Configuring Checkout

Primer Checkout 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 } }
};

Two Types of Configuration

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.

Component Properties

These are HTML attributes that configure the checkout container.

client-token (required)

Your Primer API client token. Obtain this by creating a client session.

// ✅ 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>

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');

SDK Options

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.

Common Patterns

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
  }
};

Complete Example

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
  }
};

Framework-Specific Patterns

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.

Advanced Configuration

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
  }
};

What’s Next

SDK Options Reference

Complete list of all available options

Events Guide

Handle payment success, failure, and state changes

Styling

Customize colors, fonts, and spacing

Troubleshooting

Fix common configuration issues

Checkout

​Two Types of Configuration

​Component Properties

​client-token (required)

​custom-styles

​loader-disabled

​SDK Options

​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

​Complete Example

​Framework-Specific Patterns

​Advanced Configuration

​What’s Next

SDK Options Reference

Events Guide

Styling

Troubleshooting

Two Types of Configuration

Component Properties

client-token (required)

custom-styles

loader-disabled

SDK Options

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

Complete Example

Framework-Specific Patterns

Advanced Configuration

What’s Next