API Reference - Primer

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

Core API

Component	Description
`PrimerCheckout`	Managed SwiftUI view that renders the SDK’s default checkout screens
`PrimerCheckoutSession`	Observable session that owns the checkout lifecycle for composable, inline checkout
`PrimerCheckoutState`	Enum representing checkout lifecycle states (`initializing`, `ready`, `success`, `failure`, `dismissed`)
`PrimerCheckoutPresenter`	UIKit entry point that presents the managed checkout modally with a delegate

Card Form

Component	Description
`PrimerCardForm`	Card payment form view with `@ViewBuilder` slots for card details, billing address, and submit
`PrimerCardFormSession`	Observable session exposing card-form state, field mutations, and the submit action
`CardFormDefaults`	Pre-built slot bodies and per-field building blocks for custom card form layouts
Card Field Components	Individual field building blocks (`cardNumber`, `expiryDate`, `cvv`, `cardholderName`, etc.)

Payment Methods

Component	Description
`PrimerPaymentMethods`	Payment method list view with `@ViewBuilder` slots for header, method row, and empty state
`PrimerSelectionSession`	Observable session exposing the selection state and selection actions
`PaymentMethodsDefaults`	Pre-built slot bodies for custom payment method layouts
`VaultedPaymentMethodsDefaults`	Pre-built header, item, and submit bodies for `PrimerVaultedPaymentMethods`
`PrimerVaultedPaymentMethods`	Saved payment methods view with slots for header, item, and submit

Theming

Component	Description
`PrimerCheckoutTheme`	Root theme container holding all design token override groups
`ColorOverrides`	Color token overrides, passed as `colors` (light mode) and `darkColors` (dark mode)
`SpacingOverrides`	Spacing values for padding and margins
`TypographyOverrides`	Font sizes, weights, and line heights
`RadiusOverrides` / `WidthOverrides` / `SizeOverrides`	Corner radius, border widths per field state, and component sizes

Common Objects

Component	Description
`PrimerSettings`	SDK configuration (payment handling mode, options)
`PrimerError`	Error details with diagnostics ID and recovery suggestion
`FieldError`	Validation error for a single card-form field, read from `PrimerCardFormState`
`PrimerCardNetwork`	Card network type for co-badged card selection
`PrimerCountry`	Country data used for billing address selection

Session pattern

The iOS SDK offers a managed checkout and a composable one. The managed checkout, PrimerCheckout in SwiftUI or PrimerCheckoutPresenter from UIKit, builds its own checkout and needs no session. An observable PrimerCheckoutSession drives the composable views and owns the checkout lifecycle. It loads the client session and tracks the lifecycle Phase. In SwiftUI, outcomes reach your onCompletion handler as PrimerCheckoutState. .failure arrives once per failed attempt. .success or .dismissed arrives at most once and ends the checkout. With the default error screen, the shopper can retry after a failed payment. If initialization fails, an inline PrimerCheckoutSession ends after that single .failure.

Composable (inline)

Hold a PrimerCheckoutSession as a @StateObject, then attach it to your view hierarchy with the .primerCheckoutSession(_:theme:onCompletion:) modifier. The composable views — PrimerCardForm, PrimerPaymentMethods, and PrimerVaultedPaymentMethods — resolve their per-feature session from the SwiftUI environment and expose slots you can override. PrimerCardForm and PrimerPaymentMethods take @ViewBuilder slots. PrimerVaultedPaymentMethods slots return AnyView, so wrap your custom content in AnyView.

@StateObject private var session: PrimerCheckoutSession

init(token: String) {
    _session = StateObject(wrappedValue: PrimerCheckoutSession(clientToken: token))
}

var body: some View {
    ScrollView {
        PrimerCardForm()
        PrimerPaymentMethods()
    }
    .primerCheckoutSession(session) { state in
        handle(state)
    }
}

The PrimerCardForm slots, the PrimerPaymentMethods header and emptyState slots, and the PrimerVaultedPaymentMethods header slot receive their session as a parameter. Use it to read state and call actions from your custom UI. The PrimerPaymentMethods method slot and the PrimerVaultedPaymentMethods item and submitButton slots receive only row data and callbacks.

Session	Provided by	Exposes
`PrimerCheckoutSession`	`.primerCheckoutSession(_:theme:onCompletion:)`	`phase`, `clientSession`, `cardForm`, `selection`, `onBeforePaymentCreate`, `onShippingAddressChange`, `onShippingOptionChange`, `idempotencyKey`, `formatAmount(_:)`, `refresh()`, `cancel()`
`PrimerCardFormSession`	`PrimerCardForm` slots	`state`, card field mutations, `selectCardNetwork(_:)`, `setVaultOnSuccess(_:)`, `submit()`, `cancel()`
`PrimerSelectionSession`	`PrimerPaymentMethods` / `PrimerVaultedPaymentMethods` slots	`select(_:)`, `selectVaulted(_:)` (pays), `delete(_:)`, `showAll()`, `cancel()`

Sessions are @MainActor ObservableObjects. Observe them with @StateObject (when you own them) or @ObservedObject (when they are passed into a slot), and read their @Published state/phase directly in your views.

For a turnkey flow that renders the SDK’s default screens, use PrimerCheckout in SwiftUI, or PrimerCheckoutPresenter from UIKit.

PrimerCheckout(clientToken: token) { state in
    handle(state)
}

PrimerCheckoutPresenter.shared.delegate = self
PrimerCheckoutPresenter.presentCheckout(clientToken: token, from: self)

Start with the managed PrimerCheckout view to get a working checkout quickly, then move to the composable views and @ViewBuilder slots when you need full control over the UI.

PrimerCheckoutSession

Own the checkout lifecycle for inline, composable checkout.

PrimerCheckout

Drop in the managed SwiftUI checkout view.

PrimerCardForm

Build a custom card form with @ViewBuilder slots.

Handle payment result

React to the final PrimerCheckoutState.

​Core API

​Card Form

​Payment Methods

​Theming

​Common Objects

​Session pattern

​Composable (inline)

​Managed (modal)

​See also

PrimerCheckoutSession

PrimerCheckout

PrimerCardForm

Handle payment result

Core API

Card Form

Payment Methods

Theming

Common Objects

Session pattern

Composable (inline)

Managed (modal)

See also