Installation - Primer

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

The Primer Checkout SDK uses SwiftUI. You can drop it into a SwiftUI view hierarchy directly, or present it from UIKit with PrimerCheckoutPresenter.

Install the SDK

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

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

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:

pod install

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

If Xcode reports that a resource bundle target needs signing, add the following post-install script to your Podfile.

RUBY

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:

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

Or declare it directly in your Package.swift:

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

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:

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:

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.

Building a UIKit app? Present the checkout from a UIViewController with PrimerCheckoutPresenter instead of embedding the SwiftUI view.

Verify Installation

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

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

API Overview

Tour the Checkout Components API surface

PrimerCheckout

The managed modal entry point in depth

Theming

Customize the appearance with design tokens

Handle Payment Result

Respond to success, failure, and dismissal

​Prerequisites

​Install the SDK

​With CocoaPods

​With Swift Package Manager

​Optional: Klarna

​Basic Usage

​Verify Installation

​Next Steps

API Overview

PrimerCheckout

Theming

Handle Payment Result

Prerequisites

Install the SDK

With CocoaPods

With Swift Package Manager

Optional: Klarna

Basic Usage

Verify Installation

Next Steps