Accept a payment using the Payment Setup API

Last updated: July 10, 2025

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 are able to 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 required by the selected payment method, or use of a currency not supported by the payment method.

For payment methods that require a payment session, your integration typically requires calls to the following APIs:

Payment Method API – Retrieve the payment methods enabled on your account that are available for the customer to pay with.
Payment Context API - Create a payment session for payment methods that require it.
Payments API - Submit the payment request.

The Payment Setup API simplifies your integration for these payment methods by consolidating all of these key functionalities. It enables you to:

Simultaneously initiate all payment methods enabled on your account that the customer is able to 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 instantiate the payment methods and begin monitoring the information provided during checkout.

Information

To maximize the amount of information the payment setup can use, we recommend that you create a payment setup as early as possible in the customer's journey. For example, the first time they land on the basket page.

Call the Create a Payment Setup endpoint.

post

https://api.checkout.com/payments/setups


1{
2  "processing_channel_id": "pc_q4dbxom5jbgudnjzjpz7j2z6uq",
3  "currency": "GBP",
4  "amount": 1000,
5  "payment_type": "regular",
6  "settings": {
7    "success_url": "https://success.co.uk",
8    "failure_url": "https://failure.co.uk"
9  },
10  "order": {
11    "items": [
12      {
13        "name": "Shoes",
14        "quantity": 1,
15        "unit_price": 1000,
16        "total_amount": 1000,
17        "reference": "item-ref"
18      }
19    ]
20  },
21  "customer": {
22    "name": "Ali Farid",
23    "device": {
24      "locale": "en-GB"
25    }
26  }
27}


1{
2    "id": "set_cpbwwledtkju3mlwa2hoenisbm",
3    "processing_channel_id": "pc_b5jmsxqbxpeulpioz7v5dfxlj4",
4    "currency": "GBP",
5    "amount": 1000,
6    "payment_type": "regular",
7    "payment_methods": {
8        "klarna": {
9            "payment_method_status": "available",
10            "initialization": "disabled",
11            "flags": [
12                "initialization_not_enabled"
13            ]
14        }
15    },
16    "settings": {
17        "success_url": "https://success.co.uk",
18        "failure_url": "https://failure.co.uk"
19    },
20    "customer": {
21        "name": "Ali Farid",
22        "device": {
23            "locale": "en-GB"
24        }
25    },
26    "order": {
27        "items": [
28            {
29                "name": "Shoes",
30                "quantity": 1,
31                "unit_price": 1000,
32                "total_amount": 1000,
33                "reference": "item-ref"
34            }
35        ]
36    }
37}

The response returns a payment_methods object which contains the payment methods enabled on your account.

For each payment method, payment_methods provides the following fields:

flags – An array of error codes or indicators that highlight missing or invalid information which you can prompt the customer to provide
initialization – Specifies whether to initialize the payment method in the payment setup. This is set to disabled by default. You must explicitly enable the payment method when you update the payment setup.
options – The specific options provided by the payment method, if there is more than one
status – The status of the payment method

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.

You can initialize payment methods at any point until you confirm the payment.

For each initialized payment method, the payment setup dynamically:

Validates relevant user input
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.

put

https://api.checkout.com/payments/setups/{setup_id}


1{
2  "processing_channel_id": "pc_q4dbxom5jbgudnjzjpz7j2z6uq",
3  "currency": "GBP",
4  "amount": 1000,
5  "payment_type": "regular",
6  "payment_methods": {
7    "klarna": {
8      "initialization": "enabled",
9      "account_holder": {
10        "billing_address": {
11          "country": "GB"
12        }
13      }
14    }
15  },
16  "settings": {
17    "success_url": "https://success.co.uk",
18    "failure_url": "https://failure.co.uk"
19  },
20  "order": {
21    "items": [
22      {
23        "name": "Shoes",
24        "quantity": 1,
25        "unit_price": 1000,
26        "total_amount": 1000,
27        "reference": "item-ref"
28      }
29    ]
30  },
31  "customer": {
32    "name": "Ali Farid",
33    "device": {
34      "locale": "en-GB"
35    }
36  }
37}


1{
2  "processing_channel_id": "pc_q4dbxom5jbgudnjzjpz7j2z6uq",
3  "currency": "GBP",
4  "amount": 1000,
5  "payment_type": "regular",
6  "payment_methods": {
7        "KLARNA": {
8            "payment_method_status": "available",
9            "initialization": "enabled",
10            "flags": [],
11            "payment_method_options": {
12                "default": {
13                    "id": "opt_yscniq6msqfuxjvwp4tmecmlwq",
14                    "status": "action_required",
15                    "flags": [],
16                    "action": {
17                        "type": "sdk",
18                        "client_token": "sdk_12345",
19                        "session_id": "sess_12345"
20                    }
21                }
22            }
23        }
24    },
25  "settings": {
26    "success_url": "https://success.co.uk",
27    "failure_url": "https://failure.co.uk"
28  },
29  "order": {
30    "items": [
31      {
32        "name": "Shoes",
33        "quantity": 1,
34        "unit_price": 1000,
35        "total_amount": 1000,
36        "reference": "item-ref"
37      }
38    ]
39  },
40  "customer": {
41    "name": "Ali Farid",
42    "device": {
43      "locale": "en-GB"
44    }
45  }
46}

You should 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 via 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 their respective fields. For example, the amount or customer.email fields.

put

https://api.checkout.com/payments/setups/{setup_id}


1{
2  "processing_channel_id": "pc_q4dbxom5jbgudnjzjpz7j2z6uq",
3  "currency": "GBP",
4  "amount": 2000,
5  "payment_type": "regular",
6  "payment_methods": {
7    "klarna": {
8      "initialization": "enabled",
9      "account_holder": {
10        "billing_address": {
11          "country": "GB"
12        }
13      }
14    }
15  },
16  "settings": {
17    "success_url": "https://success.co.uk",
18    "failure_url": "https://failure.co.uk"
19  },
20  "order": {
21    "items": [
22      {
23        "name": "Shoes",
24        "quantity": 2,
25        "unit_price": 1000,
26        "total_amount": 2000,
27        "reference": "item-ref"
28      }
29    ]
30  },
31  "customer": {
32    "name": "Ali Farid",
33    "device": {
34      "locale": "en-GB"
35    }
36  }
37}


1{
2  "processing_channel_id": "pc_q4dbxom5jbgudnjzjpz7j2z6uq",
3  "currency": "GBP",
4  "amount": 2000,
5  "payment_type": "regular",
6  "payment_methods": {
7        "KLARNA": {
8            "payment_method_status": "available",
9            "initialization": "enabled",
10            "flags": [],
11            "payment_method_options": {
12                "default": {
13                    "id": "opt_yscniq6msqfuxjvwp4tmecmlwq",
14                    "status": "action_required",
15                    "flags": [],
16                    "action": {
17                        "type": "sdk",
18                        "client_token": "sdk_12345",
19                        "session_id": "sess_12345"
20                    }
21                }
22            }
23        }
24    },
25  "settings": {
26    "success_url": "https://success.co.uk",
27    "failure_url": "https://failure.co.uk"
28  },
29  "order": {
30    "items": [
31      {
32        "name": "Shoes",
33        "quantity": 2,
34        "unit_price": 1000,
35        "total_amount": 2000,
36        "reference": "item-ref"
37      }
38    ]
39  },
40  "customer": {
41    "name": "Ali Farid",
42    "device": {
43      "locale": "en-GB"
44    }
45  }
46}

Each payment method returned in the payment setup response contains an options object with the list of specific payment options available and their unique ID. For example, klarna.options may contain separate options for paying in full, paying in three installments, and paying in six installments.

The status of each payment method option dynamically updates depending on the state of the basket. When a payment option has sufficient data to be used to make a payment, the option's status changes to ready. For example, if the user adds all additional data required by Klarna, the payment method option becomes available for use.

To begin processing the payment request with your chosen payment method option, call the Confirm a Payment Setup endpoint and provide the option's ID as the option_id path parameter.

Note

If you attempt to process the payment with an option that does not have the ready status, the request fails.

post

https://api.checkout.com/payments/setups/{setup_id}/confirm/{option_id}


1{
2  "id": "pay_mbabizu24mvu3mela5njyhpit4",
3  "status": "Pending",
4  "payment_type": "Regular",
5  "_links": {
6    "self": {
7      "href": "https://api.sandbox.checkout.com/payments/pay_12345"
8    }
9  }
10}

The response contains a payment ID. You can call the Get payment details endpoint with the ID to retrieve the payment's details and monitor its status.

If you've set up your webhook receiver, you receive payment webhooks with details of the payment's status.

Information

If your confirmation attempt fails, you can retry using the same payment setup ID once you resolve any outstanding issues.

The availability and eligibility of the various layers of a payment setup are communicated via statuses:

Payment method status – The status of a specific payment method within the payment setup
Payment method option status – The status of a specific payment option provided by a payment method

The payment method status indicates whether a specific payment method is available for use by the customer in the current transaction.

Payment method status Description

Payment method status	Description
`available`	The payment method can be used in the current transaction. The payment method may still require additional data or further actions for individual payment method options it provides.
`unavailable`	The payment method cannot be used in the current transaction. This may be due to: An invalid configuration Unsupported transaction details – For example, the customer is paying in an unsupported currency A temporary issuer with the payment method provider

available

The payment method can be used in the current transaction.

The payment method may still require additional data or further actions for individual payment method options it provides.

unavailable

The payment method cannot be used in the current transaction.

This may be due to:

An invalid configuration
Unsupported transaction details – For example, the customer is paying in an unsupported currency
A temporary issuer with the payment method provider

The payment method option status indicates whether a specific payment option provided by a payment method is available for use by the customer in the current transaction.

Payment method option status	Description
`action_required`	The payment method option requires additional information or customer action before it's available for 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 `action` object.
`pending`	The payment method provider is validating the payment method option. No action is required from you or the customer.
`ready`	The payment method option can be used to confirm the payment. All required information was provided and additional actions completed.
`unavailable`	The payment method option cannot be used in the current transaction. This may be due to: A temporary issuer with the payment method provider Conditions required by the payment method option not being met Validation failures

Accept a payment using the Payment Setup API

How it works

Create the payment setup

Information

Request example

Response example

Initialize the payment methods

Request example

Response example

Update the payment setup

Request example

Response example

Confirm the payment

Note

Response example

Information

Statuses

Payment method status

Payment method option status