PrimerCardFormSession

Primer Checkout iOS SDK is currently in beta (v3.0.0-beta.5). The API is subject to change before the stable release.

PrimerCardFormSession is the observable session for the card payment form. It publishes the current PrimerCardFormState and exposes field update methods, co-badge network selection, and submission controls. The session is created by the SDK and injected into every PrimerCardForm slot closure. Read state to render your UI and call the session’s methods to mutate the form.

@available(iOS 15.0, *)
@MainActor
public final class PrimerCardFormSession: ObservableObject

You never instantiate PrimerCardFormSession yourself. Each PrimerCardForm slot (cardDetails, billingAddress, submitButton) receives the session as a closure parameter. Observe it with @ObservedObject.

Accessing the session

The session is passed to each PrimerCardForm slot. Capture it and observe state to drive your UI:

PrimerCardForm(
    submitButton: { session in
        Button("Pay") { session.submit() }
            .disabled(!session.state.isValid || session.state.isLoading)
    }
)

To observe state changes inside a custom subview, mark the captured session as @ObservedObject:

struct SubmitButton: View {
    @ObservedObject var session: PrimerCardFormSession

    var body: some View {
        Button("Pay") { session.submit() }
            .disabled(!session.state.isValid || session.state.isLoading)
    }
}

Property

Property	Type	Description
`state`	`PrimerCardFormState`	The latest card form state. `@Published private(set)` — read-only, observe it through `@ObservedObject`. Contains field values, validation errors, loading state, network selection, and surcharge information.

Methods

Field update methods

Each setter forwards a raw string to the form. The session re-validates and re-publishes state after every update. Updating the card number triggers network detection and may populate state.availableNetworks and state.binData.

Method	Description
`updateCardNumber(_ value: String)`	Updates the card number. Triggers network detection.
`updateCvv(_ value: String)`	Updates the CVV / security code.
`updateExpiryDate(_ value: String)`	Updates the expiry date (MM/YY).
`updateCardholderName(_ value: String)`	Updates the cardholder name.
`updatePostalCode(_ value: String)`	Updates the billing postal / ZIP code.
`updateCountryCode(_ value: String)`	Updates the billing country code (ISO 3166-1 alpha-2).
`updateCity(_ value: String)`	Updates the billing city.
`updateState(_ value: String)`	Updates the billing state / region.
`updateAddressLine1(_ value: String)`	Updates billing address line 1.
`updateAddressLine2(_ value: String)`	Updates billing address line 2.
`updatePhoneNumber(_ value: String)`	Updates the billing phone number.
`updateFirstName(_ value: String)`	Updates the billing first name.
`updateLastName(_ value: String)`	Updates the billing last name.

Every setter drives the field the customer sees. The value you set becomes what the field displays, and the form re-validates it so a prefilled field does not hold back the submit button. The card number shows formatted, the same way typing it would. updateCountryCode also resolves the country picker’s selection from the ISO code. See Pre-fill cardholder name. Writes and reads are asymmetric on purpose. updateCardNumber and updateCvv accept a raw value and show it in the SDK-rendered field, but the card number and CVV are never handed back to your code: state.data carries a masked card number and an empty CVV.

If your code passes a card number or CVV to these setters, your application handles cardholder data, and your PCI DSS obligations can change. Confirm your scope with your acquirer or a qualified assessor before you collect card data in your own UI. If you use only the SDK-rendered card fields and never call these two setters, this warning does not apply to you.

Network selection

Method	Description
`selectCardNetwork(_ network: PrimerCardNetwork)`	Selects a network for co-badged cards. Applicable only when `state.availableNetworks` contains more than one network. See PrimerCardNetwork.

Lifecycle

Method	Description
`submit()`	Submits the form for tokenization and payment. Sets `state.isLoading` to `true` during submission.
`cancel()`	Cancels the active card form flow.

When wiring custom TextFields, drive each field with the matching update* method. You can round-trip through session.state.data for every field except the card number and the CVV: that map is the merchant-facing state, so the card number reads back masked (424242••••••4242) and the CVV reads back empty. Binding a custom card-number field to it would feed the mask straight back into the form on the next keystroke.

Never bind a custom card number or CVV field to session.state.data. Hold your own @State for those two and write one way, into the session.

struct CustomCardFields: View {
    @State private var cardNumber = ""

    var body: some View {
        PrimerCardForm(
            cardDetails: { session in
                // Card number: one-way. Your own state is the source of truth.
                TextField("Card number", text: $cardNumber)
                    .onChange(of: cardNumber) { session.updateCardNumber($0) }

                // Non-PCI fields can round-trip through the form state.
                TextField("Name on card", text: Binding(
                    get: { session.state.data[.cardholderName] },
                    set: { session.updateCardholderName($0) }
                ))
            }
        )
    }
}

PrimerCardFormState

@available(iOS 15.0, *)
public struct PrimerCardFormState: Equatable

The complete state of the card payment form: configuration, current field values, validation errors, loading and validity flags, co-badge network selection, and surcharge information.

Properties

Property	Type	Description
`configuration`	`CardFormConfiguration`	Which fields the form requires. See CardFormConfiguration.
`data`	`FormData`	Current field values keyed by `PrimerInputElementType`. See FormData.
`fieldErrors`	`[FieldError]`	Validation errors per field. Empty when there are no errors. See FieldError.
`isLoading`	`Bool`	`true` while a payment is being submitted.
`isValid`	`Bool`	`true` when all required fields pass validation. Updates in real time.
`selectedCountry`	`PrimerCountry?`	Selected billing country, or `nil`. See PrimerCountry.
`selectedNetwork`	`PrimerCardNetwork?`	Currently selected network for co-badged cards, or `nil`.
`availableNetworks`	`[PrimerCardNetwork]`	Card networks detected from the card number. More than one indicates a co-badged card.
`surchargeAmountRaw`	`Int?`	Surcharge amount in the smallest currency unit (e.g. cents), or `nil`.
`surchargeAmount`	`String?`	Formatted surcharge amount for display, or `nil`.
`binData`	`PrimerBinData?`	BIN metadata detected from the card number, or `nil`.

Convenience properties

Property	Type	Description
`displayFields`	`[PrimerInputElementType]`	All fields that should be rendered (card fields plus billing fields when enabled).

Helper methods

Method	Description
`hasError(for fieldType: PrimerInputElementType) -> Bool`	Returns `true` when the given field currently has a validation error.
`errorMessage(for fieldType: PrimerInputElementType) -> String?`	Returns the human-readable error message for the field, or `nil` when there is none.

PrimerCardForm(
    cardDetails: { session in
        VStack(alignment: .leading) {
            CardFormDefaults.cardNumber(session)
            if session.state.hasError(for: .cardNumber),
               let message = session.state.errorMessage(for: .cardNumber) {
                Text(message).foregroundColor(.red)
            }
        }
    }
)

Validation errors surface in fieldErrors after the form evaluates a field. Use isValid to gate the submit button and errorMessage(for:) to display per-field messages. See ValidationResult.

CardFormConfiguration

@available(iOS 15.0, *)
public struct CardFormConfiguration: Equatable

Declares which fields the card form requires.

Property	Type	Description
`cardFields`	`[PrimerInputElementType]`	Card-specific fields (card number, expiry, CVV, cardholder name).
`billingFields`	`[PrimerInputElementType]`	Billing address fields. Empty when billing address collection is disabled.
`requiresBillingAddress`	`Bool`	`true` when billing address collection is enabled.
`allFields`	`[PrimerInputElementType]`	Computed: `cardFields + billingFields`.

public init(
    cardFields: [PrimerInputElementType],
    billingFields: [PrimerInputElementType] = [],
    requiresBillingAddress: Bool = false
)

The static CardFormConfiguration.default requires [.cardNumber, .expiryDate, .cvv, .cardholderName] with no billing fields.

FormData

@available(iOS 15.0, *)
public struct FormData: Equatable

Type-safe container for field values keyed by PrimerInputElementType. Subscript access returns an empty string for unset fields.

Member	Type	Description
`subscript(fieldType: PrimerInputElementType)`	`String`	Reads or writes the value for a field. Returns `""` when unset.
`dictionary`	`[PrimerInputElementType: String]`	All current field values as a dictionary.

let cardNumber = session.state.data[.cardNumber]
let allValues = session.state.data.dictionary

FieldError

@available(iOS 15.0, *)
public struct FieldError: Equatable, Identifiable

A validation error for a specific form field.

Property	Type	Description
`id`	`PrimerInputElementType`	Stable identifier (the field type) for SwiftUI diffing.
`fieldType`	`PrimerInputElementType`	The field that has the error.
`message`	`String`	Human-readable error message to display.
`errorCode`	`String?`	Machine-readable error code for programmatic handling, or `nil`.

ForEach(session.state.fieldErrors) { error in
    Text(error.message)
}

PrimerInputElementType

The field identifier used throughout PrimerCardFormState (in configuration, data, and fieldErrors).

Case	Field
`.cardNumber`	Card number
`.expiryDate`	Expiry date (MM/YY)
`.cvv`	CVV / security code
`.cardholderName`	Cardholder name
`.postalCode`	Billing postal code
`.countryCode`	Billing country
`.city`	Billing city
`.state`	Billing state / region
`.addressLine1`	Billing address line 1
`.addressLine2`	Billing address line 2
`.phoneNumber`	Billing phone number
`.firstName`	Billing first name
`.lastName`	Billing last name
`.email`	Email address
`.otp`	One-time passcode
`.retailer`	Retailer
`.all`	All fields
`.unknown`	Unknown / unspecified

PrimerCardForm

The card form component and its customizable slots.

Card field components

Prebuilt field views from CardFormDefaults.

ValidationResult

Field validation model and error handling.

PrimerCountry

Country model for billing address selection.

​Accessing the session

​Property

​Methods

​Field update methods

​Network selection

​Lifecycle

​PrimerCardFormState

​Properties

​Convenience properties

​Helper methods

​CardFormConfiguration

​FormData

​FieldError

​PrimerInputElementType

​See also

PrimerCardForm

Card field components

ValidationResult

PrimerCountry

Accessing the session

Property

Methods

Field update methods

Network selection

Lifecycle

PrimerCardFormState

Properties

Convenience properties

Helper methods

CardFormConfiguration

FormData

FieldError

PrimerInputElementType

See also