Installation - Primer

Prerequisites

You’ll need your clientToken to initialize Primer Checkout. See our Client Session guide on how to create a client session and retrieve a clientToken first.

Environment Requirements

Before diving into the implementation, ensure your environment meets these requirements:

Requirement	Details
Node.js	Current LTS version recommended
Browsers	Modern browsers with ES2020 support (see below)
Not Supported	Internet Explorer 11, Classic Edge (legacy)

Minimum Browser Versions

The SDK requires ES2020 support. Minimum supported browser versions:

Browser	Minimum Version
Chrome	80+
Edge	80+
Firefox	79+
Safari	14+
iOS Safari	14+
Opera	67+
Samsung Internet	13.0+

Legacy browsers like Internet Explorer 11 aren’t officially supported due to their non-standard DOM behavior and lack of support for modern Web Component features and ES2020 syntax that this SDK is built on.

Install the SDK

Web
Android
iOS

Install the Primer SDK using your preferred package manager:

@primer-io/primer-js is installed via a package manager. Pick whichever you use. npm, yarn, and pnpm are all supported.

npm
yarn
pnpm

npm install @primer-io/primer-js

yarn add @primer-io/primer-js

pnpm add @primer-io/primer-js

Add the Primer Checkout SDK dependency to your module-level build.gradle.kts:

dependencies {
    implementation("io.primer:checkout:3.0.0-beta.2")
}

Or using the BOM for version management:

dependencies {
    implementation(platform("io.primer:primer-sdk-android-bom:3.0.0-beta.2"))
    implementation("io.primer:checkout")
}

Ensure Jetpack Compose is enabled in your module-level build.gradle.kts:

android {
    buildFeatures {
        compose = true
    }
    composeOptions {
        kotlinCompilerExtensionVersion = "1.5.8"
    }
}

dependencies {
    implementation(platform("androidx.compose:compose-bom:2025.12.00"))
    implementation("androidx.compose.ui:ui")
    implementation("androidx.compose.material3:material3")
    implementation("androidx.lifecycle:lifecycle-runtime-compose:2.7.0")
}

This is a beta SDK. The API may change before the stable release. Contact Primer support before using in production.

Install the Primer SDK using your preferred package manager:

Swift Package Manager
CocoaPods

In Xcode, go to File > Add Package Dependencies
Enter the repository URL:

https://github.com/primer-io/primer-sdk-ios.git

Under Dependency Rule, choose Exact Version and enter the beta tag 3.0.0-beta.1
Add PrimerSDK to your target

Add the following to your Podfile:

pod 'PrimerSDK', '3.0.0-beta.1'

Then run:

pod install

Your app must target iOS 15.0 or later.

This is a beta SDK. The API may change before the stable release. Contact Primer support before using in production.

Load and initialize

Web
Android
iOS

Import and initialize Primer in your application:

import { loadPrimer } from '@primer-io/primer-js';
loadPrimer();

The SDK initializes automatically when you create a checkout controller. Use rememberPrimerCheckoutController in your Composable:

val checkout = rememberPrimerCheckoutController(
    clientToken = clientToken,
)

The SDK starts loading configuration immediately upon creation.

The SDK initializes automatically when you create a PrimerCheckout view. Import PrimerSDK and add it to your SwiftUI view:

import SwiftUI
import PrimerSDK

struct CheckoutView: View {
  let clientToken: String

  var body: some View {
    PrimerCheckout(clientToken: clientToken)
  }
}

The SDK starts loading configuration immediately when the view appears.

Add the checkout component

Web
Android
iOS

Create a basic checkout by adding the primer-checkout component to your page:

<primer-checkout client-token="your-client-token"></primer-checkout>

Property	Description
`client-token`	A token retrieved from the Client Session endpoint. Authenticates the checkout session and contains configuration for available payment methods.

Add the checkout to your Composable:

@Composable
fun CheckoutScreen(clientToken: String) {
    val checkout = rememberPrimerCheckoutController(
        clientToken = clientToken,
    )
    val state by checkout.state.collectAsStateWithLifecycle()

    LaunchedEffect(state) {
        when (state) {
            is PrimerCheckoutState.Success -> { /* Navigate to confirmation */ }
            is PrimerCheckoutState.Failure -> { /* Error is shown in the UI */ }
            else -> Unit
        }
    }

    PrimerCheckoutSheet(checkout = checkout)
}

Add the checkout view to your screen with a clientToken and an onCompletion callback:

struct CheckoutView: View {
  let clientToken: String

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

Parameter	Type	Description
`clientToken`	`String`	A token retrieved from the Client Session endpoint. Authenticates the checkout session and contains configuration for available payment methods.
`onCompletion`	`(PrimerCheckoutState) -> Void`	Callback invoked when the checkout reaches a terminal state (success, failure, or dismissed).

Verify installation

Web
Android
iOS

Check that components are registered correctly in your browser console:

console.log(customElements.get('primer-checkout'));

Build your project to confirm the SDK is resolved correctly:

./gradlew assembleDebug

The SDK includes its own ProGuard rules — no additional configuration is needed for release builds.

Build and run your app. If the SDK is installed correctly, you should see the checkout UI with payment methods configured in your Primer Dashboard.

If you see a blank screen, verify that:

Your clientToken is valid and not expired
Payment methods are configured in your Primer Dashboard
Your app targets iOS 15.0 or later

Framework-specific setup

Web
Android
iOS

Framework	Additional Steps
React 18/19	See React Integration Guide for stable reference patterns
Next.js	See SSR Guide for client-side loading
Nuxt.js	See SSR Guide for `onMounted` pattern
SvelteKit	See SSR Guide for `onMount` pattern
Vue.js (client-only)	No additional setup needed
Vanilla JS	No additional setup needed

Server-Side RenderingIf you’re using Next.js, Nuxt, SvelteKit, or any SSR framework, you must load Primer only on the client side. The Web Components API doesn’t exist in Node.js.

useEffect(() => {
  if (typeof window !== 'undefined') {
    loadPrimer();
  }
}, []);

See the SSR Guide for complete patterns.

No framework-specific setup is needed. PrimerCheckout integrates directly with SwiftUI.For UIKit apps, use PrimerCheckoutPresenter to present the checkout from a UIViewController.

First Payment

Accept your first payment

Styling

Customize the appearance

Layout

Control component arrangement

Core Concepts

Understand the architecture

​Prerequisites

​Environment Requirements

​Minimum Browser Versions

​Install the SDK

​Load and initialize

​Add the checkout component

​Verify installation

​Framework-specific setup

​See also

First Payment

Styling

Layout

Core Concepts

Prerequisites

Environment Requirements

Minimum Browser Versions

Install the SDK

Load and initialize

Add the checkout component

Verify installation

Framework-specific setup

See also