The Payment Setup API enables you to simplify the management of complex payment flows that cover multiple payment methods.
For more information, see Accept a payment using the Payment Setup API.
The Payment Setup API enables you to simplify the management of complex payment flows that cover multiple payment methods.
For more information, see Accept a payment using the Payment Setup API.
Beta
Creates a Payment Setup.
To maximize the information available to the payment setup, create a Payment Setup as early as possible in the customer's journey. For example, create it the first time they land on the basket page.
Pattern: ^(pc)_(\w{26})$The processing channel to use for the payment.
The amount and currency to present to the customer, when the settlement currency differs from the customer-facing currency.
The type of payment.
You must provide this field for card payments in which the cardholder is not present. For example, if the transaction is a recurring payment, or a mail order/telephone order (MOTO) payment.
A reference you can use to identify the payment. For example, an order number.
A description of the payment.
The payment methods that are enabled on your account and available for use.
Settings for the Payment Setup.
Risk assessment settings for the Payment Setup.
The customer's details.
The customer's order details.
Authentication failed. Provide a valid API key or access token.
You do not have permission to create a Payment Setup.
curl 'https://{prefix}.api.sandbox.checkout.com/payments/setups' \
--request POST \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
--data '{
"processing_channel_id": "pc_q4dbxom5jbgudnjzjpz7j2z6uq",
"amount": 10000,
"currency": "GBP",
"presentment_details": {
"amount": 110,
"currency": "EUR"
},
"payment_type": "regular",
"reference": "REF-0987-475",
"description": "Set of 3 t-shirts",
"payment_methods": {
"auto_confirm": "card",
"instrument": {
"id": "src_wmlfc3zttb4uzmk6snpwb43jbi"
},
"klarna": {
"initialization": "disabled"
},
"stcpay": {
"initialization": "disabled",
"otp": "123456"
},
"tabby": {
"initialization": "disabled",
"payment_types": [
"pay_later"
]
},
"qpay": {
"national_id": "21234567890",
"description": ""
},
"ideal": {
"description": "2 t-shirts"
},
"knet": {
"language": "en"
},
"bancontact": {
"account_holder_name": ""
},
"blik": {
"partner_code": "999111"
},
"alipay_cn": {
"terminal_type": "web",
"os_type": "android"
},
"alipay_hk": {
"terminal_type": "web",
"os_type": "android"
},
"gcash": {
"terminal_type": "web",
"os_type": "android"
},
"tng": {
"terminal_type": "web",
"os_type": "android"
},
"dana": {
"terminal_type": "web",
"os_type": "android"
},
"tamara": {
"initialization": "disabled",
"risk_assessment": {
"premium_customer": false,
"risk_score": 42,
"order_count_last24h": 0,
"linked_device_count": 2
}
},
"multibanco": {
"account_holder_name": ""
},
"kakaopay": {
"terminal_type": "web",
"os_type": "android"
},
"truemoney": {
"terminal_type": "web",
"os_type": "android"
},
"p24": {
"account_holder": {
"name": "",
"email": ""
}
},
"alma": {},
"swish": {
"billing_descriptor": "",
"account_holder": {
"first_name": "John",
"last_name": "Smith"
}
},
"sequra": {},
"ach": {
"account_type": "savings",
"account_holder": {
"type": "individual",
"first_name": "",
"last_name": "",
"company_name": "",
"date_of_birth": "",
"identification": {
"type": "",
"issuing_country": "",
"number": ""
}
},
"account_number": "",
"bank_code": "",
"country": ""
},
"sepa": {
"account_holder": {
"type": "individual",
"first_name": "",
"last_name": "",
"company_name": ""
},
"account_number": "",
"country": "",
"currency": "",
"mandate": {
"id": "",
"type": "core",
"date_of_signature": ""
}
},
"bacs": {
"initialization": "disabled",
"account_holder": {
"type": "individual",
"first_name": "",
"last_name": "",
"company_name": "",
"email": "john.smith@example.com"
},
"account_number": "",
"bank_code": "",
"country": "",
"currency": "",
"allow_partial_match": false
},
"paybybank": {
"bank_id": "ob-natwest"
},
"paypal": {
"initialization": "disabled",
"user_action": "pay_now",
"brand_name": "Acme Corporation",
"shipping_preference": "no_shipping"
},
"googlepay": {
"token_data": {
"protocol_version": "",
"signature": "",
"signed_message": "",
"tokenization_key": ""
},
"token": {
"id": "",
"expires_on": ""
},
"store_for_future_use": true,
"phone": {
"country_code": "+44",
"number": "207 946 0000"
},
"account_holder": {
"type": "individual",
"first_name": "",
"last_name": "",
"middle_name": "",
"company_name": "",
"account_name_inquiry": true
},
"preferred_scheme": "visa"
},
"applepay": {
"token_data": {
"version": "",
"data": "",
"signature": "",
"header": {
"ephemeral_public_key": "",
"public_key_hash": "",
"transaction_id": ""
}
},
"token": {
"id": "",
"expires_on": ""
},
"store_for_future_use": true,
"phone": {
"country_code": "+44",
"number": "207 946 0000"
},
"account_holder": {
"type": "individual",
"first_name": "",
"last_name": "",
"middle_name": "",
"company_name": "",
"account_name_inquiry": true
},
"preferred_scheme": "visa"
},
"card": {
"token": {
"id": ""
},
"details": {
"number": "",
"expiry_month": 1,
"expiry_year": 1,
"name": "",
"cvv": "",
"stored": true,
"allow_update": true
},
"store_for_future_use": true,
"phone": {
"country_code": "+44",
"number": "207 946 0000"
},
"account_holder": {
"type": "individual",
"first_name": "",
"last_name": "",
"middle_name": "",
"company_name": "",
"account_name_inquiry": true
},
"preferred_scheme": "visa"
},
"stablecoin": {}
},
"settings": {
"success_url": "https://example.com/payments/success",
"failure_url": "https://example.com/payments/fail",
"capture": true,
"excluded_payment_methods": [
"card",
"klarna",
"stcpay"
]
},
"risk": {
"enabled": true
},
"customer": {
"country": "GB",
"id": "cus_123456789",
"email": {
"address": "johnsmith@example.com",
"verified": true
},
"name": "John Smith",
"tax_number": "GB123456789",
"phone": {
"country_code": "+44",
"number": "207 946 0000"
},
"device": {
"locale": "en_GB"
},
"merchant_account": {
"id": "1234",
"registration_date": "2023-05-01",
"last_modified": "2023-05-01",
"returning_customer": true,
"first_transaction_date": "2023-09-15",
"last_transaction_date": "2025-03-28",
"total_order_count": 6,
"last_payment_amount": 55.99
}
},
"order": {
"items": [
{
"name": "Battery Power Pack",
"quantity": 1,
"unit_price": 1000,
"total_amount": 1000,
"reference": "BA67A",
"discount_amount": 150,
"url": "https://example.com/products/my-item",
"image_url": "https://example.com/products/my-item/image",
"type": "digital"
}
],
"shipping": {
"first_name": "Jane",
"last_name": "Doe",
"email": "jane.doe@example.com",
"phone": {
"country_code": "+44",
"number": "207 946 0000"
},
"address": {
"address_line1": "10 Canterbury Road",
"address_line2": "Flat 2",
"city": "London",
"state": "Greater London",
"zip": "NE1 1KO",
"country": "GB"
},
"method": "",
"delay": 3
},
"sub_merchants": [
{
"id": "SUB12345",
"product_category": "Electronics",
"number_of_sales": 500,
"registration_date": "2023-01-15"
}
],
"invoice_id": "inv_123456789",
"shipping_amount": 5,
"discount_amount": 10,
"tax_amount": 2,
"tipping_amount": 2,
"surcharge_amount": 2,
"amount_allocations": [
{
"id": "ent_w4jelhppmfiufdnatam37wrfc4",
"amount": 1000,
"reference": "ORD-5023-4E89",
"commission": {
"amount": 1000,
"percentage": 1.125
}
}
]
},
"billing": {
"address": {
"address_line1": "10 Canterbury Road",
"address_line2": "Flat 2",
"city": "London",
"state": "Greater London",
"zip": "NE1 1KO",
"country": "GB"
}
},
"industry": {
"airline": [
{
"ticket": {
"number": "0742464639523",
"issue_date": "2025-05-01",
"issuing_carrier_code": "042",
"travel_package_indicator": "A",
"travel_agency_name": "Checkout Travel Agents",
"travel_agency_code": "91114362"
},
"passengers": [
{
"first_name": "John",
"last_name": "Smith",
"date_of_birth": "1990-10-31",
"address": {
"country": "GB"
}
}
],
"flight_leg_details": [
{
"flight_number": "BA1483",
"carrier_code": "BA",
"class_of_travelling": "W",
"departure_airport": "LHR",
"departure_date": "2025-10-13",
"departure_time": "18:30",
"arrival_airport": "JFK",
"stop_over_code": "X",
"fare_basis_code": "WUP14B"
}
],
"total_number_of_passengers": 1,
"travel_type": "international",
"trip_type": "one_way",
"refundable": true,
"delivery_recipient": "jane.smith@example.com",
"ancillaries": "extra_baggage",
"insurance": {
"type": "travel",
"company": "AXA",
"price": {
"amount": 500,
"currency": "SAR"
}
}
}
],
"accommodation": [
{
"name": "Checkout Lodge",
"booking_reference": "REF9083748",
"check_in_date": "2025-04-11",
"check_out_date": "2025-04-18",
"address": {
"address_line1": "123 High Street",
"city": "London",
"state": "Greater London",
"country": "GB",
"zip": "NE1 1CK"
},
"number_of_rooms": 2,
"guests": [
{
"first_name": "John",
"last_name": "Smith",
"date_of_birth": "1970-03-19"
}
],
"room": [
{
"rate": 42.3,
"number_of_nights": 5,
"type": "deluxe"
}
],
"total_number_of_guests": 2,
"refundable": true,
"delivery_recipient": "jane.smith@example.com",
"host": {
"registration_date": "2020-01-01",
"total_reservation_count": 150
}
}
]
},
"account_funding_transaction": {
"enabled": true,
"purpose": "financial_services",
"sender": {
"date_of_birth": "2000-01-01",
"reference": "0fc88634-78c1-4286-9cb6-6ca358730c8c",
"identification": {
"type": "passport",
"number": "1234567890",
"issuing_country": "US"
}
},
"recipient": {
"date_of_birth": "2000-01-01",
"account_number": "",
"first_name": "",
"last_name": "",
"address": {
"address_line1": "10 Canterbury Road",
"address_line2": "Flat 2",
"city": "London",
"state": "Greater London",
"zip": "NE1 1KO",
"country": "GB"
}
}
},
"terminal": {
"id": "12345678",
"local_date_time": "2026-05-26T13:05:14+01:00"
},
"billing_descriptor": {
"name": "Checkout.com",
"city": "London",
"reference": "Payment for order 123456"
},
"metadata": {
"additionalProperty": ""
}
}'
{ "id": "string", "processing_channel_id": "pc_q4dbxom5jbgudnjzjpz7j2z6uq", "amount": 10000, "currency": "GBP", "presentment_details": { "amount": 110, "currency": "EUR" }, "payment_type": "regular",Beta
Updates a Payment Setup.
Update the Payment Setup whenever there are significant changes in the data relevant to the customer's transaction. For example, when the customer makes a change that impacts the total payment amount.
The unique identifier of the Payment Setup to update.
Pattern: ^(pc)_(\w{26})$The processing channel to use for the payment.
The amount and currency to present to the customer, when the settlement currency differs from the customer-facing currency.
The type of payment.
You must provide this field for card payments in which the cardholder is not present. For example, if the transaction is a recurring payment, or a mail order/telephone order (MOTO) payment.
A reference you can use to identify the payment. For example, an order number.
A description of the payment.
The payment methods that are enabled on your account and available for use.
Settings for the Payment Setup.
Risk assessment settings for the Payment Setup.
The customer's details.
The customer's order details.
Authentication failed. Provide a valid API key or access token.
You do not have permission to update this Payment Setup.
curl 'https://{prefix}.api.sandbox.checkout.com/payments/setups/{id}' \
--request PUT \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
--data '{
"processing_channel_id": "pc_q4dbxom5jbgudnjzjpz7j2z6uq",
"amount": 10000,
"currency": "GBP",
"presentment_details": {
"amount": 110,
"currency": "EUR"
},
"payment_type": "regular",
"reference": "REF-0987-475",
"description": "Set of 3 t-shirts",
"payment_methods": {
"auto_confirm": "card",
"instrument": {
"id": "src_wmlfc3zttb4uzmk6snpwb43jbi"
},
"klarna": {
"initialization": "disabled"
},
"stcpay": {
"initialization": "disabled",
"otp": "123456"
},
"tabby": {
"initialization": "disabled",
"payment_types": [
"pay_later"
]
},
"qpay": {
"national_id": "21234567890",
"description": ""
},
"ideal": {
"description": "2 t-shirts"
},
"knet": {
"language": "en"
},
"bancontact": {
"account_holder_name": ""
},
"blik": {
"partner_code": "999111"
},
"alipay_cn": {
"terminal_type": "web",
"os_type": "android"
},
"alipay_hk": {
"terminal_type": "web",
"os_type": "android"
},
"gcash": {
"terminal_type": "web",
"os_type": "android"
},
"tng": {
"terminal_type": "web",
"os_type": "android"
},
"dana": {
"terminal_type": "web",
"os_type": "android"
},
"tamara": {
"initialization": "disabled",
"risk_assessment": {
"premium_customer": false,
"risk_score": 42,
"order_count_last24h": 0,
"linked_device_count": 2
}
},
"multibanco": {
"account_holder_name": ""
},
"kakaopay": {
"terminal_type": "web",
"os_type": "android"
},
"truemoney": {
"terminal_type": "web",
"os_type": "android"
},
"p24": {
"account_holder": {
"name": "",
"email": ""
}
},
"alma": {},
"swish": {
"billing_descriptor": "",
"account_holder": {
"first_name": "John",
"last_name": "Smith"
}
},
"sequra": {},
"ach": {
"account_type": "savings",
"account_holder": {
"type": "individual",
"first_name": "",
"last_name": "",
"company_name": "",
"date_of_birth": "",
"identification": {
"type": "",
"issuing_country": "",
"number": ""
}
},
"account_number": "",
"bank_code": "",
"country": ""
},
"sepa": {
"account_holder": {
"type": "individual",
"first_name": "",
"last_name": "",
"company_name": ""
},
"account_number": "",
"country": "",
"currency": "",
"mandate": {
"id": "",
"type": "core",
"date_of_signature": ""
}
},
"bacs": {
"initialization": "disabled",
"account_holder": {
"type": "individual",
"first_name": "",
"last_name": "",
"company_name": "",
"email": "john.smith@example.com"
},
"account_number": "",
"bank_code": "",
"country": "",
"currency": "",
"allow_partial_match": false
},
"paybybank": {
"bank_id": "ob-natwest"
},
"paypal": {
"initialization": "disabled",
"user_action": "pay_now",
"brand_name": "Acme Corporation",
"shipping_preference": "no_shipping"
},
"googlepay": {
"token_data": {
"protocol_version": "",
"signature": "",
"signed_message": "",
"tokenization_key": ""
},
"token": {
"id": "",
"expires_on": ""
},
"store_for_future_use": true,
"phone": {
"country_code": "+44",
"number": "207 946 0000"
},
"account_holder": {
"type": "individual",
"first_name": "",
"last_name": "",
"middle_name": "",
"company_name": "",
"account_name_inquiry": true
},
"preferred_scheme": "visa"
},
"applepay": {
"token_data": {
"version": "",
"data": "",
"signature": "",
"header": {
"ephemeral_public_key": "",
"public_key_hash": "",
"transaction_id": ""
}
},
"token": {
"id": "",
"expires_on": ""
},
"store_for_future_use": true,
"phone": {
"country_code": "+44",
"number": "207 946 0000"
},
"account_holder": {
"type": "individual",
"first_name": "",
"last_name": "",
"middle_name": "",
"company_name": "",
"account_name_inquiry": true
},
"preferred_scheme": "visa"
},
"card": {
"token": {
"id": ""
},
"details": {
"number": "",
"expiry_month": 1,
"expiry_year": 1,
"name": "",
"cvv": "",
"stored": true,
"allow_update": true
},
"store_for_future_use": true,
"phone": {
"country_code": "+44",
"number": "207 946 0000"
},
"account_holder": {
"type": "individual",
"first_name": "",
"last_name": "",
"middle_name": "",
"company_name": "",
"account_name_inquiry": true
},
"preferred_scheme": "visa"
},
"stablecoin": {}
},
"settings": {
"success_url": "https://example.com/payments/success",
"failure_url": "https://example.com/payments/fail",
"capture": true,
"excluded_payment_methods": [
"card",
"klarna",
"stcpay"
]
},
"risk": {
"enabled": true
},
"customer": {
"country": "GB",
"id": "cus_123456789",
"email": {
"address": "johnsmith@example.com",
"verified": true
},
"name": "John Smith",
"tax_number": "GB123456789",
"phone": {
"country_code": "+44",
"number": "207 946 0000"
},
"device": {
"locale": "en_GB"
},
"merchant_account": {
"id": "1234",
"registration_date": "2023-05-01",
"last_modified": "2023-05-01",
"returning_customer": true,
"first_transaction_date": "2023-09-15",
"last_transaction_date": "2025-03-28",
"total_order_count": 6,
"last_payment_amount": 55.99
}
},
"order": {
"items": [
{
"name": "Battery Power Pack",
"quantity": 1,
"unit_price": 1000,
"total_amount": 1000,
"reference": "BA67A",
"discount_amount": 150,
"url": "https://example.com/products/my-item",
"image_url": "https://example.com/products/my-item/image",
"type": "digital"
}
],
"shipping": {
"first_name": "Jane",
"last_name": "Doe",
"email": "jane.doe@example.com",
"phone": {
"country_code": "+44",
"number": "207 946 0000"
},
"address": {
"address_line1": "10 Canterbury Road",
"address_line2": "Flat 2",
"city": "London",
"state": "Greater London",
"zip": "NE1 1KO",
"country": "GB"
},
"method": "",
"delay": 3
},
"sub_merchants": [
{
"id": "SUB12345",
"product_category": "Electronics",
"number_of_sales": 500,
"registration_date": "2023-01-15"
}
],
"invoice_id": "inv_123456789",
"shipping_amount": 5,
"discount_amount": 10,
"tax_amount": 2,
"tipping_amount": 2,
"surcharge_amount": 2,
"amount_allocations": [
{
"id": "ent_w4jelhppmfiufdnatam37wrfc4",
"amount": 1000,
"reference": "ORD-5023-4E89",
"commission": {
"amount": 1000,
"percentage": 1.125
}
}
]
},
"billing": {
"address": {
"address_line1": "10 Canterbury Road",
"address_line2": "Flat 2",
"city": "London",
"state": "Greater London",
"zip": "NE1 1KO",
"country": "GB"
}
},
"industry": {
"airline": [
{
"ticket": {
"number": "0742464639523",
"issue_date": "2025-05-01",
"issuing_carrier_code": "042",
"travel_package_indicator": "A",
"travel_agency_name": "Checkout Travel Agents",
"travel_agency_code": "91114362"
},
"passengers": [
{
"first_name": "John",
"last_name": "Smith",
"date_of_birth": "1990-10-31",
"address": {
"country": "GB"
}
}
],
"flight_leg_details": [
{
"flight_number": "BA1483",
"carrier_code": "BA",
"class_of_travelling": "W",
"departure_airport": "LHR",
"departure_date": "2025-10-13",
"departure_time": "18:30",
"arrival_airport": "JFK",
"stop_over_code": "X",
"fare_basis_code": "WUP14B"
}
],
"total_number_of_passengers": 1,
"travel_type": "international",
"trip_type": "one_way",
"refundable": true,
"delivery_recipient": "jane.smith@example.com",
"ancillaries": "extra_baggage",
"insurance": {
"type": "travel",
"company": "AXA",
"price": {
"amount": 500,
"currency": "SAR"
}
}
}
],
"accommodation": [
{
"name": "Checkout Lodge",
"booking_reference": "REF9083748",
"check_in_date": "2025-04-11",
"check_out_date": "2025-04-18",
"address": {
"address_line1": "123 High Street",
"city": "London",
"state": "Greater London",
"country": "GB",
"zip": "NE1 1CK"
},
"number_of_rooms": 2,
"guests": [
{
"first_name": "John",
"last_name": "Smith",
"date_of_birth": "1970-03-19"
}
],
"room": [
{
"rate": 42.3,
"number_of_nights": 5,
"type": "deluxe"
}
],
"total_number_of_guests": 2,
"refundable": true,
"delivery_recipient": "jane.smith@example.com",
"host": {
"registration_date": "2020-01-01",
"total_reservation_count": 150
}
}
]
},
"account_funding_transaction": {
"enabled": true,
"purpose": "financial_services",
"sender": {
"date_of_birth": "2000-01-01",
"reference": "0fc88634-78c1-4286-9cb6-6ca358730c8c",
"identification": {
"type": "passport",
"number": "1234567890",
"issuing_country": "US"
}
},
"recipient": {
"date_of_birth": "2000-01-01",
"account_number": "",
"first_name": "",
"last_name": "",
"address": {
"address_line1": "10 Canterbury Road",
"address_line2": "Flat 2",
"city": "London",
"state": "Greater London",
"zip": "NE1 1KO",
"country": "GB"
}
}
},
"terminal": {
"id": "12345678",
"local_date_time": "2026-05-26T13:05:14+01:00"
},
"billing_descriptor": {
"name": "Checkout.com",
"city": "London",
"reference": "Payment for order 123456"
},
"metadata": {
"additionalProperty": ""
}
}'
{ "id": "string", "processing_channel_id": "pc_q4dbxom5jbgudnjzjpz7j2z6uq", "amount": 10000, "currency": "GBP", "presentment_details": { "amount": 110, "currency": "EUR" }, "payment_type": "regular",Beta
Retrieves a Payment Setup by its unique identifier.
The unique identifier of the Payment Setup to retrieve.
Authentication failed. Provide a valid API key.
You do not have permission to retrieve this Payment Setup.
curl 'https://{prefix}.api.sandbox.checkout.com/payments/setups/{id}' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{ "id": "string", "processing_channel_id": "pc_q4dbxom5jbgudnjzjpz7j2z6uq", "amount": 10000, "currency": "GBP", "presentment_details": { "amount": 110, "currency": "EUR" }, "payment_type": "regular",Beta
Confirm a Payment Setup to begin processing the payment request with your chosen payment method.
The unique identifier of the Payment Setup.
The name of the payment method to process the payment with (For example, tabby, klarna, card).
Authentication failed. Provide a valid API key or access token.
You do not have permission to update this Payment Setup.
curl 'https://{prefix}.api.sandbox.checkout.com/payments/setups/{id}/confirm/{payment_method_name}' \
--request POST \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{ "id": "string", "processing_channel_id": "pc_q4dbxom5jbgudnjzjpz7j2z6uq", "amount": 10000, "currency": "GBP", "presentment_details": { "amount": 110, "currency": "EUR" }, "payment_type": "regular",