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