PrimerCheckoutState

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

PrimerCheckoutState is a public, Equatable enum that represents the current state of the checkout flow. It captures both the lifecycle of the session (initializing, ready) and its terminal outcome (success, failure, dismissed). Your onCompletion closure on PrimerCheckout or on the .primerCheckoutSession(_:onCompletion:) modifier receives outcome states only — .success, .failure, or .dismissed. The lifecycle states .initializing and .ready are part of the enum’s definition but are never delivered to onCompletion; they describe internal progress the SDK drives on your behalf. .success and .dismissed end the session and are delivered at most once. .failure depends on when it happens: once the checkout is ready, a failed payment attempt does not end the session — the SDK shows its error screen, offers a retry, and your closure is called again with the outcome of each further attempt. Only a failure that occurs before the checkout becomes ready is terminal.

Do not treat the first .failure as the end of the session. If you tear down your checkout UI on it, a customer who retries after a decline and then succeeds will never reach your success handling. Tear down on .success and .dismissed.

On iOS, a single PrimerCheckoutState enum covers what the Android SDK splits across PrimerCheckoutState (lifecycle) and PrimerCheckoutEvent (outcomes). The .initializing and .ready cases mirror the lifecycle; .success, .failure, and .dismissed mirror the outcome events delivered to onCompletion.

Definition

@available(iOS 15.0, *)
public enum PrimerCheckoutState: Equatable {
    case initializing
    case ready(clientSession: PrimerClientSession)
    case success(PaymentResult)
    case dismissed
    case failure(PrimerError)
}

States

State	Associated values	Description
`.initializing`	—	Initial state while loading configuration and payment methods. The SDK is fetching the client session and preparing available payment methods.
`.ready`	`PrimerClientSession`	Checkout is fully initialized and payment methods are loaded. Carries the client session — order total, currency, line items, customer, fees.
`.success`	`PaymentResult`	Payment completed successfully. Carries the full payment result with payment ID, status, and other details.
`.dismissed`	—	Terminal state. Checkout was dismissed by user action or programmatically without completing a payment.
`.failure`	`PrimerError`	Payment or checkout failed. Carries the specific error with diagnostics information for debugging.

`.ready` associated values

Parameter	Type	Description
`clientSession`	`PrimerClientSession`	The resolved client session: order total, currency, line items, order and customer details, allowed card networks, and fees.

Because .ready is never delivered to onCompletion, read the client session from the session object instead — PrimerCheckoutSession.clientSession is @Published and becomes non-nil as soon as the checkout is ready:

@StateObject private var session = PrimerCheckoutSession(clientToken: clientToken)
...
if let clientSession = session.clientSession {
    Text(formatted(clientSession.totalAmount, clientSession.currencyCode))
}

This requires the inline integration. PrimerCheckout — the managed modal — renders the SDK’s own screens and exposes no session object, so the client session is not reachable from it.

Lifecycle

A checkout session progresses from the lifecycle states to an outcome. .success and .dismissed end it; a .failure after .ready does not:

initializing → ready → success | dismissed        (session over)
                 ↑ ↓
               failure                            (retryable — session continues)

Transition	When	Ends the session
`.initializing` → `.ready`	Configuration and payment methods have loaded.	—
`.initializing` → `.failure`	Initialization fails (bad client token, network, configuration).	Yes
`.ready` → `.success`	Payment is confirmed by the processor (automatic payment handling).	Yes
`.ready` → `.failure`	A payment attempt fails. The SDK shows its error screen and the customer can retry; a further attempt delivers another outcome.	No
`→ .dismissed`	The user closes checkout, or you dismiss it programmatically, without completing a payment.	Yes

.success and .dismissed are delivered at most once per session. .failure is terminal only before .ready; after that it is delivered once per failed attempt. The lifecycle states .initializing and .ready are never passed to onCompletion.

Handling completion

Pass an onCompletion closure when you present checkout. It receives the outcome states — .success, .failure, or .dismissed — and may be called more than once if a payment attempt fails and the customer retries.

import SwiftUI
import PrimerSDK

struct CheckoutView: View {
    @StateObject private var session = PrimerCheckoutSession(clientToken: clientToken)

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

    private func handle(_ state: PrimerCheckoutState) {
        switch state {
        case let .success(result):
            print("Payment \(result.paymentId) succeeded")
        case let .failure(error):
            print("Checkout failed: \(error.localizedDescription)")
        case .dismissed:
            print("Checkout dismissed")
        default:
            // .initializing and .ready are lifecycle states and are
            // never delivered here.
            break
        }
    }
}

onCompletion only delivers terminal states, but a switch on PrimerCheckoutState must still be exhaustive. Cover the lifecycle cases with a default: (or @unknown default:) so future state additions don’t break compilation.

PaymentResult

PaymentResult is the value carried by .success. It is a public, Sendable, Equatable struct describing the completed payment.

public struct PaymentResult: Sendable, Equatable {
    public let paymentId: String
    public let status: PaymentStatus
    public let token: String?
    public let redirectUrl: String?
    public let errorMessage: String?
    public let amount: Int?
    public let currencyCode: String?
    public let paymentMethodType: String?
}

Property	Type	Description
`paymentId`	`String`	Unique payment identifier assigned by Primer.
`status`	`PaymentStatus`	The final status of the payment.
`token`	`String?`	The payment method token, when available.
`redirectUrl`	`String?`	A redirect URL associated with the payment, when applicable.
`errorMessage`	`String?`	A human-readable error message, when the payment did not complete cleanly.
`amount`	`Int?`	The payment amount in minor units, when available.
`currencyCode`	`String?`	The ISO 4217 currency code, when available.
`paymentMethodType`	`String?`	The payment method type identifier used for the payment (e.g., `"PAYMENT_CARD"`).

PaymentStatus

PaymentStatus is a public, Sendable enum describing the final status of a payment.

public enum PaymentStatus: Sendable {
    case pending
    case success
    case failed
}

Case	Description
`.pending`	The payment is pending and awaiting further processing or confirmation.
`.success`	The payment completed successfully.
`.failed`	The payment failed.

Always include a default: (or @unknown default:) case when switching on PaymentStatus to handle future additions.

Handling the result

Use the .success payload to read the payment details and route your UI:

private func handleCompletion(_ state: PrimerCheckoutState) {
    switch state {
    case let .success(result):
        switch result.status {
        case .success:
            showReceipt(paymentId: result.paymentId)
        case .pending:
            showPendingScreen(paymentId: result.paymentId)
        case .failed:
            showErrorScreen(message: result.errorMessage)
        @unknown default:
            break
        }
    case let .failure(error):
        // Not the end of the session: the customer can retry, and this
        // closure will be called again with the next attempt's outcome.
        showErrorScreen(message: error.localizedDescription)
    case .dismissed:
        dismiss()
    default:
        // .initializing and .ready are lifecycle states and are
        // never delivered to onCompletion.
        break
    }
}

For a full integration walkthrough, see Handle payment result.

PrimerClientSession

The resolved client session, carried by .ready and published on PrimerCheckoutSession.clientSession.

@objc public final class PrimerClientSession: NSObject, Codable {
    public let customerId: String?
    public let orderId: String?
    public let currencyCode: String?
    public let totalAmount: Int?
    public let lineItems: [PrimerLineItem]?
    public let orderDetails: PrimerOrder?
    public let customer: PrimerCustomer?
    public let paymentMethod: PaymentMethod?
    public let fees: [PrimerFee]?
}

Property	Type	Description
`customerId`	`String?`	Customer identifier from your system.
`orderId`	`String?`	Order identifier from your system.
`currencyCode`	`String?`	ISO 4217 currency code (e.g., `"USD"`, `"EUR"`).
`totalAmount`	`Int?`	Total amount in minor currency units (e.g., `1000` = $10.00).
`lineItems`	`[PrimerLineItem]?`	The order’s line items.
`orderDetails`	`PrimerOrder?`	Country code and shipping details.
`customer`	`PrimerCustomer?`	Customer contact details, billing and shipping address.
`paymentMethod`	`PaymentMethod?`	Payment-method configuration — currently the allowed card networks.
`fees`	`[PrimerFee]?`	Fees applied to the order, such as surcharges.

Every property is optional because the client session itself is merchant-configured — a session created without line items has none. Read them defensively rather than assuming a shape.

PrimerLineItem

Property	Type	Description
`itemId`	`String?`	Your identifier for the item.
`itemDescription`	`String?`	Human-readable description.
`amount`	`Int?`	Unit amount in minor units.
`discountAmount`	`Int?`	Discount applied to this item, in minor units.
`quantity`	`Int?`	Number of units.
`taxCode`	`String?`	Tax code for this item.
`taxAmount`	`Int?`	Tax charged on this item, in minor units.

taxCode and taxAmount are per line item. Do not read the order’s total tax from them — a three-item order reports each item’s own tax, and the values will not sum to a field you can find elsewhere on the session unless your client session was configured that way.

PrimerOrder

Property	Type	Description
`countryCode`	`String?`	The order’s ISO 3166-1 alpha-2 country code.
`shipping`	`PrimerShipping?`	Shipping `amount`, plus the selected method’s `methodId`, `methodName`, and `methodDescription`.

PrimerCustomer

Property	Type	Description
`emailAddress`	`String?`	Customer email.
`mobileNumber`	`String?`	Customer phone number.
`firstName` / `lastName`	`String?`	Customer name.
`billingAddress`	`PrimerAddress?`	Billing address.
`shippingAddress`	`PrimerAddress?`	Shipping address.

PrimerAddress

Property	Type	Description
`firstName` / `lastName`	`String?`	Name on the address.
`addressLine1` / `addressLine2`	`String?`	Street address.
`city`	`String?`	City.
`state`	`String?`	State, province, or region.
`countryCode`	`String?`	ISO 3166-1 alpha-2 country code.
`postalCode`	`String?`	Postal or ZIP code.

PaymentMethod

Property	Type	Description
`orderedAllowedCardNetworks`	`[CardNetwork]`	Card networks the client session allows, in the configured order. A network the SDK does not recognise becomes `.unknown` rather than being dropped, so the list always matches what the session declared.

PrimerFee

Property	Type	Description
`type`	`String`	The fee type as configured, e.g. `"SURCHARGE"`. A raw string rather than an enum, so an unrecognised type surfaces instead of failing to decode.
`amount`	`Int`	The fee amount in minor units.

PrimerCheckout

Present checkout and receive the final state through onCompletion.

PrimerError

Error details carried by the .failure state.

Handle payment result

Route your UI based on the checkout outcome.

PrimerCheckoutSession

Drive the inline checkout lifecycle from your own layout.

​Definition

​States

​.ready associated values

​Lifecycle

​Handling completion

​PaymentResult

​PaymentStatus

​Handling the result

​PrimerClientSession

​PrimerLineItem

​PrimerOrder

​PrimerCustomer

​PrimerAddress

​PaymentMethod

​PrimerFee

​See also

PrimerCheckout

PrimerError

Handle payment result

PrimerCheckoutSession

Definition

States

`.ready` associated values

Lifecycle

Handling completion

PaymentResult

PaymentStatus

Handling the result

PrimerClientSession

PrimerLineItem

PrimerOrder

PrimerCustomer

PrimerAddress

PaymentMethod

PrimerFee

See also