Skip to main content

headless-checkout changelog

3.67.1 — 2026-05-20​

This release enhances the reliability of Google Pay payments for our Ingenico/Worldline merchants by correcting configuration defaults, preventing silent tokenization failures. Additionally, we've fixed an issue ensuring that payment tokens saved in the wallet display their correct names.

Fixes​

  • Google Pay : Ingenico/Worldline : Google Pay tokenization now uses the correct default gateway and narrower network list when specific payment product data is unavailable, preventing silent payment failures.
  • The payment token wallet now correctly uses the name field for saved payment tokens and ensures the editTokenName API path is correct.

3.67.0 — 2026-05-19​

We've added new capabilities for a smoother payment experience and enhanced developer tooling. Buyers can now customize their PayPal button appearance, while developers benefit from a streamlined way to create PaymentElement instances and readily access payment method icons.

Features​

  • PayPal : Developers can now disable the maximum width applied to the PayPal button.

    The new disableMaxWidth option can be passed in XPayButtonUIOptions['paypal'] to prevent the PayPal button from expanding to its container's full width.

    interface XPayButtonUIOptions {
      paypal?: {
        disableMaxWidth?: boolean;
        // ... other PayPal button options
      };
    }

    // Example usage:
    checkout.getPaymentElement({
      partner: 'paypal',
      method: 'paypal',
      paypal: {
        disableMaxWidth: true,
      },
    });

  • Developers can now create a PaymentElement directly from the checkout instance.

    A new shortcut method, checkout.getPaymentElement(), simplifies the creation and rendering of a single payment method's UI.

    // Before: More verbose for a single method
    // const checkout = new PurseHeadlessCheckout(...);
    // const paymentMethods = await checkout.getPaymentMethods();
    // const specificMethod = paymentMethods.find(
    //   (pm) => pm.partner === 'ingenico' && pm.method === 'creditcard'
    // );
    // if (specificMethod) {
    //   const el = specificMethod.getPaymentElement({ theme: {} });
    //   el.appendTo('#container');
    // }

    // After: Simplified approach
    const el = checkout.getPaymentElement({
      partner: 'ingenico',
      method: 'creditcard', // 'method' is optional for hosted fields
      theme: { /* ... */ },
      hostedForm: { /* ... */ }, // Options specific to hosted forms
      hostedFields: { /* ... */ }, // Options specific to hosted fields
    });

    el.on('ready', () => console.log('PaymentElement is ready.'));
    el.appendTo('#container');

  • Payment methods and secondary tokens now expose an iconUrl.

    Integrators can now easily display official icons for payment methods and secondary tokens by accessing the new iconUrl property.

    interface PaymentMethod {
      // ... existing properties
      iconUrl: string | null;
    }

    interface BuiltSecondaryToken {
      // ... existing properties
      iconUrl: string | null;
    }

    // Example usage:
    const paymentMethods = await checkout.getPaymentMethods();
    paymentMethods.forEach((method) => {
      if (method.iconUrl) {
        console.log(`Icon for ${method.name}: ${method.iconUrl}`);
      }
    });

Fixes​

  • Apple Pay : The payment sheet now handles cancellation gracefully without crashing.

  • Secondary payment tokens now correctly map payment data from API responses, and currency is consistently sourced from the payment session.

    Dedicated mappers ensure accurate data extraction for secondary tokens, including those from partners like Illicado, Easy2play giftcard, Mybeezbox, and Ogloba. This includes migrating from deprecated payment_data.card to payment_data.cards[0] for card-based secondary tokens.

    currencyCode has been removed from BuiltSecondaryToken, PurseHeadlessCheckoutSecondaryToken, and PartialSecondaryToken types. Integrators should now retrieve the currency directly from the payment session, which serves as the single source of truth.

  • The SDK now properly handles redirections, preventing crashes when a validation result lacks a redirect URL.

  • The cardholder name field no longer accepts semicolons.

  • Wallet sessions are now correctly parsed from widget_data when available.

  • Off-session payments no longer incorrectly filter amounts.

3.66.0 — 2026-05-06​

This release expands payment options by introducing Apple Pay and Google Pay for Sogecommerce, PayPal BNPL, and Younited Installments. We've also enhanced Oney card support to correctly collect birthdates for private cards and added a noCVV mode for more flexible card form integrations.

Features​

  • Alma : Alma payment sessions now validate before displaying the popup.

    This prevents 'ghost sessions' with Alma when buyers close the popup prematurely, ensuring session consistency between Purse and Alma.

  • Oney : The card form now correctly collects a birthdate instead of a CVV for Oney private cards.

    For Oney private cards, the card form dynamically adapts to collect the buyer's birthdate instead of the CVV. This ensures accurate data collection for Oney payments.

  • PayPal : Introduce a new BNPL plugin for PayPal payments.

  • Sogecommerce : Buyers can now pay using Apple Pay and Google Pay via xPay.

  • Younited : Buyers can now pay using Younited Installments.

  • Enable an optional noCVV mode for card forms.

    Integrators can now configure the card form to optionally collect the CVV by setting the noCVV flag on PaymentElement initialization. This allows for use cases where CVV collection is not always required for specific card brands or payment flows.

    const paymentElement = purse.initPaymentElement({
      // ... other config
      card: {
        noCVV: true // CVV field becomes optional
      }
    });

Fixes​

  • Adyen : Redirection for 3DS challenges is now handled by the headless checkout manager, ensuring consistent behavior.

  • ANCV : Cancellation of ANCV Connect polling is now reliable.

  • ANCV : Correctly handle "Other Transaction Pending" errors for ANCV sessions.

  • Lyra : Prevent 725 errors when a payment button is not explicitly clicked.

  • Lyra : 3DS authentication is now correctly skipped when the validation response does not provide an authentication URL.

  • Maxxing : Correctly generate token IDs for Maxxing loyalty, resolving issues with loyalty program availability.

  • Support for information requests in the headless checkout.

    Payment methods compatible with OFF_SESSION registrations are now correctly displayed and activated, allowing for payments even with zero-amount initial requests.

  • Ensure payment method splits are correctly processed when using the onBeforeValidate hook.

  • Centralize final redirection handling within the manager, preventing double redirection calls.

  • Hosted fields for CVV inputs now use a unique prefix to prevent conflicts between token and new card forms.

    This resolves an issue where the CVV field could be duplicated or misbehave when quickly switching between a saved card token form and a new card entry form, especially on slow networks (SDK-11545).

  • The vault module now waits for the 'ready' event before resolving its boot promise, improving stability.

  • Card brand names in the vault are now displayed with natural language, instead of SCREAMING_SNAKE_CASE.

  • The system now emits a 'died' event when a payment plugin is not found, providing clearer error feedback.

    This prevents unknown plugins from occupying slots in xPay displays when a template is not properly configured (SDK-11514).