Skip to main content

Key Concepts

Before diving into implementation details, it's important to understand the core concepts and terminology used in Purse Headless Checkout for managing payment methods.

Payment Methods vs. Payment Tokens​

Payment Methods​

A payment method represents a type of payment that can be used (e.g., credit card, gift card, PayPal). Payment methods are available options that customers can choose from during checkout.

// Access available payment methods
const methods = checkout.paymentMethods.value;
const creditCardMethod = methods.find((method) => method.method === "creditcard");

Payment Tokens​

A payment token represents a saved or registered payment instrument that can be reused. Tokens are created when:

  • A customer saves a payment method for future use
  • A gift card is added to the session
  • A customer uses a previously saved payment method
// Access saved payment tokens
const tokens = checkout.paymentTokens.value;

Primary vs. Secondary Payment Methods​

Primary Methods​

A single primary method is used for the main payment and always takes the remainder of the balance. Examples include:

  • Credit/debit cards
  • Digital wallets (Apple Pay, Google Pay, PayPal)
  • Bank transfers
// Set a method as the primary payment source
method.setAsPrimarySource();

Secondary Methods​

Secondary methods are applied to the outstanding balance to complement the primary payment. Examples include:

  • Gift cards
  • Loyalty cards
  • Store credit

Unlike primary methods, multiple secondary methods can be used in a single transaction.

// Check if a method is secondary
if (method.isSecondary) {
    // Handle as secondary method
}

Payment Sessions​

Client Session (PaymentSession)​

A client session contains the transaction details such as:

  • Available payment methods and their settings
  • Transaction context (amount, currency, etc.)

Update the client session when cart details change:

await checkout.setSession(newSession);

Wallet Session​

A wallet session is required to manage saved payment methods. It enables:

  • Editing token names
  • Deleting saved tokens
await checkout.setWalletSession(walletSession);
Session Types

Use a PaymentSession for checkout flows and a WalletSession for managing saved payment methods in account settings.

Payment Elements​

A payment element is a UI component that handles secure payment data entry. The SDK provides payment elements for:

  • Credit card details (PAN, expiry, CVV)
  • CVV entry for saved cards
  • Alternative Payment Methods like BNPL or Installments
// Get a payment element for a method
const paymentElement = method.getPaymentElement();
paymentElement.appendTo(document.getElementById("form"));

Payment elements are hosted securely and handle:

  • PCI-compliant data collection
  • Input validation
  • Error messaging
  • Styling customization

Registration and Tokenization​

Registration​

Registration is the process of saving a payment method for future use. When a payment method is registered:

  1. The payment details are securely tokenized
  2. A reusable token is created
  3. The token can be used in future transactions
// Register a payment method with a custom name
method.register(true, {name: "My Visa Card"});

Registration State​

You can track the registration state using reactive variables:

method.registration.subscribe((registration) => {
    if (registration.registered) {
        console.log(`Will be saved as: ${registration.name}`);
    }
});
Registration Availability

Not all payment methods support registration. Check with your account manager to enable this feature for specific payment methods.

Payment Splits​

A payment split defines how the total amount is divided among different payment sources.

Primary Split​

The primary split represents the main payment source. Only one primary method can be in the primary split at a time.

// Clear the current primary split
checkout.clearPrimarySplit();

Secondary Split​

The secondary split contains supplementary payment sources (e.g., gift cards). Multiple secondary methods can be in the split simultaneously.

// Add a gift card to the split
await token.take(amount);

// Remove from split
token.removeFromSplit();

Reactive Variables​

The SDK uses reactive variables that automatically notify subscribers when values change. This enables real-time UI updates.

// Subscribe to payment methods changes
checkout.paymentMethods.subscribe((methods) => {
    // Update UI with new methods
    displayMethods(methods);
});

// Subscribe to payment tokens changes
checkout.paymentTokens.subscribe((tokens) => {
    // Update UI with saved tokens
    displayTokens(tokens);
});

Validation​

Built-in Validation​

Payment elements include built-in validation for:

  • Card number format
  • Expiry date validity
  • CVV length
  • Required fields

Next Steps​

Now that you understand the core concepts, explore the implementation guides: