> ## 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.1).
  The API is subject to change before the stable release.
</Warning>

## Core API

| Component                                                                                | Description                                                                                              |
| ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| [`PrimerCheckout`](/docs/sdk/ios-checkout/v3.0.0-beta/api/primer-checkout)                    | Managed SwiftUI view that renders the SDK's default checkout screens                                     |
| [`PrimerCheckoutSession`](/docs/sdk/ios-checkout/v3.0.0-beta/api/primer-checkout-session)     | Observable session that owns the checkout lifecycle for composable, inline checkout                      |
| [`PrimerCheckoutState`](/docs/sdk/ios-checkout/v3.0.0-beta/api/primer-checkout-state)         | Enum representing checkout lifecycle states (`initializing`, `ready`, `success`, `failure`, `dismissed`) |
| [`PrimerCheckoutPresenter`](/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`](/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`](/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`](/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](/docs/sdk/ios-checkout/v3.0.0-beta/api/card-form/card-field-components) | Individual field building blocks (`cardNumber`, `expiryDate`, `cvv`, `cardholderName`, etc.)   |

## Payment Methods

| Component                                                                                                  | Description                                                                                |
| ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| [`PrimerPaymentMethods`](/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`](/docs/sdk/ios-checkout/v3.0.0-beta/api/payment-methods/payment-methods-session)      | Observable session exposing the selection state and selection actions                      |
| [`PaymentMethodsDefaults`](/docs/sdk/ios-checkout/v3.0.0-beta/api/payment-methods/payment-methods-defaults)     | Pre-built slot bodies for custom payment method layouts                                    |
| [`PrimerVaultedPaymentMethods`](/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`](/docs/sdk/ios-checkout/v3.0.0-beta/api/theming/primer-theme)                                        | Root theme container holding all design token override groups |
| [`ColorOverrides`](/docs/sdk/ios-checkout/v3.0.0-beta/api/theming/color-tokens)                                             | Color token overrides for light and dark mode                 |
| [`SpacingOverrides`](/docs/sdk/ios-checkout/v3.0.0-beta/api/theming/spacing-tokens)                                         | Spacing values for padding and margins                        |
| [`TypographyOverrides`](/docs/sdk/ios-checkout/v3.0.0-beta/api/theming/typography-tokens)                                   | Font sizes, weights, and line heights                         |
| [`RadiusOverrides` / `BorderWidthOverrides` / `SizeOverrides`](/docs/sdk/ios-checkout/v3.0.0-beta/api/theming/shape-tokens) | Corner radius, border widths, and component sizes             |

## Common Objects

| Component                                                                           | Description                                               |
| ----------------------------------------------------------------------------------- | --------------------------------------------------------- |
| [`PrimerSettings`](/docs/sdk/ios-checkout/v3.0.0-beta/api/common/primer-settings)        | SDK configuration (payment handling mode, options)        |
| [`PrimerError`](/docs/sdk/ios-checkout/v3.0.0-beta/api/common/primer-error)              | Error details with diagnostics ID and recovery suggestion |
| [`ValidationResult`](/docs/sdk/ios-checkout/v3.0.0-beta/api/common/validation-result)    | Field validation result with error details                |
| [`PrimerCardNetwork`](/docs/sdk/ios-checkout/v3.0.0-beta/api/common/primer-card-network) | Card network type for co-badged card selection            |
| [`PrimerCountry`](/docs/sdk/ios-checkout/v3.0.0-beta/api/common/primer-country)          | 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`](/docs/sdk/ios-checkout/v3.0.0-beta/api/primer-checkout-session), which owns the checkout lifecycle: it loads the [client session](/docs/checkout/client-session), tracks the lifecycle [`Phase`](/docs/sdk/ios-checkout/v3.0.0-beta/api/primer-checkout-session), and delivers the final [`PrimerCheckoutState`](/docs/sdk/ios-checkout/v3.0.0-beta/api/primer-checkout-state).

### Composable (inline)

Hold a `PrimerCheckoutSession` as a `@StateObject`, then attach it to your view hierarchy with the `.primerCheckoutSession(_:onCompletion:)` modifier. The composable views — [`PrimerCardForm`](/docs/sdk/ios-checkout/v3.0.0-beta/api/card-form/primer-card-form), [`PrimerPaymentMethods`](/docs/sdk/ios-checkout/v3.0.0-beta/api/payment-methods/primer-payment-methods), and [`PrimerVaultedPaymentMethods`](/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 `@ViewBuilder` slots you can override.

```swift theme={"dark"}
@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`](/docs/sdk/ios-checkout/v3.0.0-beta/api/primer-checkout-session)                  | `.primerCheckoutSession(_:onCompletion:)`                    | `phase`, `onBeforePaymentCreate`, `idempotencyKey`          |
| [`PrimerCardFormSession`](/docs/sdk/ios-checkout/v3.0.0-beta/api/card-form/card-form-session)              | `PrimerCardForm` slots                                       | Card field mutations, `submit()`, `cancel()`                |
| [`PrimerSelectionSession`](/docs/sdk/ios-checkout/v3.0.0-beta/api/payment-methods/payment-methods-session) | `PrimerPaymentMethods` / `PrimerVaultedPaymentMethods` slots | `select(_:)`, `selectVaulted(_:)`, `delete(_:)`, `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.
</Note>

### Managed (modal)

For a turnkey flow that renders the SDK's default screens, use [`PrimerCheckout`](/docs/sdk/ios-checkout/v3.0.0-beta/api/primer-checkout) in SwiftUI, or [`PrimerCheckoutPresenter`](/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.
</Tip>

## See also

<CardGroup cols={2}>
  <Card title="PrimerCheckoutSession" icon="diagram-project" href="/docs/sdk/ios-checkout/v3.0.0-beta/api/primer-checkout-session">
    Own the checkout lifecycle for inline, composable checkout.
  </Card>

  <Card title="PrimerCheckout" icon="window-maximize" href="/docs/sdk/ios-checkout/v3.0.0-beta/api/primer-checkout">
    Drop in the managed SwiftUI checkout view.
  </Card>

  <Card title="PrimerCardForm" icon="credit-card" href="/docs/sdk/ios-checkout/v3.0.0-beta/api/card-form/primer-card-form">
    Build a custom card form with @ViewBuilder slots.
  </Card>

  <Card title="Handle payment result" icon="circle-check" href="/docs/sdk/ios-checkout/v3.0.0-beta/guides/handle-payment-result">
    React to the final PrimerCheckoutState.
  </Card>
</CardGroup>