Accept a payment using the API

Last updated: April 29, 2022

There are four possible ways for you to request a payment:

using a token
using a network token
using full card details(requires SAQ D PCI compliance)
using a payment instrument

Use the details below to set up your request.

For the full API specification, see the API reference.

post

https://api.checkout.com/payments

IPv4 or IPv6 addresses?

The optional payment_ip field, which is used by our risk engine to check the customer's IP address, only accepts IPv4 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}

Use the approved field to check whether or not the authorization was successful ("approved": true). If your authorization was not successful, it's possible the payment used an invalid/expired card, or a valid card with an insufficient available balance.

If you received a 202 response, the payment requires a redirect. For example, if the payment is 3D Secure.

Tip

The following pages can help you understand the response message:

CVV codes and descriptions
AVS codes
Response codes (if the authorization was unsuccessful)

The possible values for the status field in the synchronous 201 response are Authorized, Pending, Card Verified, or Declined. Note that Pending only applies to 3D Secure payments. You can use Workflows or the Get payment details endpoint for asynchronous status updates.


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": "john.smith@example.com",
40    "name": "John Smith"
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": "john.smith@example.com",
8    "name": "John Smith"
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}

Use the details below to set up your request.

For the full API specification, see the API reference.

post

https://api.checkout.com/payments

IPv4 or IPv6 addresses?

The optional payment_ip field, which is used by our risk engine to check the customer's IP address, only accepts IPv4 addresses.


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}

If you received a 202 response, the payment requires a redirect. For example, if the payment is 3D Secure.

Tip

The following pages can help you understand the response message:

CVV codes and descriptions
AVS codes
Response codes (if the authorization was unsuccessful)

The possible values for the status field include Authorized, Pending, Card Verified, Captured, Declined, or Paid. Note that Pending only applies to 3D Secure payments.


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": "john.smith@example.com",
40    "name": "John Smith"
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": "john.smith@example.com",
8    "name": "John Smith"
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}

If you are SAQ D PCI compliant, you can use our Full Card API to request a payment using the full card details. To enable full card processing on your account, contact your Solution Engineer or support@checkout.com.

Use the details below to set up your request.

For the full API specification, see the API reference.

post

https://api.checkout.com/payments

IPv4 or IPv6 addresses?

The optional payment_ip field, which is used by our risk engine to check the customer's IP address, only accepts IPv4 addresses.


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 received a 202 response, the payment requires a redirect. For example, if the payment is 3D Secure.

Tip

The following pages can help you understand the response message:

CVV codes and descriptions
AVS codes
Response codes (if the authorization was unsuccessful)

The possible values for the status field include Authorized, Pending, Card Verified, Captured, Declined, or Paid. Note that Pending only applies to 3D Secure payments.


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": "john.smith@example.com",
40    "name": "John Smith"
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": "john.smith@example.com",
8    "name": "John Smith"
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}

You can use a payment instrument to request a payment.


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}

We've made some changes to our API

Accept a payment using the API

Using a token

Endpoints

IPv4 or IPv6 addresses?

Request example

Response example

Tip

Using a network token

Endpoints

IPv4 or IPv6 addresses?

Request example

Response example

Tip

Using full card details

Endpoints

IPv4 or IPv6 addresses?

Request example

Response example

Tip

Using a payment instrument

Request example

Response example