Accept a payment using the Payment Setup API
Last updated: February 4, 2026
The Payment Setup API enables you to simplify the management of complex payment flows that cover multiple payment methods.
A payment setup dynamically updates the payment session based on the customer's interactions and the information they provide during checkout. This can help to:
- Maximize conversion and reduce friction for the customer by ensuring you only present payment methods that they can use.
- Provide enhanced visibility and control over the customer's checkout journey by dynamically updating the payment setup status.
- Reduce the number of payment failures. For example, due to missing information that the selected payment method requires or a currency does not support.
The Payment Setup API simplifies your payment methods integration by consolidating the following key functionalities. It enables you to:
- Simultaneously initiate all payment methods enabled on your account that the customer can use.
- Bundle initialization processes for payment methods that require multi-step initialization.
- Perform real-time validation of which payment methods are available and are most likely to result in a successful payment.
- Dynamically update the payment state based on customer input. For example, if the customer has not provided a field required by their selected payment method, you can prompt them for input to prevent a payment failure.
Create a payment setup to receive the list of available payment methods. We recommended creating a payment setup as soon as you know the transaction amount. For example, when the customer begins the checkout process. If the amount changes, you can update it later.
When creating the payment setup, provide any known customer and order information. For example, amount, currency, and country. The response returns the list of payment methods that are available for the customer.
Call the Create a payment setup endpoint.
In the request body, provide the following:
processing_channel_id– The processing channel's unique identifieramount– The payment amountcurrency– The payment currency
Information
Your base URL's {prefix} value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see API endpoints.
post
https://{prefix}.api.checkout.com/payments/setups
The response returns a payment_methods object, which contains the payment methods enabled on your account.
For each payment method, payment_methods contains the following fields:
flags– An array of error codes or indicators that highlight missing or invalid information which you can prompt the customer to providestatus– The status of the payment method
Update the payment setup whenever there are significant changes in the data relevant to the customer's transaction. For example, when the customer:
- Provides additional information – For example, their email, phone number, or shipping address
- Provides information or completes an action required by a payment method – For example, if they successfully authenticate using an OTP
- Makes a change that impacts the total payment amount – For example, they change the basket contents, select a faster delivery method, or apply a discount code
Call the Update a payment setup endpoint, and provide the updated customer or payment data in the respective fields. For example, the amount or customer.email fields. See each payment method's documentation for the specific fields they require.
Some payment methods require initialization before they can be used to confirm a payment.
Initialize a payment method in the payment setup to begin collecting data, or if the customer selects the payment method as the payment option during checkout.
For each initialized payment method, the payment setup dynamically:
- Triggers required actions – For example, generating a redirect URL, preparing an SDK session, or requesting one-time password (OTP) verification from the customer
- Updates the payment method's status
Call the Update a payment setup endpoint, and set initialization to enabled for each payment method you want to initialize.
To process the payment request with the customer's selected payment method option, you must first confirm the payment setup.
Call the Confirm a payment setup endpoint, and provide the payment method name as the {payment_method_name} path parameter.
Note
Only confirm payment methods that have ready status.
The payment method option status indicates whether a specific payment option provided by a payment method is available for the customer to use in the current transaction.
| Payment method option status | Description |
|---|---|
| The payment method option requires additional information or customer action before it's available to use. For example, the customer may need to provide a shipping address, or authenticate using an OTP. You may receive details of the additional requirements in the response's |
| The payment method provider is validating the payment method option. No action is required from you or the customer. |
| The payment method option can be used to confirm the payment. All required information was provided and additional actions completed. |