> ## Documentation Index
> Fetch the complete documentation index at: https://primer.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Complete API reference for the Primer Checkout iOS SDK

> [!WARNING]
>
> 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`](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/primer-checkout) | Managed SwiftUI view that renders the SDK's default checkout screens |
| [`PrimerCheckoutSession`](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/primer-checkout-session) | Observable session that owns the checkout lifecycle for composable, inline checkout |
| [`PrimerCheckoutState`](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/primer-checkout-state) | Enum representing checkout lifecycle states (`initializing`, `ready`, `success`, `failure`, `dismissed`) |
| [`PrimerCheckoutPresenter`](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/primer-checkout-presenter) | UIKit entry point that presents the managed checkout modally with a delegate |

## Card Form

| Component | Description |
| - | - |
| [`PrimerCardForm`](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/card-form/primer-card-form) | Card payment form view with `@ViewBuilder` slots for card details, billing address, and submit |
| [`PrimerCardFormSession`](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/card-form/card-form-session) | Observable session exposing card-form state, field mutations, and the submit action |
| [`CardFormDefaults`](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/card-form/card-form-defaults) | Pre-built slot bodies and per-field building blocks for custom card form layouts |
| [Card Field Components](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/card-form/card-field-components.md) | Individual field building blocks (`cardNumber`, `expiryDate`, `cvv`, `cardholderName`, etc.) |

## Payment Methods

| Component | Description |
| - | - |
| [`PrimerPaymentMethods`](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/payment-methods/primer-payment-methods) | Payment method list view with `@ViewBuilder` slots for header, method row, and empty state |
| [`PrimerSelectionSession`](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/payment-methods/payment-methods-session) | Observable session exposing the selection state and selection actions |
| [`PaymentMethodsDefaults`](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/payment-methods/payment-methods-defaults) | Pre-built slot bodies for custom payment method layouts |
| [`VaultedPaymentMethodsDefaults`](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/payment-methods/vaulted-payment-methods) | Pre-built header, item, and submit bodies for `PrimerVaultedPaymentMethods` |
| [`PrimerVaultedPaymentMethods`](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/payment-methods/vaulted-payment-methods) | Saved payment methods view with slots for header, item, and submit |

## Theming

| Component | Description |
| - | - |
| [`PrimerCheckoutTheme`](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/theming/primer-theme) | Root theme container holding all design token override groups |
| [`ColorOverrides`](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/theming/color-tokens) | Color token overrides, passed as `colors` (light mode) and `darkColors` (dark mode) |
| [`SpacingOverrides`](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/theming/spacing-tokens) | Spacing values for padding and margins |
| [`TypographyOverrides`](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/theming/typography-tokens) | Font sizes, weights, and line heights |
| [`RadiusOverrides` / `WidthOverrides` / `SizeOverrides`](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/theming/shape-tokens) | Corner radius, border widths per field state, and component sizes |

## Common Objects

| Component | Description |
| - | - |
| [`PrimerSettings`](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/common/primer-settings) | SDK configuration (payment handling mode, options) |
| [`PrimerError`](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/common/primer-error) | Error details with diagnostics ID and recovery suggestion |
| [`FieldError`](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/common/validation-result) | Validation error for a single card-form field, read from `PrimerCardFormState` |
| [`PrimerCardNetwork`](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/common/primer-card-network) | Card network type for co-badged card selection |
| [`PrimerCountry`](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/common/primer-country) | Country data used for billing address selection |

## Session pattern

The iOS SDK offers a managed checkout and a composable one. The managed checkout, [`PrimerCheckout`](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/primer-checkout) in SwiftUI or [`PrimerCheckoutPresenter`](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/primer-checkout-presenter) from UIKit, builds its own checkout and needs no session. An observable [`PrimerCheckoutSession`](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/primer-checkout-session) drives the composable views and owns the checkout lifecycle. It loads the [client session](https://primer.io/docs/checkout/client-session.md) and tracks the lifecycle [`Phase`](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/primer-checkout-session). In SwiftUI, outcomes reach your `onCompletion` handler as [`PrimerCheckoutState`](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/primer-checkout-state). `.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`](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/card-form/primer-card-form), [`PrimerPaymentMethods`](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/payment-methods/primer-payment-methods), and [`PrimerVaultedPaymentMethods`](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/payment-methods/vaulted-payment-methods) — 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`.

```swift theme={"dark"}
@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`](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/primer-checkout-session) | `.primerCheckoutSession(_:theme:onCompletion:)` | `phase`, `clientSession`, `cardForm`, `selection`, `onBeforePaymentCreate`, `onShippingAddressChange`, `onShippingOptionChange`, `idempotencyKey`, `formatAmount(_:)`, `refresh()`, `cancel()` |
| [`PrimerCardFormSession`](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/card-form/card-form-session) | `PrimerCardForm` slots | `state`, card field mutations, `selectCardNetwork(_:)`, `setVaultOnSuccess(_:)`, `submit()`, `cancel()` |
| [`PrimerSelectionSession`](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/payment-methods/payment-methods-session) | `PrimerPaymentMethods` / `PrimerVaultedPaymentMethods` slots | `select(_:)`, `selectVaulted(_:)` (pays), `delete(_:)`, `showAll()`, `cancel()` |

> [!NOTE]
>
> Sessions are `@MainActor` `ObservableObject`s. 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.

### Managed (modal)

For a turnkey flow that renders the SDK's default screens, use [`PrimerCheckout`](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/primer-checkout) in SwiftUI, or [`PrimerCheckoutPresenter`](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/primer-checkout-presenter) from UIKit.

```swift theme={"dark"}
PrimerCheckout(clientToken: token) { state in
    handle(state)
}
```

```swift theme={"dark"}
PrimerCheckoutPresenter.shared.delegate = self
PrimerCheckoutPresenter.presentCheckout(clientToken: token, from: self)
```

> [!TIP]
>
> 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.

## See also

> [card] [PrimerCheckoutSession](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/primer-checkout-session.md)
>
> Own the checkout lifecycle for inline, composable checkout.

> [card] [PrimerCheckout](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/primer-checkout.md)
>
> Drop in the managed SwiftUI checkout view.

> [card] [PrimerCardForm](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/card-form/primer-card-form.md)
>
> Build a custom card form with @ViewBuilder slots.

> [card] [Handle payment result](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/guides/handle-payment-result.md)
>
> React to the final PrimerCheckoutState.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.