API Reference - Primer

Primer Checkout iOS SDK is currently in beta (v3.0.0-beta.1). 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
`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 for light and dark mode
`SpacingOverrides`	Spacing values for padding and margins
`TypographyOverrides`	Font sizes, weights, and line heights
`RadiusOverrides` / `BorderWidthOverrides` / `SizeOverrides`	Corner radius, border widths, and component sizes

Common Objects

Component	Description
`PrimerSettings`	SDK configuration (payment handling mode, options)
`PrimerError`	Error details with diagnostics ID and recovery suggestion
`ValidationResult`	Field validation result with error details
`PrimerCardNetwork`	Card network type for co-badged card selection
`PrimerCountry`	Country data used for billing address selection

Session pattern

The iOS SDK exposes one managed entry point and one composable entry point. Both are built on the same observable PrimerCheckoutSession, which owns the checkout lifecycle: it loads the client session, tracks the lifecycle Phase, and delivers the final PrimerCheckoutState.

Composable (inline)

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

@StateObject private var session = PrimerCheckoutSession(clientToken: token)

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

Each composable view receives its session as a slot parameter so you can read state and call actions from your custom UI:

Session	Resolved by	Exposes
`PrimerCheckoutSession`	`.primerCheckoutSession(_:onCompletion:)`	`phase`, `onBeforePaymentCreate`, `idempotencyKey`
`PrimerCardFormSession`	`PrimerCardForm` slots	Card field mutations, `submit()`, `cancel()`
`PrimerSelectionSession`	`PrimerPaymentMethods` / `PrimerVaultedPaymentMethods` slots	`select(_:)`, `selectVaulted(_:)`, `delete(_:)`, `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