Card payments for Payment Setup API

Last updated: June 24, 2026

To accept card payments, you must:

Create a payment setup.
Update the payment setup with the card details.
Confirm the payment.

Call the Create a payment setup endpoint.

Information

The Payment Setup API supports idempotency. You can safely retry API requests without the risk of duplicate requests.

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


1{
2  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
3  "currency": "USD",
4  "amount": 2000,
5  "reference": "ORDER_01234",
6  "description": "Card payment",
7  "payment_type": "Regular",
8  "settings": {
9    "success_url": "https://example.com/payments/success",
10    "failure_url": "https://example.com/payments/failure"
11  }
12}

In the request body, provide the following:

processing_channel_id – The processing channel's unique identifier
amount – The payment amount
currency – The payment currency


1{
2  "id": "set_rcmepwrchqab2wsergcafvijfy",
3  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
4  "amount": 2000,
5  "currency": "USD",
6  "payment_type": "Regular",
7  "reference": "ORDER_01234",
8  "description": "Card payment",
9  "payment_methods": {
10    "card": {
11      "status": "pending",
12      "flags": []
13    }
14  },
15  "available_payment_methods": [
16    "card"
17  ],
18  "settings": {
19    "success_url": "https://example.com/payments/success",
20    "failure_url": "https://example.com/payments/failure"
21  }
22}

For card, payment_methods contains the following fields:

status – The status of the payment method.
flags – An array of error codes or indicators that highlight missing or invalid information.

When the customer selects card as the payment method on the checkout page, collect their card details and call the Update a payment setup endpoint to submit them.

You can provide either a card token or the full card details.

A token is a secure representation of sensitive payment details. Requesting a payment with the token ensures that the details do not reach your server.

When updating the payment setup, provide the following fields:

Field Description

Field	Description
`payment_methods.card.token` object	A Checkout.com token representing the card. Required if `payment_methods.card.details` is not provided.
`payment_methods.card.token.id` string	The token identifier, prefixed by `tok_`. Required
`payment_methods.card.account_holder.type` string	The card account holder type. Supported values: `individual` `corporate` `government` Required
`payment_methods.card.account_holder.first_name` string	The card account holder's first name. Max length: 35 Required
`payment_methods.card.account_holder.last_name` string	The card account holder's last name. Max length: 35 Required
`payment_methods.card.account_holder.middle_name` string	The card account holder's middle name. Max length: 35
`payment_methods.card.account_holder.account_name_inquiry` boolean	Indicates whether the ANI (account name inquiry) check is performed with the card scheme (Visa or Mastercard).
`payment_methods.card.phone` object	The customer's phone number.
`payment_methods.card.phone.country_code` string	The phone number's international country calling code. Min length: 1 Max length: 7
`payment_methods.card.phone.number` string	The phone number. Min length: 6 Max length: 25
`payment_methods.card.store_for_future_use` boolean	Set to `true` if you intend to reuse the payment credentials in subsequent payments. If set to `false`, a payment instrument will not be included in the payment response.
`payment_methods.card.preferred_scheme` string	The preferred card scheme for co-badged cards. Supported values: `visa` `mastercard` `cartes_bancaires`

payment_methods.card.token

object

A Checkout.com token representing the card. Required if payment_methods.card.details is not provided.

payment_methods.card.token.id

string

The token identifier, prefixed by tok_.

Required

payment_methods.card.account_holder.type

string

The card account holder type.

Supported values:

individual
corporate
government

Required

payment_methods.card.account_holder.first_name

string

The card account holder's first name.

Max length: 35
Required

payment_methods.card.account_holder.last_name

string

The card account holder's last name.

Max length: 35
Required

payment_methods.card.account_holder.middle_name

string

The card account holder's middle name.

Max length: 35

payment_methods.card.account_holder.account_name_inquiry

boolean

Indicates whether the ANI (account name inquiry) check is performed with the card scheme (Visa or Mastercard).

payment_methods.card.phone

object

The customer's phone number.

payment_methods.card.phone.country_code

string

The phone number's international country calling code.

Min length: 1
Max length: 7

payment_methods.card.phone.number

string

The phone number.

Min length: 6
Max length: 25

payment_methods.card.store_for_future_use

boolean

Set to true if you intend to reuse the payment credentials in subsequent payments. If set to false, a payment instrument will not be included in the payment response.

payment_methods.card.preferred_scheme

string

The preferred card scheme for co-badged cards.

Supported values:

visa
mastercard
cartes_bancaires


1{
2  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
3  "currency": "USD",
4  "amount": 2000,
5  "reference": "ORDER_01234",
6  "description": "Card payment",
7  "payment_type": "Regular",
8  "payment_methods": {
9    "card": {
10      "token": {
11        "id": "tok_4gzeau5lnbcubj3fjzaqpdbdrm"
12      },
13      "account_holder": {
14        "type": "individual",
15        "first_name": "Toby",
16        "last_name": "Arden"
17      }
18    }
19  }
20}


1{
2  "id": "set_rcmepwrchqab2wsergcafvijfy",
3  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
4  "amount": 2000,
5  "currency": "USD",
6  "payment_type": "Regular",
7  "reference": "ORDER_01234",
8  "description": "Card payment",
9  "payment_methods": {
10    "card": {
11      "status": "ready",
12      "flags": [],
13      "schemes": [
14        "visa",
15        "mastercard"
16      ]
17    }
18  },
19  "available_payment_methods": [
20    "card"
21  ],
22  "settings": {
23    "success_url": "https://example.com/payments/success",
24    "failure_url": "https://example.com/payments/failure"
25  }
26}

If your level of PCI compliance is SAQ D, you can request a payment using the card's full details.

When updating the payment setup, provide the following fields:

Field Description

Field	Description
`payment_methods.card.details` object	The card details. Required if `payment_methods.card.token` is not provided.
`payment_methods.card.details.number` string	The card number (without separators). Required
`payment_methods.card.details.expiry_month` integer	The expiry month of the card. Minimum: 1 Maximum: 12 Required
`payment_methods.card.details.expiry_year` integer	The expiry year of the card. Required
`payment_methods.card.details.cvv` string	The card verification value/code. 3 digits, except for American Express (4 digits). Min length: 3 Max length: 4
`payment_methods.card.details.name` string	The cardholder's name.
`payment_methods.card.details.stored` boolean	Set to `true` for payments that use stored card details.
`payment_methods.card.details.allow_update` boolean	Indicates whether to use the Real-Time Account Updater to update the card information.
`payment_methods.card.account_holder.type` string	The card account holder type. Supported values: `individual` `corporate` `government` Required
`payment_methods.card.account_holder.first_name` string	The card account holder's first name. Max length: 35 Required
`payment_methods.card.account_holder.last_name` string	The card account holder's last name. Max length: 35 Required
`payment_methods.card.account_holder.middle_name` string	The card account holder's middle name. Max length: 35
`payment_methods.card.account_holder.account_name_inquiry` boolean	Indicates whether the ANI (account name inquiry) check is performed with the card scheme (Visa or Mastercard).
`payment_methods.card.phone` object	The customer's phone number.
`payment_methods.card.phone.country_code` string	The phone number's international country calling code. Min length: 1 Max length: 7
`payment_methods.card.phone.number` string	The phone number. Min length: 6 Max length: 25
`payment_methods.card.store_for_future_use` boolean	Set to `true` if you intend to reuse the payment credentials in subsequent payments. If set to `false`, a payment instrument will not be included in the payment response.
`payment_methods.card.preferred_scheme` string	The preferred card scheme for co-badged cards. Supported values: `visa` `mastercard` `cartes_bancaires`

payment_methods.card.details

object

The card details. Required if payment_methods.card.token is not provided.

payment_methods.card.details.number

string

The card number (without separators).

Required

payment_methods.card.details.expiry_month

integer

The expiry month of the card.

Minimum: 1
Maximum: 12
Required

payment_methods.card.details.expiry_year

integer

The expiry year of the card.

Required

payment_methods.card.details.cvv

string

The card verification value/code. 3 digits, except for American Express (4 digits).

Min length: 3
Max length: 4

payment_methods.card.details.name

string

The cardholder's name.

payment_methods.card.details.stored

boolean

Set to true for payments that use stored card details.

payment_methods.card.details.allow_update

boolean

Indicates whether to use the Real-Time Account Updater to update the card information.

payment_methods.card.account_holder.type

string

The card account holder type.

Supported values:

individual
corporate
government

Required

payment_methods.card.account_holder.first_name

string

The card account holder's first name.

Max length: 35
Required

payment_methods.card.account_holder.last_name

string

The card account holder's last name.

Max length: 35
Required

payment_methods.card.account_holder.middle_name

string

The card account holder's middle name.

Max length: 35

payment_methods.card.account_holder.account_name_inquiry

boolean

Indicates whether the ANI (account name inquiry) check is performed with the card scheme (Visa or Mastercard).

payment_methods.card.phone

object

The customer's phone number.

payment_methods.card.phone.country_code

string

The phone number's international country calling code.

Min length: 1
Max length: 7

payment_methods.card.phone.number

string

The phone number.

Min length: 6
Max length: 25

payment_methods.card.store_for_future_use

boolean

Set to true if you intend to reuse the payment credentials in subsequent payments. If set to false, a payment instrument will not be included in the payment response.

payment_methods.card.preferred_scheme

string

The preferred card scheme for co-badged cards.

Supported values:

visa
mastercard
cartes_bancaires


1{
2  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
3  "currency": "USD",
4  "amount": 2000,
5  "reference": "ORDER_01234",
6  "description": "Card payment",
7  "payment_type": "Regular",
8  "payment_methods": {
9    "card": {
10      "details": {
11        "number": "4242424242424242",
12        "expiry_month": 6,
13        "expiry_year": 2028,
14        "cvv": "100",
15        "name": "Toby Arden"
16      },
17      "account_holder": {
18        "type": "individual",
19        "first_name": "Toby",
20        "last_name": "Arden"
21      }
22    }
23  }
24}


1{
2  "id": "set_rcmepwrchqab2wsergcafvijfy",
3  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
4  "amount": 2000,
5  "currency": "USD",
6  "payment_type": "Regular",
7  "reference": "ORDER_01234",
8  "description": "Card payment",
9  "payment_methods": {
10    "card": {
11      "status": "ready",
12      "flags": [],
13      "schemes": [
14        "visa",
15        "mastercard"
16      ]
17    }
18  },
19  "available_payment_methods": [
20    "card"
21  ],
22  "settings": {
23    "success_url": "https://example.com/payments/success",
24    "failure_url": "https://example.com/payments/failure"
25  }
26}

The response returns a ready status when the payment details pass validation. The payment is ready to confirm.

When the payment status changes to ready, confirm the payment by calling the Confirm a payment setup endpoint and provide:

The payment setup id as the {id} path parameter.
card as the payment method name.

post

https://{prefix}.api.checkout.com/payments/setups/{id}/confirm/card

A successful response returns a payment_id that you can use to track the payment.

Card payments for Payment Setup API

Create a payment setup

Information

Information

Request example

Response example

Update the payment setup

Request example

Response example

Request example

Response example

Confirm the payment