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

## Prerequisites

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

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

## 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.8`. Pin to the exact beta version so a new beta tag does not change your build without you opting in.

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

  # ...

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]
>
> If Xcode reports that a resource bundle target needs signing, 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
> ```

### 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.8`.
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.8"
    )
]
```

### Optional: Klarna

Native Klarna appears in the payment method list only when your app includes the `PrimerKlarnaSDK` pod. Adyen Klarna does not need it.

With CocoaPods, add `PrimerKlarnaSDK` next to `PrimerSDK` in your `Podfile`, then run `pod install`:

```ruby RUBY theme={"dark"}
target 'MyApp' do
  pod 'PrimerSDK', '3.0.0-beta.8'
  # 👇 Add this line
  pod 'PrimerKlarnaSDK'
end
```

The `PrimerSDK` Swift package does not include `PrimerKlarnaSDK`, so native Klarna requires CocoaPods.

## 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 let .failure(error, _):
                print("Checkout failed: \(error)")
            case .dismissed:
                print("Checkout dismissed")
            default:
                break
            }
        }
    }
}
```

`PrimerCheckout` requires iOS 15.0+ and runs on the main actor. Its initializer also accepts `primerSettings` and `primerTheme`, plus two optional Apple Pay Express Checkout shipping handlers:

```swift theme={"dark"}
PrimerCheckout(
    clientToken: clientToken,
    primerSettings: PrimerSettings(),
    primerTheme: PrimerCheckoutTheme(),
    onCompletion: { state in
        // .failure per failed attempt, then .success or .dismissed once
    }
)
```

| 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` | Receives `.failure` once per failed attempt, including a failed initialization. With the default error screen, the checkout stays open for a retry. Then receives `.success` or `.dismissed` exactly once. |
| `onShippingAddressChange` | `ShippingAddressChangeHandler?` | `nil` | Express Checkout: returns the shipping options for the shopper's address. |
| `onShippingOptionChange` | `ShippingOptionChangeHandler?` | `nil` | Express Checkout: commits the shipping option the shopper selected. |

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

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

> [card] [API Overview](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/overview.md)
>
> Tour the Checkout Components API surface

> [card] [PrimerCheckout](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/primer-checkout.md)
>
> The managed modal entry point in depth

> [card] [Theming](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/theming/primer-theme.md)
>
> Customize the appearance with design tokens

> [card] [Handle Payment Result](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/guides/handle-payment-result.md)
>
> Respond to success, failure, and dismissal


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