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": 12398914}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": true17},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}
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 havePending
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": true17},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": true49},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}
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 havePending
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": 20227},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": 12398916}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": true17},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}
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 havePending
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