PrimerCheckoutSession

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

PrimerCheckoutSession is the owner of a CheckoutComponents session. You hold it (typically as a @StateObject) and wire it into your SwiftUI view hierarchy with the .primerCheckoutSession(_:theme:onCompletion:) modifier. The session builds the SDK, runs client-token initialization, creates the checkout scope, and bridges per-method scopes into observable session objects that the composable views (such as PrimerCardForm and PrimerPaymentMethods) consume from the environment. The same session powers both the managed modal PrimerCheckout and fully inline embedding: any Primer composable view placed under the modifier resolves its session from the environment. While the session is .ready, the SDK presents its own follow-up screens (processing, success and failure, plus saved-method management and CVV recapture) in a sheet over your layout. See What the modifier provides.

This is the iOS analog of the Android PrimerCheckoutHost. Where Android wraps your layout in a composable host, iOS wires the session into the environment with a view modifier — child composable views read their per-feature session from EnvironmentValues.

Declaration

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

Initializer

public init(
    clientToken: String,
    settings: PrimerSettings = PrimerSettings(),
    theme: PrimerCheckoutTheme = PrimerCheckoutTheme(),
    idempotencyKey: @escaping @Sendable () -> String? = { nil }
)

Parameter	Type	Default	Description
`clientToken`	`String`	Required	The client token from your `POST /client-session` call. See Client session.
`settings`	`PrimerSettings`	`PrimerSettings()`	SDK configuration applied to this session.
`theme`	`PrimerCheckoutTheme`	`PrimerCheckoutTheme()`	Design tokens applied to all SDK components within the session.
`idempotencyKey`	`@Sendable () -> String?`	`{ nil }`	Declarative idempotency-key provider, invoked once per payment attempt just before the SDK creates the payment. Return `nil` to opt out. Ignored when `onBeforePaymentCreate` is set.

Phase

The lifecycle phase of the session. Terminal outcomes (success, failure, dismissed) are not delivered here — they are delivered through the modifier’s onCompletion.

public enum Phase: Equatable {
    case initializing
    case ready
}

Case	Description
`initializing`	The session is building the SDK and running client-token initialization. Child sessions (`cardForm`, `selection`) are `nil`.
`ready`	Initialization completed. Child sessions resolve and the composable views render.

Published properties

Property	Type	Description
`phase`	`Phase`	The current lifecycle phase. Declared `@Published public private(set)` — observe it, but only the session mutates it.
`clientSession`	`PrimerClientSession?`	The resolved client session — order total, currency, line items, customer, fees. `nil` until the session reaches `.ready`, then non-`nil` for the rest of the session. Declared `@Published public private(set)`.

This is how you read the order the customer is paying for:

struct OrderSummary: View {
  @ObservedObject var session: PrimerCheckoutSession

  var body: some View {
    if let clientSession = session.clientSession {
      VStack(alignment: .leading) {
        if let amount = clientSession.totalAmount,
           let formatted = session.formatAmount(amount) {
          Text("Total: \(formatted)")
        }
        ForEach(clientSession.lineItems ?? [], id: \.itemId) { item in
          Text(item.itemDescription ?? "")
        }
      }
    }
  }
}

Properties

Property	Type	Description
`onBeforePaymentCreate`	`BeforePaymentCreateHandler?`	Called before a payment is created. Use the decision handler to provide an idempotency key or abort payment creation. Mutations are forwarded to the checkout scope immediately, so assigning after the session reaches `.ready` still takes effect for the next payment attempt.
`idempotencyKey`	`@Sendable () -> String?`	Declarative idempotency-key provider, invoked once per payment attempt just before the SDK creates the payment. Return `nil` (default) to opt out. Ignored when `onBeforePaymentCreate` is set. Mutations are forwarded to the checkout scope immediately, so post-`.ready` assignment still applies.
`cardForm`	`PrimerCardFormSession?`	The card-form sub-session, lazily created and cached. Non-`nil` only once `phase == .ready`.
`selection`	`PrimerSelectionSession?`	The payment-method-selection sub-session, lazily created and cached. Non-`nil` only once `phase == .ready`.

onBeforePaymentCreate uses the BeforePaymentCreateHandler type:

public typealias BeforePaymentCreateHandler = @Sendable (
    _ data: PrimerCheckoutPaymentMethodData,
    _ decisionHandler: @escaping (PrimerPaymentCreationDecision) -> Void
) -> Void

If you set onBeforePaymentCreate, the declarative idempotencyKey provider is ignored — use the decision handler to supply the key instead.

Methods

Method	Description
`start() async`	Builds the SDK and drives the session to `.ready`. Idempotent — repeated calls are ignored once initialization has started. The modifier calls this for you on appear.
`refresh() async`	Re-fetches configuration and payment methods from the backend and returns the session to `.ready`. No-op unless the session has finished initializing; concurrent calls are ignored. Failures are delivered via `onCompletion`.
`cancel()`	Tears the session down: dismisses the checkout scope, clears resources, drops cached sub-sessions, and resets to a restartable state. Idempotent. The modifier wires this to `onDisappear`.
`formatAmount(_ amountInMinorUnits: Int) -> String?`	Formats an amount in minor units the way the SDK’s own screens do. `nil` before the session reaches `.ready`, when no currency is known yet.

formatAmount(_:)

public func formatAmount(_ amountInMinorUnits: Int) -> String?

Formats an amount in minor units for display, so a total you print yourself matches what the SDK prints on its own screens. The currency comes from the client session. Its decimal digits come from the backend and cannot be worked out from PrimerClientSession.currencyCode alone, because some currencies have none and some have three. The locale is the one in PrimerSettings.localeData, which defaults to the device.

if let total = session.clientSession?.totalAmount,
   let formatted = session.formatAmount(total) {
  Text("Pay \(formatted)")
}

Parameter	Type	Description
`amountInMinorUnits`	`Int`	The amount in the currency’s minor units, for example cents.

Returns nil before the session reaches .ready.

You normally never call start() or cancel() yourself — the .primerCheckoutSession modifier handles the lifecycle. Call refresh() when you need to reload after a client-session update (for example, an amount or currency change).

View modifier

The View.primerCheckoutSession(_:theme:onCompletion:) modifier wires a PrimerCheckoutSession into the SwiftUI environment, bootstraps it on appear, and tears it down on disappear. Apply it once around any Primer composable views — whether presented modally via PrimerCheckout or embedded inline in your own layout.

@available(iOS 15.0, *)
public extension View {
    func primerCheckoutSession(
        _ session: PrimerCheckoutSession,
        theme: PrimerCheckoutTheme? = nil,
        onCompletion: ((PrimerCheckoutState) -> Void)? = nil
    ) -> some View
}

Parameter	Type	Default	Description
`session`	`PrimerCheckoutSession`	Required	The session injected into the environment for child composable views to resolve.
`theme`	`PrimerCheckoutTheme?`	`nil`	Overrides the theme the session was created with, re-applied whenever the value changes. Use it to follow a theme your own view state owns, for example a brand or colour-scheme switch.
`onCompletion`	`((PrimerCheckoutState) -> Void)?`	`nil`	Receives the outcome states. `.success` and `.dismissed` arrive at most once and end the session; a `.failure` after `.ready` is one failed attempt and does not, so this may be called again if the customer retries. See `PrimerCheckoutState`.

What the modifier provides

Environment injection — exposes the PrimerCheckoutSession, the derived PrimerCardFormSession, and the PrimerSelectionSession through EnvironmentValues, so child views like PrimerCardForm and PrimerPaymentMethods resolve their per-feature session automatically.
Lifecycle bootstrapping — calls start() on appear and cancel() on disappear.
Overlay management — once the session is .ready, the modifier presents the SDK’s own follow-up screens in a sheet over your layout: processing, success and failure after any payment you start, the screens of payment methods that need one, the saved-methods list opened by showAll() with its delete confirmation, and the CVV recapture screen that selectVaulted(_:) raises when a saved card needs it. 3DS challenges and web redirects open their own system UI. Do not present a sheet of your own while one of these is up.

Without the .primerCheckoutSession modifier above them in the hierarchy, composable views such as PrimerCardForm and PrimerPaymentMethods cannot resolve a session and will not function.

Usage

Hold the session as a @StateObject, place the composable views in a ScrollView, and attach the modifier with your completion handler.

import SwiftUI
import PrimerSDK

@available(iOS 15.0, *)
struct CheckoutView: View {
    @StateObject private var session: PrimerCheckoutSession

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

    var body: some View {
        ScrollView {
            VStack(spacing: 24) {
                PrimerCardForm()
                PrimerPaymentMethods()
            }
            .padding()
        }
        .primerCheckoutSession(session) { state in
            switch state {
            case .success(let data):
                print("Payment complete: \(data)")
            case let .failure(error, _):
                print("Payment failed: \(error)")
            case .dismissed:
                print("Checkout dismissed")
            default:
                break
            }
        }
    }
}

The child composable views resolve their per-feature session from the environment — you do not pass a session into them. Behind the scenes the modifier injects PrimerCardFormSession and PrimerSelectionSession, which PrimerCardForm and PrimerPaymentMethods bind to once the session reaches .ready.

Supplying an idempotency key

Provide the declarative idempotencyKey provider at construction, or assign onBeforePaymentCreate for full control over the payment-creation decision. Either may be assigned after .ready — the change applies to the next payment attempt.

let session = PrimerCheckoutSession(
    clientToken: token,
    idempotencyKey: { UUID().uuidString }
)

PrimerCheckout

The managed modal entry point powered by the same session.

PrimerCardForm

Composable card form that resolves its session from the environment.

PrimerPaymentMethods

Composable payment-method selection list for inline layouts.

PrimerCheckoutState

The terminal outcome delivered to onCompletion.

​Declaration

​Initializer

​Phase

​Published properties

​Properties

​Methods

​formatAmount(_:)

​View modifier

​What the modifier provides

​Usage

​Supplying an idempotency key

​See also

PrimerCheckout

PrimerCardForm

PrimerPaymentMethods

PrimerCheckoutState

Declaration

Initializer

Phase

Published properties

Properties

Methods

formatAmount(_:)

View modifier

What the modifier provides

Usage

Supplying an idempotency key

See also