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

# Install Primer Checkout

> Package managers, browser requirements and initial setup for Web, iOS and Android.

## Prerequisites

You'll need your `clientToken` to initialize Primer Checkout. See our [Client Session guide](https://primer.io/docs/checkout/client-session.md) 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+ |

> [!NOTE]
>
> 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

> [tab] Web
>
> Install the Primer SDK using your preferred package manager:
>
> > [!NOTE]
> >
> > `@primer-io/primer-js` is installed via a package manager. Pick whichever you use. npm, yarn, and pnpm are all supported.
>
> > [tab] npm
> >
> > ```bash theme={"dark"}
> > npm install @primer-io/primer-js
> > ```
>
> > [tab] yarn
> >
> > ```bash theme={"dark"}
> > yarn add @primer-io/primer-js
> > ```
>
> > [tab] pnpm
> >
> > ```bash theme={"dark"}
> > pnpm add @primer-io/primer-js
> > ```

> [tab] Android
>
> Add the Primer BOM and the Primer Checkout SDK to your module-level `build.gradle.kts`. The BOM keeps the SDK and the 3DS, Klarna and Stripe ACH wrappers on the same version:
>
> ```kotlin theme={"dark"}
> dependencies {
>     implementation(platform("io.primer:bom:3.0.0-beta.8"))
>     implementation("io.primer:checkout")
> }
> ```
>
> Or without the BOM:
>
> ```kotlin theme={"dark"}
> dependencies {
>     implementation("io.primer:checkout:3.0.0-beta.8")
> }
> ```
>
> To add the wrappers, see [Payment method dependencies](https://primer.io/docs/sdk/android-checkout/v3.0.0-beta/installation.md#payment-method-dependencies).
>
> Ensure Jetpack Compose is enabled in your module-level `build.gradle.kts`:
>
> ```kotlin theme={"dark"}
> 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")
> }
> ```
>
> > [!WARNING]
> >
> > **This is a beta SDK.** The API may change before the stable release.
> > Contact [Primer support](https://primer.io/docs/support) before using in production.

> [tab] iOS
>
> Install the Primer SDK using your preferred package manager:
>
> > [tab] Swift Package Manager
> >
> > 1. In Xcode, go to **File > Add Package Dependencies**
> > 2. Enter the repository URL:
> >
> > ```
> > https://github.com/primer-io/primer-sdk-ios.git
> > ```
> >
> > 3. Under **Dependency Rule**, choose **Exact Version** and enter the beta tag `3.0.0-beta.8`
> > 4. Add `PrimerSDK` to your target
>
> > [tab] CocoaPods
> >
> > Add the following to your `Podfile`:
> >
> > ```ruby theme={"dark"}
> > pod 'PrimerSDK', '3.0.0-beta.8'
> > ```
> >
> > Then run:
> >
> > ```bash theme={"dark"}
> > pod install
> > ```
>
> Your app must target **iOS 15.0** or later.
>
> > [!WARNING]
> >
> > **This is a beta SDK.** The API may change before the stable release.
> > Contact [Primer support](https://primer.io/docs/support) before using in production.

## Load and initialize

> [tab] Web
>
> Import and initialize Primer in your application:
>
> ```javascript theme={"dark"}
> import { loadPrimer } from '@primer-io/primer-js';
> loadPrimer();
> ```

> [tab] Android
>
> The SDK initializes automatically when you create a checkout controller. Use `rememberPrimerCheckoutController` in your Composable:
>
> ```kotlin theme={"dark"}
> val checkout = rememberPrimerCheckoutController(
>     clientToken = clientToken,
> )
> ```
>
> The SDK starts loading configuration immediately upon creation.

> [tab] iOS
>
> The SDK initializes automatically when you create a `PrimerCheckout` view. Import PrimerSDK and add it to your SwiftUI view:
>
> ```swift theme={"dark"}
> 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

> [tab] Web
>
> Create a basic checkout by adding the `primer-checkout` component to your page:
>
> ```html theme={"dark"}
> <primer-checkout client-token="your-client-token"></primer-checkout>
> ```
>
> | Property | Description |
> | - | - |
> | `client-token` | A token retrieved from the [Client Session endpoint](https://primer.io/docs/checkout/client-session.md). Authenticates the checkout session and contains configuration for available payment methods. |

> [tab] Android
>
> Add the checkout to your Composable:
>
> ```kotlin theme={"dark"}
> @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)
> }
> ```

> [tab] iOS
>
> Add the checkout view to your screen with a `clientToken` and an `onCompletion` callback:
>
> ```swift theme={"dark"}
> 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 let .failure(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](https://primer.io/docs/checkout/client-session.md). Authenticates the checkout session and contains configuration for available payment methods. |
> | `onCompletion` | `((PrimerCheckoutState) -> Void)?` | Optional, defaults to `nil`. Receives `.failure` once per failed attempt, including a failed initialization. If the SDK error screen is on, the checkout stays open for a retry. Receives `.success` or `.dismissed` exactly once. |

## Verify installation

> [tab] Web
>
> Check that components are registered correctly in your browser console:
>
> ```javascript theme={"dark"}
> console.log(customElements.get('primer-checkout'));
> ```

> [tab] Android
>
> Build your project to confirm the SDK is resolved correctly:
>
> ```bash theme={"dark"}
> ./gradlew assembleDebug
> ```
>
> The SDK includes its own ProGuard rules — no additional configuration is needed for release builds.

> [tab] iOS
>
> 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.
>
> > [!WARNING]
> >
> > If the checkout shows an error screen instead of payment methods, or `onCompletion` receives `.failure`, verify that:
> >
> > * Your `clientToken` is valid and not expired
> > * Payment methods are configured in your [Primer Dashboard](https://dashboard.primer.io)
> >
> > If you turn off the SDK error screen with `PrimerSettings(uiOptions: PrimerUIOptions(isErrorScreenEnabled: false))`, the checkout shows nothing when it fails. The `.failure` in `onCompletion` is then your only signal.

## Framework-specific setup

> [tab] Web
>
> | Framework | Additional Steps |
> | - | - |
> | React 18/19 | See [React Integration Guide](https://primer.io/docs/checkout/primer-checkout/frameworks/react-integration-guide.md) for stable reference patterns |
> | Next.js | See [SSR Guide](https://primer.io/docs/checkout/primer-checkout/frameworks/ssr-guide.md) for client-side loading |
> | Nuxt.js | See [SSR Guide](https://primer.io/docs/checkout/primer-checkout/frameworks/ssr-guide.md) for `onMounted` pattern |
> | SvelteKit | See [SSR Guide](https://primer.io/docs/checkout/primer-checkout/frameworks/ssr-guide.md) for `onMount` pattern |
> | Vue.js (client-only) | No additional setup needed |
> | Vanilla JS | No additional setup needed |
>
> > [!WARNING]
> >
> > **Server-Side Rendering**
> >
> > If 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.
> >
> > ```javascript theme={"dark"}
> > useEffect(() => {
> >   if (typeof window !== 'undefined') {
> >     loadPrimer();
> >   }
> > }, []);
> > ```
> >
> > See the [SSR Guide](https://primer.io/docs/checkout/primer-checkout/frameworks/ssr-guide.md) for complete patterns.

> [tab] Android
>
> No framework-specific setup is needed. The SDK integrates directly with Jetpack Compose.

> [tab] iOS
>
> No framework-specific setup is needed. `PrimerCheckout` integrates directly with SwiftUI.
>
> For UIKit apps, use [`PrimerCheckoutPresenter`](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/guides/uikit-integration) to present the checkout from a `UIViewController`.

## See also

> [card] [First Payment](https://primer.io/docs/checkout/primer-checkout/first-payment.md)
>
> Accept your first payment

> [card] [Styling](https://primer.io/docs/checkout/primer-checkout/build-your-ui/styling-customization.md)
>
> Customize the appearance

> [card] [Layout](https://primer.io/docs/checkout/primer-checkout/build-your-ui/layout-customization.md)
>
> Control component arrangement

> [card] [Core Concepts](https://primer.io/docs/checkout/primer-checkout/core-concepts.md)
>
> Understand the architecture


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