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

// Check if a method is disabled
if (creditCardMethod.disabled.value) {
    console.log('Method is disabled:', creditCardMethod.disabled.value.code);
    // Possible codes: MIN_AMOUNT_NOT_MET, MAX_AMOUNT_EXCEEDED
}

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

// Remove the element (automatically clears the split in v3.61+)
paymentElement.remove();

Payment elements are hosted securely and handle:

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

Removing a payment element with remove() automatically clears the payment split for primary methods. Secondary methods (gift cards) still require manual removeFromSplit() calls.

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 with a specific amount
await token.take(amount);

// Add a gift card to the split with full balance
await token.take();  // Automatically uses full balance for "max" policy

// Remove from split
token.removeFromSplit();
Amount Policy

Some payment tokens (like gift cards) support different amount policies:

  • Full: Use the entire balance of the token (for maxxing and easy2play voucher)
  • Partial: Use a specific amount from the token

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: