Configuring checkout

Primer Checkout uses platform-specific configuration to control checkout behavior, appearance, and payment handling.

Web
Android
iOS

Primer Checkout Web uses two types of configuration: component properties (HTML attributes) and SDK options (JavaScript object).

const checkout = document.querySelector('primer-checkout');

// Component properties - use setAttribute()
checkout.setAttribute('client-token', 'your-token');

// SDK options - assign directly
checkout.options = {
  locale: 'en-GB',
  card: { cardholderName: { required: true } }
};

The Android SDK uses PrimerSettings to configure checkout behavior. Pass it when creating the checkout controller:

val checkout = rememberPrimerCheckoutController(
    clientToken = clientToken,
    settings = PrimerSettings().apply {
        locale = Locale("fr", "FR")
        uiOptions.dismissalMechanism = listOf(DismissalMechanism.CLOSE_BUTTON)
    },
)

The iOS SDK uses PrimerSettings and PrimerCheckoutTheme to configure checkout behavior and appearance. Pass them when creating PrimerCheckout:

PrimerCheckout(
  clientToken: clientToken,
  primerSettings: PrimerSettings(paymentHandling: .auto),
  primerTheme: PrimerCheckoutTheme(
    colors: ColorOverrides(primerColorBrand: .blue)
  )
)

Configuration Overview

Web
Android
iOS

Type	How to Set	Examples
Component Properties	`setAttribute()`	`client-token`, `custom-styles`, `loader-disabled`
SDK Options	Direct assignment to `.options`	`locale`, `card`, `vault`, `applePay`

Don’t mix them up. Component properties must use setAttribute(). SDK options must be assigned directly to .options.

Type	How to Set	Examples
Client token	`rememberPrimerCheckoutController(clientToken)`	Authentication token
Settings	`PrimerSettings` object	`locale`, `uiOptions`, `paymentMethodOptions`, `debugOptions`
Theme	`PrimerTheme` parameter on composable	`PrimerCheckoutSheet(theme = ...)`

Theming is not part of PrimerSettings. Pass PrimerTheme directly to PrimerCheckoutSheet or PrimerCheckoutHost. See Styling Guide.

Type	How to Set	Examples
Client token	`PrimerCheckout(clientToken:)`	Authentication token
Settings	`PrimerSettings` parameter	`paymentHandling`, `uiOptions`, `paymentMethodOptions`
Theme	`PrimerCheckoutTheme` parameter	`colors`, `radius`, `spacing`, `typography`

Theming is not part of PrimerSettings. Pass PrimerCheckoutTheme as a separate parameter to PrimerCheckout or PrimerCheckoutPresenter. See Styling Guide.

Component Properties / Client Token

The client token authenticates your checkout session. Obtain this by creating a client session.

Web
Android
iOS

client-token (required)

// ✅ Correct
checkout.setAttribute('client-token', 'your-client-token');

// ❌ Wrong - won't work
checkout.clientToken = 'your-token';

<!-- Or set directly in HTML -->
<primer-checkout client-token="your-client-token"></primer-checkout>

Updating the client token

To start a new session, set a new client token on the existing component. The checkout tears down the current session and initializes the new one in place, so you don’t need to reload the page or recreate the component.

checkout.setAttribute('client-token', newClientToken);

This is a full re-initialization: the loader shows again, entered card details are cleared, payment methods are reloaded, and primer:ready fires again with a new PrimerJS instance. Don’t change the token while a payment is in progress.If you updated the existing client session on your server and the token hasn’t changed, call primer.refreshSession() instead. It syncs the checkout with the session without re-initializing.

custom-styles

JSON string containing CSS variables for theming.

const styles = {
  primerColorBrand: '#4a6cf7',
  primerTypographyBrand: 'Inter, sans-serif'
};

checkout.setAttribute('custom-styles', JSON.stringify(styles));

See Styling Guide for available properties.

loader-disabled

Disables the default loading spinner.

checkout.setAttribute('loader-disabled', 'true');

Pass the client token directly when creating the checkout controller:

val checkout = rememberPrimerCheckoutController(
    clientToken = clientToken,
)

Pass the client token directly when creating PrimerCheckout:

// SwiftUI
PrimerCheckout(clientToken: clientToken)

// UIKit
PrimerCheckoutPresenter.presentCheckout(
  clientToken: clientToken,
  from: viewController,
  primerSettings: PrimerSettings(),
  primerTheme: PrimerCheckoutTheme()
)

SDK Options / Settings

Web
Android
iOS

SDK options configure checkout behavior. Assign a JavaScript object directly to the options property.

// ✅ Correct - assign directly
checkout.options = {
  locale: 'en-GB',
  card: { cardholderName: { required: true } }
};

// ❌ Wrong - don't use setAttribute for options
checkout.setAttribute('options', JSON.stringify({...}));

For the complete list of available options, see the SDK Options Reference.

PrimerSettings configures the SDK behavior for a checkout session. Pass it when creating the controller.

val checkout = rememberPrimerCheckoutController(
    clientToken = clientToken,
    settings = PrimerSettings().apply {
        locale = Locale("fr", "FR")
        uiOptions.dismissalMechanism = listOf(DismissalMechanism.CLOSE_BUTTON)
        paymentMethodOptions.redirectScheme = "myapp"
    },
)

For the complete list of available options, see the SDK Options Reference.

PrimerSettings configures the SDK behavior for a checkout session. Pass it when creating PrimerCheckout.

let settings = PrimerSettings(
  paymentHandling: .auto,
  paymentMethodOptions: PrimerPaymentMethodOptions(),
  uiOptions: PrimerUIOptions()
)

PrimerCheckout(
  clientToken: clientToken,
  primerSettings: settings
)

For the complete list of available options, see the SDK Options Reference.

Common Patterns

Web
Android
iOS

Set Locale

checkout.options = {
  locale: 'en-GB'
};

Supported locales

Enable Specific Payment Methods

import { PaymentMethodType } from '@primer-io/primer-js';

checkout.options = {
  enabledPaymentMethods: [
    PaymentMethodType.PAYMENT_CARD,
    PaymentMethodType.PAYPAL,
    PaymentMethodType.ADYEN_BLIK
  ]
};

Pre-fill Cardholder Name

checkout.options = {
  card: {
    cardholderName: {
      required: true,
      visible: true,
      defaultValue: 'John Doe'
    }
  }
};

For runtime updates after initialization, use primer.setCardholderName() instead.

Enable Vault (Saved Payment Methods)

checkout.options = {
  vault: {
    enabled: true
  }
};

Configure Apple Pay Button

checkout.options = {
  applePay: {
    buttonType: 'buy',
    buttonStyle: 'black'
  }
};

Configure Google Pay Button

checkout.options = {
  googlePay: {
    buttonType: 'buy',
    buttonColor: 'black',
    captureBillingAddress: true
  }
};

Configure Klarna

checkout.options = {
  klarna: {
    paymentFlow: 'DEFAULT',
    allowedPaymentCategories: ['pay_now', 'pay_later'],
    buttonOptions: {
      text: 'Pay with Klarna'
    }
  }
};

Configure Klarna via Adyen

checkout.options = {
  adyenKlarna: {
    buttonOptions: {
      text: 'Pay with Klarna'
    }
  }
};

Set Locale

settings = PrimerSettings().apply {
    locale = Locale("fr", "FR")
}

Default is Locale.getDefault() (device locale). Controls SDK-internal strings and currency formatting.

Custom Success/Error Screens

Replace the default success and error screens with your own composables via slot parameters:

PrimerCheckoutSheet(
    checkout = checkout,
    success = { checkoutData ->
        MyCustomSuccessScreen(checkoutData)
    },
    error = { primerError, _ ->
        MyCustomErrorScreen(primerError)
    },
)

See Layout Customization for more slot examples.

Configure Dismissal Behavior

settings = PrimerSettings().apply {
    uiOptions.dismissalMechanism = listOf(DismissalMechanism.CLOSE_BUTTON)
}

Value	Behavior
`GESTURES`	Swipe-to-dismiss (default)
`CLOSE_BUTTON`	Explicit close button

You can combine both: listOf(DismissalMechanism.GESTURES, DismissalMechanism.CLOSE_BUTTON).

Configure Google Pay

settings = PrimerSettings().apply {
    paymentMethodOptions.googlePayOptions = PrimerGooglePayOptions(
        merchantName = "My Store",
        captureBillingAddress = true,
        emailAddressRequired = true,
        buttonStyle = GooglePayButtonStyle.BLACK,
    )
}

Set Redirect Scheme

Required for redirect-based payment methods (PayPal, Klarna, etc.):

settings = PrimerSettings().apply {
    paymentMethodOptions.redirectScheme = "myapp"
}

Set Payment Handling

let settings = PrimerSettings(paymentHandling: .auto)

Value	Behavior
`.auto`	Primer handles the full payment flow (recommended)
`.manual`	Not supported in Primer Checkout. The checkout fails at start with a `PrimerError` whose `errorId` is `invalid-value`. Keep `.auto`. See PrimerPaymentHandling.

Toggle Managed Screens

PrimerCheckout renders Primer’s default init, success, and error screens. Toggle them through uiOptions to handle results yourself instead:

let settings = PrimerSettings(
  uiOptions: PrimerUIOptions(
    isInitScreenEnabled: false,
    isSuccessScreenEnabled: false,
    isErrorScreenEnabled: false
  )
)

For fully custom screens, compose your own views under PrimerCheckoutSession instead of PrimerCheckout and drive them with the session’s published state.

Configure Theme Colors

let theme = PrimerCheckoutTheme(
  colors: ColorOverrides(
    primerColorBrand: .blue,
    primerColorBackground: .white
  )
)

Handle Completion

PrimerCheckout(
  clientToken: clientToken,
  onCompletion: { state in
    switch state {
    case .success(let result):
      print("Payment: \(result.paymentId)")
    case let .failure(error, _):
      print("Failed: \(error.localizedDescription)")
    case .dismissed:
      print("Dismissed")
    default:
      break
    }
  }
)

Complete Example

Web
Android
iOS

import { PaymentMethodType } from '@primer-io/primer-js';

const checkout = document.querySelector('primer-checkout');

// 1. Component properties
checkout.setAttribute('client-token', 'your-client-token');
checkout.setAttribute('custom-styles', JSON.stringify({
  primerColorBrand: '#4a6cf7'
}));

// 2. SDK options
checkout.options = {
  locale: 'en-GB',
  enabledPaymentMethods: [
    PaymentMethodType.PAYMENT_CARD,
    PaymentMethodType.PAYPAL
  ],
  card: {
    cardholderName: {
      required: true,
      visible: true
    }
  },
  vault: {
    enabled: true
  }
};

@Composable
fun CheckoutScreen(clientToken: String) {
    val checkout = rememberPrimerCheckoutController(
        clientToken = clientToken,
        settings = PrimerSettings().apply {
            locale = Locale("fr", "FR")
            uiOptions.dismissalMechanism = listOf(DismissalMechanism.CLOSE_BUTTON)
            paymentMethodOptions.redirectScheme = "myapp"
            paymentMethodOptions.googlePayOptions = PrimerGooglePayOptions(
                merchantName = "My Store",
                captureBillingAddress = true,
            )
        },
    )

    val state by checkout.state.collectAsStateWithLifecycle()

    LaunchedEffect(state) {
        when (val s = state) {
            is PrimerCheckoutState.Success -> navigateToConfirmation(s.checkoutData)
            is PrimerCheckoutState.Failure -> {
                Log.e("Checkout", "Failed: ${s.primerError.description}")
            }
            else -> Unit
        }
    }

    PrimerCheckoutSheet(
        checkout = checkout,
        success = { checkoutData -> MySuccessScreen(checkoutData) },
        error = { primerError, _ -> MyErrorScreen(primerError) },
        onDismiss = {
            navigateBack()
        },
    )
}

private let primerSettings = PrimerSettings(
  paymentHandling: .auto,
  uiOptions: PrimerUIOptions(
    dismissalMechanism: [.gestures, .closeButton]
  )
)

private let primerTheme = PrimerCheckoutTheme(
  colors: ColorOverrides(primerColorBrand: .blue),
  radius: RadiusOverrides(primerRadiusMedium: 12)
)

struct CheckoutView: View {
  let clientToken: String

  var body: some View {
    PrimerCheckout(
      clientToken: clientToken,
      primerSettings: primerSettings,
      primerTheme: primerTheme,
      onCompletion: { state in
        switch state {
        case .success(let result):
          print("Payment: \(result.paymentId)")
        case let .failure(error, _):
          print("Failed: \(error.localizedDescription)")
        case .dismissed:
          print("Dismissed")
        default:
          break
        }
      }
    )
  }
}

Framework-Specific Patterns

Web
Android
iOS

Vanilla JS
React
Next.js / SSR

document.addEventListener('DOMContentLoaded', () => {
  const checkout = document.querySelector('primer-checkout');
  checkout.setAttribute('client-token', 'your-token');
  checkout.options = { locale: 'en-GB' };
});

const SDK_OPTIONS = { locale: 'en-GB' };

function CheckoutPage() {
  return (
    <primer-checkout
      client-token="your-token"
      options={SDK_OPTIONS}
    />
  );
}

See React Integration Guide for stable references and React 18/19 differences.

'use client';

import { useEffect } from 'react';
import { loadPrimer } from '@primer-io/primer-js';

const SDK_OPTIONS = { locale: 'en-GB' };

export default function CheckoutPage() {
  useEffect(() => {
    loadPrimer();
  }, []);

  return (
    <primer-checkout
      client-token="your-token"
      options={SDK_OPTIONS}
    />
  );
}

See SSR Guide for framework-specific patterns.

The Android SDK uses standard Jetpack Compose patterns. Configuration is passed when creating the checkout controller:

@Composable
fun CheckoutScreen(clientToken: String) {
    val checkout = rememberPrimerCheckoutController(
        clientToken = clientToken,
        settings = PrimerSettings().apply {
            paymentMethodOptions.redirectScheme = "myapp"
        },
    )

    PrimerCheckoutSheet(checkout = checkout)
}

See the Best Practices guide for Compose-specific patterns.

SwiftUI
UIKit

struct CheckoutView: View {
  let clientToken: String

  var body: some View {
    PrimerCheckout(
      clientToken: clientToken,
      primerSettings: PrimerSettings(paymentHandling: .auto),
      onCompletion: { state in
        // Handle result
      }
    )
  }
}

See the Best Practices guide for SwiftUI-specific patterns.

class CheckoutViewController: UIViewController, PrimerCheckoutPresenterDelegate {
  func showCheckout() {
    PrimerCheckoutPresenter.shared.delegate = self

    PrimerCheckoutPresenter.presentCheckout(
      clientToken: clientToken,
      from: self,
      primerSettings: PrimerSettings(paymentHandling: .auto),
      primerTheme: PrimerCheckoutTheme()
    )
  }

  func primerCheckoutPresenterDidCompleteWithSuccess(_ result: PaymentResult) {
    // Navigate to confirmation
  }

  func primerCheckoutPresenterDidFailWithError(_ error: PrimerError, checkoutData: PrimerCheckoutData?) {
    print("Failed: \(error.errorDescription)")
  }

  func primerCheckoutPresenterDidDismiss() {
    print("Dismissed")
  }
}

See UIKit Integration Guide for more details.

Advanced Configuration

Web
Android
iOS

Headless Vault

Build custom vault UIs while retaining full vault functionality. Enable headless mode:

checkout.options = {
  vault: {
    enabled: true,
    headless: true
  }
};

Then use onVaultedMethodsUpdate, vault.createCvvInput(), and vault.startPayment() to build your custom UI.

Headless Vault Implementation Guide

External Submit Button

Use your own submit button instead of the built-in one:

checkout.options = {
  submitButton: {
    useBuiltInButton: false
  }
};

// Trigger submission from your button
document.getElementById('my-button').addEventListener('click', () => {
  document.dispatchEvent(new CustomEvent('primer:card-submit', {
    bubbles: true,
    composed: true
  }));
});

External Submit Button Recipe

Show Amount on Button

Display the payment amount on the submit button:

checkout.options = {
  submitButton: {
    amountVisible: true
  }
};

Custom Submit Button

Override the submit button slot in PrimerCardForm:

PrimerCardForm(
    controller = cardFormController,
    submitButton = {
        Button(
            onClick = { cardFormController.submit() },
            enabled = formState.isFormValid && !formState.isLoading,
        ) {
            Text("Pay")
        }
    },
)

External Submit Button Recipe

Google Pay with Shipping

Configure Google Pay to collect billing address, email, and shipping:

settings = PrimerSettings().apply {
    paymentMethodOptions.googlePayOptions = PrimerGooglePayOptions(
        merchantName = "My Store",
        captureBillingAddress = true,
        emailAddressRequired = true,
        shippingAddressParameters = PrimerGoogleShippingAddressParameters(
            phoneNumberRequired = true,
        ),
        requireShippingMethod = true,
    )
}

Stripe ACH Mandate

Configure mandate data for Stripe ACH payments:

settings = PrimerSettings().apply {
    paymentMethodOptions.stripeOptions = PrimerStripeOptions(
        mandateData = MandateData.TemplateMandateData(merchantName = "My Store"),
    )
}

3DS Configuration

Set the 3DS App Requestor URL:

settings = PrimerSettings().apply {
    paymentMethodOptions.threeDsOptions = PrimerThreeDsOptions(
        threeDsAppRequestorUrl = "https://mystore.com",
    )
}

Inline Custom Layout

PrimerCheckout renders the SDK’s default screens. For a fully custom layout, hold a PrimerCheckoutSession as a @StateObject, compose the SwiftUI views you need, and wire them up with the .primerCheckoutSession(_:theme:onCompletion:) modifier:

struct CustomCheckoutView: View {
  @StateObject private var session: PrimerCheckoutSession

  init(clientToken: String) {
    _session = StateObject(wrappedValue: PrimerCheckoutSession(clientToken: clientToken))
  }

  var body: some View {
    ScrollView {
      VStack(spacing: 24) {
        Text("Secure Checkout").font(.headline)
        PrimerPaymentMethods()
        PrimerCardForm()
      }
      .padding()
    }
    .primerCheckoutSession(session) { state in
      // React to the terminal PrimerCheckoutState.
    }
  }
}

Custom Card Form Submit Button

Override the submitButton slot on PrimerCardForm. Each slot closure receives the active PrimerCardFormSession, so you read session.state and call session.submit():

PrimerCardForm(submitButton: { session in
  Button("Pay Now") {
    session.submit()
  }
  .disabled(!session.state.isValid || session.state.isLoading)
})

The other slots (cardDetails, billingAddress) keep their CardFormDefaults styling. Place PrimerCardForm under the .primerCheckoutSession modifier so it resolves its session from the environment.

Custom Submit Button Recipe

Web SDK Options Reference

Complete list of all available Web options

Android SDK Reference

Android SDK API documentation

Events Guide

Handle payment success, failure, and state changes

Styling

Customize colors, fonts, and spacing

​Configuration Overview

​Component Properties / Client Token

​client-token (required)

​Updating the client token

​custom-styles

​loader-disabled

​SDK Options / Settings

​Common Patterns

​Set Locale

​Enable Specific Payment Methods

​Pre-fill Cardholder Name

​Enable Vault (Saved Payment Methods)

​Configure Apple Pay Button

​Configure Google Pay Button

​Configure Klarna

​Configure Klarna via Adyen

​Set Locale

​Custom Success/Error Screens

​Configure Dismissal Behavior

​Configure Google Pay

​Set Redirect Scheme

​Set Payment Handling

​Toggle Managed Screens

​Configure Theme Colors

​Handle Completion

​Complete Example

​Framework-Specific Patterns

​Advanced Configuration

​See also

Web SDK Options Reference

Android SDK Reference

Events Guide

Styling

Configuration Overview

Component Properties / Client Token

client-token (required)

Updating the client token

custom-styles

loader-disabled

SDK Options / Settings

Common Patterns

Set Locale

Enable Specific Payment Methods

Pre-fill Cardholder Name

Enable Vault (Saved Payment Methods)

Configure Apple Pay Button

Configure Google Pay Button

Configure Klarna

Configure Klarna via Adyen

Set Locale

Custom Success/Error Screens

Configure Dismissal Behavior

Configure Google Pay

Set Redirect Scheme

Set Payment Handling

Toggle Managed Screens

Configure Theme Colors

Handle Completion

Complete Example

Framework-Specific Patterns

Advanced Configuration

See also