> ## 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
> Install and set up Primer Checkout
## Prerequisites
You'll need your `clientToken` to initialize Primer Checkout. See our [Client Session guide](/checkout/client-session) 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
Install the Primer SDK using your preferred package manager:
```bash theme={"dark"}
npm install @primer-io/primer-js
```
```bash theme={"dark"}
yarn add @primer-io/primer-js
```
```bash theme={"dark"}
pnpm add @primer-io/primer-js
```
Add the Primer Checkout SDK dependency to your module-level `build.gradle.kts`:
```kotlin theme={"dark"}
dependencies {
implementation("io.primer:checkout:3.0.0-beta.2")
}
```
Or using the BOM for version management:
```kotlin theme={"dark"}
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`:
```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")
}
```
**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.
Install the Primer SDK using your preferred 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. Select the version rule for the `3.0.0-beta` release
4. Add `PrimerSDK` to your target
Add the following to your `Podfile`:
```ruby theme={"dark"}
pod 'PrimerSDK', '~> 3.0.0-beta'
```
Then run:
```bash theme={"dark"}
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](https://primer.io/docs/support) before using in production.
## Load and initialize
Import and initialize Primer in your application:
```javascript theme={"dark"}
import { loadPrimer } from '@primer-io/primer-js';
loadPrimer();
```
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.
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
Create a basic checkout by adding the `primer-checkout` component to your page:
```html theme={"dark"}
```
| Property | Description |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `client-token` | A token retrieved from the [Client Session endpoint](/checkout/client-session). Authenticates the checkout session and contains configuration for available payment methods. |
Add the checkout to your Composable:
```kotlin theme={"dark"}
@Composable
fun CheckoutScreen(clientToken: String) {
val checkout = rememberPrimerCheckoutController(
clientToken = clientToken,
)
PrimerCheckoutSheet(
checkout = checkout,
onEvent = { event ->
when (event) {
is PrimerCheckoutEvent.Success -> { /* Navigate to confirmation */ }
is PrimerCheckoutEvent.Failure -> { /* Error is shown in the UI */ }
}
},
)
}
```
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.payment?.id ?? "")")
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](/checkout/client-session). 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
Check that components are registered correctly in your browser console:
```javascript theme={"dark"}
console.log(customElements.get('primer-checkout'));
```
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.
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](https://dashboard.primer.io)
* Your app targets iOS 15.0 or later
## Framework-specific setup
| Framework | Additional Steps |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| React 18/19 | See [React Integration Guide](/checkout/primer-checkout/frameworks/react-integration-guide) for stable reference patterns |
| Next.js | See [SSR Guide](/checkout/primer-checkout/frameworks/ssr-guide) for client-side loading |
| Nuxt.js | See [SSR Guide](/checkout/primer-checkout/frameworks/ssr-guide) for `onMounted` pattern |
| SvelteKit | See [SSR Guide](/checkout/primer-checkout/frameworks/ssr-guide) for `onMount` pattern |
| Vue.js (client-only) | No additional setup needed |
| Vanilla JS | No additional setup needed |
**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](/checkout/primer-checkout/frameworks/ssr-guide) for complete patterns.
No framework-specific setup is needed. The SDK integrates directly with Jetpack Compose.
No framework-specific setup is needed. `PrimerCheckout` integrates directly with SwiftUI.
For UIKit apps, use [`PrimerCheckoutPresenter`](/sdk/ios-checkout/v3.0.0-beta/integration-patterns/uikit-integration) to present the checkout from a `UIViewController`.
## See also
Accept your first payment
Customize the appearance
Control component arrangement
Understand the architecture