Primary vs. Secondary Payment Methods

The SDK supports multiple payment sources. You can distinguish between primary methods (credit cards, wallet...) and secondary ones (used to cover remaining balances, like gift cards).

Use the checkout.paymentMethods variable to access all payment methods.

• Primary methods: Used for initial payment and only one can be selected.
• Secondary methods: Supplementary payments (e.g. gift cards).

You can explicitly mark a method as the primary one:

selectedMethod.setAsPrimarySource()

By default, the last selected primary method is used for the main payment.

Conversely, you can remove the primary method from the primary split using checkout.clearPrimarySplit().

checkout.clearPrimarySplit();

Automatic Cleanup

When you remove a primary payment element using element.remove(), the primary split is automatically cleared. You no longer need to manually call clearPrimarySplit() in this case.

Payment Method Disabled States

Payment methods can be disabled for various reasons. Each disabled method includes a DisabledState object with a code and message.

Disabled State Codes

Code	Description
METHOD_UNSTABLE	The payment method is temporarily unavailable
TOKEN_INIT_FAILED	Failed to initialize the payment token
PAYMENT_ELEMENT_FATAL_ERROR	A critical error occurred in the payment element
PAYMENT_ELEMENT_RENDER_FAILED	The payment UI element failed to render
PARTNER_UI_FATAL_ERROR	A critical error occurred in the partner's payment interface
SUBMITTING	Payment is currently being processed
MIN_AMOUNT_NOT_MET	Transaction amount is below the minimum for this method
MAX_AMOUNT_EXCEEDED	Transaction amount exceeds the maximum for this method

Handling Disabled States

• Hide payment methods with PARTNER_UI_FATAL_ERROR from your UI
• Display other disabled methods with their message explaining why they're unavailable
• Check the disabled state before allowing submission

See the Headless Checkout API Reference for more details on handling disabled payment methods.