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();
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_ERRORfrom 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.