Accept a payment using the API

Last updated: August 14, 2024

You can use the 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

Information

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

To reduce the likelihood of encountering a decline due to an unsupported payment method, you can 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.

get

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

To return the payment methods available for a specific processing channel, pass the processing_channel_id as a query parameter. For example:


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


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.

If you've integrated with our Flow or Frames front-end solutions, you'll receive a token when the customer submits their payment details on the checkout page.

If you request a payment request with the token, you ensure that the sensitive payment details do not reach your server.

post

https://api.checkout.com/payments

For the full API specification, see the API reference.

You can also 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.

Information

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


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": "NY2018",
13    "partner_id": 123989
14  }
15}

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.

For 3DS payments that require a redirect, status may return Pending while additional authentication is performed.

Information

See the CVV codes, AVS codes, and API response codes documentation to help you understand the response.

The possible values for the status field are:

Authorized
Pending (3DS payments only)
Card Verified
Declined

If the status value is Declined, the authorization failed. The card used for the payment request may be invalid, expired, or have insufficient funds for the transaction.

To receive asynchronous status updates, you can use the

get

/get-payment-details endpoint, or set up a workflow.


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": "2019-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": "2020-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}

A network token is a secure representation of a card's Primary Account Number (PAN), provided by card networks.

post

https://api.checkout.com/payments

For the full API specification, see the API reference.

Information

The customer's IP address is used by Fraud Detection for the transaction risk assessment and to make the payment. Both IPv4 and IPv6 addresses are supported.


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}

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

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

If authorization failed, the payment may have been requested with an invalid or expired card, or a valid card with insufficient funds.

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

For 3DS payments that require a redirect, status may return Pending while additional authentication is performed.

Information

See the CVV codes, AVS codes, and API response codes documentation to help you understand the response.

The possible values for the status field are:

Authorized
Pending (3DS payments only)
Card Verified
Captured
Declined
Paid


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": "2019-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": "2020-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}

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

post

https://api.checkout.com/payments

For the full API specification, see the API reference.


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 full card details.

Information

To enable full card processing on your account, contact your Solution Engineer or [email protected].

post

https://api.checkout.com/payments

For the full API specification, see the API reference.

Information

The customer's IP address is used by Fraud Detection for the transaction risk assessment and to make the payment. Both IPv4 and IPv6 addresses are supported.


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": "NY2018",
15    "partner_id": 123989
16  }
17}

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

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

If authorization failed, the payment may have been requested with an invalid or expired card, or a valid card with insufficient funds.

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

For 3DS payments that require a redirect, status may return Pending while additional authentication is performed.

Information

See the CVV codes, AVS codes, and API response codes documentation to help you understand the response.

The possible values for the status field are:

Authorized
Pending (3DS payments only)
Card Verified
Captured
Declined
Paid


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": "2019-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": "2020-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}

Accept a payment using the API

Information

Get a list of available payment methods
Beta

Response example

Request a payment with a token

Information

Request example

Information

Response example

Request a payment with a network token

Information

Request example

Information

Response example

Request a payment with a payment instrument

Request example

Response example

Request a payment with full card details

Information

Information

Request example

Information

Response example

Information

Get a list of available payment methods Beta

Response example

Request a payment with a token

Information

Request example

Information

Response example

Request a payment with a network token

Information

Request example

Information

Response example

Request a payment with a payment instrument

Request example

Response example

Request a payment with full card details

Information

Information

Request example

Information

Response example

Get a list of available payment methods
Beta