> ## 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.

# Installation

> Add the Primer Checkout iOS SDK to your project

<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>

## Prerequisites

* iOS 15.0+ deployment target
* Swift 6.0+
* Xcode 16.0+
* A `clientToken` from your server via the [Client Session API](/docs/checkout/client-session)

<Info>
  The Primer Checkout SDK uses SwiftUI. You can drop it into a SwiftUI view hierarchy directly, or present it from UIKit with [`PrimerCheckoutPresenter`](/docs/sdk/ios-checkout/v3.0.0-beta/api/primer-checkout-presenter).
</Info>

## Install the SDK

Choose CocoaPods or Swift Package Manager. Both install the same `PrimerSDK` framework, which includes the Checkout Components UI.

<Note>
  This is a beta release line. The current version is `3.0.0-beta.1`. Pin to the exact beta version so a new beta tag does not change your build without you opting in.
</Note>

### With CocoaPods

Add the following to your `Podfile`:

```ruby RUBY theme={"dark"}
use_frameworks!

target 'MyApp' do

  # 👇 Add this line
  pod 'PrimerSDK', '3.0.0-beta.1'

  # ...

end
```

Then run `pod install` to install `PrimerSDK` into your workspace:

```bash theme={"dark"}
pod install
```

Open the generated `.xcworkspace` (not the `.xcodeproj`) from now on.

<Note>
  In case you encounter an error that the bundle needs signing on Xcode 14, add the following post-install script to your `Podfile`.

  ```ruby RUBY theme={"dark"}
  post_install do |installer|
    installer.pods_project.targets.each do |target|
      if target.respond_to?(:product_type) and target.product_type == "com.apple.product-type.bundle"
        target.build_configurations.each do |config|
            config.build_settings['CODE_SIGNING_ALLOWED'] = 'NO'
        end
      end
    end
  end
  ```
</Note>

### With Swift Package Manager

Swift Package Manager is integrated into Xcode. To add `PrimerSDK`:

1. Select your project, then navigate to **Package Dependencies**.
2. Click the **+** button at the bottom-left of the **Packages** section.
3. Paste [https://github.com/primer-io/primer-sdk-ios.git](https://github.com/primer-io/primer-sdk-ios.git) into the search bar.
4. Under **Dependency Rule**, choose **Exact Version** and enter the beta tag `3.0.0-beta.1`.
5. Press **Add Package** and let Xcode resolve and link the dependency.

Or declare it directly in your `Package.swift`:

```swift theme={"dark"}
dependencies: [
    .package(
        url: "https://github.com/primer-io/primer-sdk-ios.git",
        exact: "3.0.0-beta.1"
    )
]
```

## Basic Usage

Import `PrimerSDK` and present `PrimerCheckout` with a `clientToken`. This renders the SDK's default screens as a managed modal and reports the outcome through `onCompletion`:

```swift theme={"dark"}
import SwiftUI
import PrimerSDK

struct ContentView: View {
    let clientToken: String

    var body: some View {
        PrimerCheckout(clientToken: clientToken) { state in
            switch state {
            case .success(let result):
                print("Payment complete: \(result)")
            case .failure(let error):
                print("Checkout failed: \(error)")
            case .dismissed:
                print("Checkout dismissed")
            default:
                break
            }
        }
    }
}
```

`PrimerCheckout` requires iOS 15.0+ and runs on the main actor. Its full initializer also accepts `primerSettings` and `primerTheme`:

```swift theme={"dark"}
PrimerCheckout(
    clientToken: clientToken,
    primerSettings: PrimerSettings(),
    primerTheme: PrimerCheckoutTheme(),
    onCompletion: { state in
        // Handle the final checkout state
    }
)
```

| Parameter        | Type                               | Default                 | Description                                                                           |
| ---------------- | ---------------------------------- | ----------------------- | ------------------------------------------------------------------------------------- |
| `clientToken`    | `String`                           | —                       | The client token obtained from your backend via the Client Session API.               |
| `primerSettings` | `PrimerSettings`                   | `PrimerSettings()`      | Configuration settings including payment options and UI preferences.                  |
| `primerTheme`    | `PrimerCheckoutTheme`              | `PrimerCheckoutTheme()` | Theme configuration for design tokens.                                                |
| `onCompletion`   | `((PrimerCheckoutState) -> Void)?` | `nil`                   | Called when checkout completes with the final state (success, failure, or dismissed). |

<Tip>
  Building a UIKit app? Present the checkout from a `UIViewController` with [`PrimerCheckoutPresenter`](/docs/sdk/ios-checkout/v3.0.0-beta/api/primer-checkout-presenter) instead of embedding the SwiftUI view.
</Tip>

## Verify Installation

Build and run your app to confirm the SDK is resolved and links correctly:

```bash theme={"dark"}
xcodebuild -scheme MyApp -destination 'generic/platform=iOS' build
```

If the build succeeds and `import PrimerSDK` resolves, the SDK is installed and ready to use.

## Next Steps

<CardGroup cols={2}>
  <Card title="API Overview" icon="map" href="/docs/sdk/ios-checkout/v3.0.0-beta/api/overview">
    Tour the Checkout Components API surface
  </Card>

  <Card title="PrimerCheckout" icon="credit-card" href="/docs/sdk/ios-checkout/v3.0.0-beta/api/primer-checkout">
    The managed modal entry point in depth
  </Card>

  <Card title="Theming" icon="palette" href="/docs/sdk/ios-checkout/v3.0.0-beta/api/theming/primer-theme">
    Customize the appearance with design tokens
  </Card>

  <Card title="Handle Payment Result" icon="circle-check" href="/docs/sdk/ios-checkout/v3.0.0-beta/guides/handle-payment-result">
    Respond to success, failure, and dismissal
  </Card>
</CardGroup>