Accept a payment using the Payments API

Last updated: October 15, 2025

You can use the Unified Payments API to request a payment with:

A token
A network token
A payment instrument
The full card details, if your level of PCI compliance is SAQ D

The Unified Payments API supports idempotency. You can safely retry API requests without the risk of duplicate requests.

You can provide additional payment and authentication data to improve the data quality of your payment request. This can help issuers to identify fraudulent transactions and reduce false declines.

The Fraud Detection solution uses the customer's IP address to assess the payment's risk. The payment_ip field supports IPv4 and IPv6 addresses.

For more information about payment request responses, see:

To receive asynchronous status updates, you can call the Get payment details endpoint, or set up a webhooks workflow.

To reduce the likelihood of declines due to unsupported payment methods, check which payment methods are configured on your account before you request a payment.

You can use the values returned to ensure that you do not display unsupported payment methods to the customer at checkout.

Call the Get available payment methods endpoint, and provide the processing_channel_id as a query parameter. For example:


1https://api.checkout.com/payment-methods?processing_channel_id=pc_ovo75iz4hdyudnx6tu74mum3fq

get

https://api.checkout.com/payment-methods


1{
2  "methods": [
3    {
4      "type": "visa"
5    },
6    {
7      "type": "mastercard"
8    },
9    {
10      "type": "paypal",
11      "partner_merchant_id": "XUDKCFT2RGRAC"
12    },
13    {
14      "type": "applepay"
15    }
16  ]
17}

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.

You can tokenize credentials with Flow to receive a token when the customer submits their payment details on your checkout page.

Call the Request a payment or payout endpoint and set the source.type field to token.

post

https://api.checkout.com/payments


1{
2  "source": {
3    "type": "token",
4    "token": "tok_4gzeau5o2uqubbk6fufs3m7p54"
5  },
6  "amount": 6500,
7  "currency": "USD",
8  "processing_channel_id": "pc_ovo75iz4hdyudnx6tu74mum3fq",
9  "reference": "ORD-5023-4E89",
10  "metadata": {
11    "udf1": "TEST123",
12    "coupon_code": "NY2024",
13    "partner_id": 123989
14  }
15}


1{
2  "id": "pay_mbabizu24mvu3mela5njyhpit4",
3  "action_id": "act_mbabizu24mvu3mela5njyhpit4",
4  "amount": 6540,
5  "currency": "USD",
6  "approved": true,
7  "status": "Authorized",
8  "auth_code": "770687",
9  "response_code": "10000",
10  "response_summary": "Approved",
11  "3ds": {
12    "downgraded": true,
13    "enrolled": "N"
14  },
15  "risk": {
16    "flagged": true
17  },
18  "source": {
19    "type": "card",
20    "id": "src_nwd3m4in3hkuddfpjsaevunhdy",
21    "billing_address": {
22      "address_line1": "123 Anywhere St.",
23      "address_line2": "Apt. 456",
24      "city": "Anytown",
25      "state": "AL",
26      "zip": "123456",
27      "country": "US"
28    },
29    "phone": {
30      "country_code": "+1",
31      "number": "555 123 4567"
32    },
33    "last4": "4242",
34    "fingerprint": "F31828E2BDABAE63EB694903825CDD36041CC6ED461440B81415895855502832",
35    "bin": "424242"
36  },
37  "customer": {
38    "id": "cus_udst2tfldj6upmye2reztkmm4i",
39    "email": "[email protected]",
40    "name": "Ali Farid"
41  },
42  "processed_on": "2024-09-10T10:11:12Z",
43  "reference": "ORD-5023-4E89",
44  "processing": {
45    "retrieval_reference_number": "909913440644",
46    "acquirer_transaction_id": "440644309099499894406"
47  },
48  "eci": "06",
49  "scheme_id": "489341065491658",
50  "links": {
51    "self": {
52      "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4"
53    },
54    "action": {
55      "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/actions"
56    },
57    "void": {
58      "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/voids"
59    },
60    "capture": {
61      "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/captures"
62    }
63  }
64}


1{
2  "id": "pay_mbabizu24mvu3mela5njyhpit4",
3  "status": "Pending",
4  "reference": "ORD-5023-4E89",
5  "customer": {
6    "id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
7    "email": "[email protected]",
8    "name": "Ali Farid"
9  },
10  "3ds": {
11    "downgraded": false,
12    "enrolled": "Y"
13  },
14  "instruction": {
15    "value_date": "2024-08-25"
16  },
17  "_links": {
18    "self": {
19      "href": "https://api.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4"
20    },
21    "redirect": {
22      "href": "https://api.checkout.com/3ds/pay_mbabizu24mvu3mela5njyhpit4"
23    }
24  }
25}


1{
2  "request_id": "0HL80RJLS76I7",
3  "error_type": "request_invalid",
4  "error_codes": ["payment_source_required"]
5}

If you receive a 201 response with the following values, the authorization was successful:

"approved": true
"status": "Authorized"

If you receive a 202 response, the payment requires a redirect. For example, if the payment was performed with 3D Secure (3DS) authentication.

The possible values for the status field are:

Authorized
Pending – 3DS payments that require a redirect can have Pending status while additional authentication is performed.
Card Verified
Declined – The authorization failed. The card used for the payment request may be invalid, expired, or have insufficient funds.

A network token is a secure representation of a card's primary account number (PAN), provided by card networks.

Call the Request a payment or payout endpoint and set the source.type field to network_token.

post

https://api.checkout.com/payments


1{
2  "source": {
3    "type": "network_token",
4    "token": "4242424242424242",
5    "token_type": "vts",
6    "expiry_month": "10",
7    "expiry_year": "2025",
8    "eci": "06",
9    "cryptogram": "AgAAAAAAAIR8CQrXcIhbQAAAAAA="
10  },
11  "amount": 1000,
12  "currency": "USD",
13  "pan_preference": "dpan"
14}


1{
2  "id": "pay_mbabizu24mvu3mela5njyhpit4",
3  "action_id": "act_mbabizu24mvu3mela5njyhpit4",
4  "amount": 6540,
5  "currency": "USD",
6  "approved": true,
7  "status": "Authorized",
8  "auth_code": "770687",
9  "response_code": "10000",
10  "response_summary": "Approved",
11  "3ds": {
12    "downgraded": true,
13    "enrolled": "N"
14  },
15  "risk": {
16    "flagged": true
17  },
18  "source": {
19    "type": "card",
20    "id": "src_nwd3m4in3hkuddfpjsaevunhdy",
21    "billing_address": {
22      "address_line1": "123 Anywhere St.",
23      "address_line2": "Apt. 456",
24      "city": "Anytown",
25      "state": "AL",
26      "zip": "123456",
27      "country": "US"
28    },
29    "phone": {
30      "country_code": "+1",
31      "number": "555 123 4567"
32    },
33    "last4": "4242",
34    "fingerprint": "F31828E2BDABAE63EB694903825CDD36041CC6ED461440B81415895855502832",
35    "bin": "424242"
36  },
37  "customer": {
38    "id": "cus_udst2tfldj6upmye2reztkmm4i",
39    "email": "[email protected]",
40    "name": "Ali Farid"
41  },
42  "processed_on": "2024-09-10T10:11:12Z",
43  "reference": "ORD-5023-4E89",
44  "processing": {
45    "retrieval_reference_number": "909913440644",
46    "acquirer_transaction_id": "440644309099499894406",
47    "pan_type_processed": "dpan",
48    "cko_network_token_available": true
49  },
50  "eci": "06",
51  "scheme_id": "489341065491658",
52  "links": {
53    "self": {
54      "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4"
55    },
56    "action": {
57      "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/actions"
58    },
59    "void": {
60      "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/voids"
61    },
62    "capture": {
63      "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/captures"
64    }
65  }
66}


1{
2  "id": "pay_mbabizu24mvu3mela5njyhpit4",
3  "status": "Pending",
4  "reference": "ORD-5023-4E89",
5  "customer": {
6    "id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
7    "email": "[email protected]",
8    "name": "Ali Farid"
9  },
10  "3ds": {
11    "downgraded": false,
12    "enrolled": "Y"
13  },
14  "instruction": {
15    "value_date": "2024-08-25"
16  },
17  "_links": {
18    "self": {
19      "href": "https://api.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4"
20    },
21    "redirect": {
22      "href": "https://api.checkout.com/3ds/pay_mbabizu24mvu3mela5njyhpit4"
23    }
24  }
25}


1{
2  "request_id": "0HL80RJLS76I7",
3  "error_type": "request_invalid",
4  "error_codes": ["payment_source_required"]
5}

If you receive a 201 response with the following values, the authorization was successful:

"approved": true
"status": "Authorized"

If you receive a 202 response, the payment requires a redirect. For example, if the payment was performed with 3DS authentication.

The possible values for the status field are:

Authorized
Pending – 3DS payments that require a redirect can have Pending status while additional authentication is performed.
Card Verified
Captured
Declined – The authorization failed. The card used for the payment request may be invalid, expired, or have insufficient funds.
Paid

A payment instrument is a secure representation of a customer's card or bank account that you have stored with Checkout.com for reuse.

Call the Request a payment or payout endpoint and set the source.type field to id.

post

https://api.checkout.com/payments


1{
2  "source": {
3    "type": "id",
4    "id": "src_wmlfc3zyhqzehihu7giusaaawu"
5  },
6  "amount": 6500,
7  "currency": "USD",
8  "reference": "ORD-5023-4E89"
9}


1{
2  "id": "pay_mbabizu24mvu3mela5njyhpit4",
3  "amount": 6500,
4  "currency": "USD",
5  "approved": true,
6  "status": "Authorized",
7  "auth_code": "770687",
8  "response_code": "10000",
9  "response_summary": "Approved",
10  "source": {
11    "type": "id",
12    "id": "src_wmlfc3zyhqzehihu7giusaaawu"
13  }
14}

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

Information

To enable full card processing on your account, contact your solution engineer or request support.

Call the Request a payment or payout endpoint and set the source.type field to card.

post

https://api.checkout.com/payments


1{
2  "source": {
3    "type": "card",
4    "number": "4242424242424242",
5    "expiry_month": 12,
6    "expiry_year": 2022
7  },
8  "amount": 6500,
9  "currency": "USD",
10  "processing_channel_id": "processing_channel_id",
11  "reference": "ORD-5023-4E89",
12  "metadata": {
13    "udf1": "TEST123",
14    "coupon_code": "NY2024",
15    "partner_id": 123989
16  }
17}


1{
2  "id": "pay_mbabizu24mvu3mela5njyhpit4",
3  "action_id": "act_mbabizu24mvu3mela5njyhpit4",
4  "amount": 6540,
5  "currency": "USD",
6  "approved": true,
7  "status": "Authorized",
8  "auth_code": "770687",
9  "response_code": "10000",
10  "response_summary": "Approved",
11  "3ds": {
12    "downgraded": true,
13    "enrolled": "N"
14  },
15  "risk": {
16    "flagged": true
17  },
18  "source": {
19    "type": "card",
20    "id": "src_nwd3m4in3hkuddfpjsaevunhdy",
21    "billing_address": {
22      "address_line1": "123 Anywhere St.",
23      "address_line2": "Apt. 456",
24      "city": "Anytown",
25      "state": "AL",
26      "zip": "123456",
27      "country": "US"
28    },
29    "phone": {
30      "country_code": "+1",
31      "number": "555 123 4567"
32    },
33    "last4": "4242",
34    "fingerprint": "F31828E2BDABAE63EB694903825CDD36041CC6ED461440B81415895855502832",
35    "bin": "424242"
36  },
37  "customer": {
38    "id": "cus_udst2tfldj6upmye2reztkmm4i",
39    "email": "[email protected]",
40    "name": "Ali Farid"
41  },
42  "processed_on": "2024-09-10T10:11:12Z",
43  "reference": "ORD-5023-4E89",
44  "processing": {
45    "retrieval_reference_number": "909913440644",
46    "acquirer_transaction_id": "440644309099499894406"
47  },
48  "eci": "06",
49  "scheme_id": "489341065491658",
50  "links": {
51    "self": {
52      "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4"
53    },
54    "action": {
55      "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/actions"
56    },
57    "void": {
58      "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/voids"
59    },
60    "capture": {
61      "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/captures"
62    }
63  }
64}


1{
2  "id": "pay_mbabizu24mvu3mela5njyhpit4",
3  "status": "Pending",
4  "reference": "ORD-5023-4E89",
5  "customer": {
6    "id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
7    "email": "[email protected]",
8    "name": "Ali Farid"
9  },
10  "3ds": {
11    "downgraded": false,
12    "enrolled": "Y"
13  },
14  "instruction": {
15    "value_date": "2024-08-25"
16  },
17  "_links": {
18    "self": {
19      "href": "https://api.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4"
20    },
21    "redirect": {
22      "href": "https://api.checkout.com/3ds/pay_mbabizu24mvu3mela5njyhpit4"
23    }
24  }
25}


1{
2  "request_id": "0HL80RJLS76I7",
3  "error_type": "request_invalid",
4  "error_codes": ["payment_source_required"]
5}

If you receive a 201 response with the following values, the authorization was successful:

"approved": true
"status": "Authorized"

If you receive a 202 response, the payment requires a redirect. For example, if the payment was performed with 3DS authentication.

The possible values for the status field are:

Authorized
Pending – 3DS payments that require a redirect can have Pending status while additional authentication is performed.
Card Verified
Captured
Declined – The authorization failed. The card used for the payment request may be invalid, expired, or have insufficient funds.
Paid

Accept a payment using the Payments API

Idempotency

Data quality

Risk assessment

API responses

Webhooks

Get a list of available payment methods
Beta

Response example

Request a payment with a token

Request example

Response example

Request a payment with a network token

Request example

Response example

Request a payment with a payment instrument

Request example

Response example

Request a payment with full card details

Information

Request example

Response example

Idempotency

Data quality

Risk assessment

API responses

Webhooks

Get a list of available payment methods Beta

Response example

Request a payment with a token

Request example

Response example

Request a payment with a network token

Request example

Response example

Request a payment with a payment instrument

Request example

Response example

Request a payment with full card details

Information

Request example

Response example

Get a list of available payment methods
Beta