Request a card payment
Once you've successfully set up your integration, you're able to start receiving and tokenizing your customers' card details. After this tokenization process, you're ready to create a payment. To do this, you can use our API and your server-side code.
How it works
Card tokens (tok_
) are single use and only have a 15-minute lifespan. Once you've successfully sent your request, you'll receive a response containing a permanent card source ID (src_
) which can be used in subsequent payment requests.
Request a card payment
The POST request
Use the details below to set up your request.
Endpoint
POSThttps://api.checkout.com/payments
POSThttps://api.sandbox.checkout.com/payments
Header parameters
Header | Value |
---|---|
REQUIRED |
Use the valid secret key of your Checkout.com account. You can find this in the Hub. |
REQUIRED | application/json |
Body parameters
The table below describes the minimum recommended fields. For the full API specification, see the API reference.
Field name | Description |
---|---|
OBJECT REQUIRED | Details about the payment source. |
STRING REQUIRED | The type of payment source. Set this to token . |
STRING REQUIRED | The Checkout.com token. This could be for a card, wallet, or alternative payment method. |
INTEGER OPTIONAL | The payment amount in your chosen currency. Omit the amount or provide a value of The format depends on the currency. For more information, see calculating the value. |
STRING REQUIRED | A three-letter ISO currency code representing the currency of the payment. |
STRING OPTIONAL | An optional reference you can use to identify the payment later. For example, an order number. If using Bambora as a third-party acquirer, this field is numeric only and limited to 12 characters maximum. |
OBJECT OPTIONAL | Allows you to store additional information about a transaction (e.g., a coupon code) with custom fields and up to five user-defined fields (
|
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.
Request example
{
"source": {
"type": "token",
"token": "tok_4gzeau5o2uqubbk6fufs3m7p54"
},
"amount": 6500,
"currency": "USD",
"reference": "ORD-5023-4E89",
"metadata": {
"udf1": "TEST123",
"coupon_code": "NY2018",
"partner_id": 123989
}
}
The POST response
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.
The following pages can help you understand the response message:
- CVV codes and descriptions
- AVS codes
- Response codes (if the authorization was unsuccessful)
Response example
The possible values for the status
field include Authorized
, Captured
, Card Verified
, Declined
, and Pending
. Note that Pending
only applies to 3D Secure payments and alternative payments.
{
"id": "pay_mbabizu24mvu3mela5njyhpit4",
"action_id": "act_mbabizu24mvu3mela5njyhpit4",
"amount": 6500,
"currency": "USD",
"approved": true,
"status": "Authorized",
"auth_code": "770687",
"eci": "05",
"scheme_id": "638284745624527",
"response_code": "10000",
"response_summary": "Approved",
"risk": {
"flagged": false
},
"source": {
"id": "src_nwd3m4in3hkuddfpjsaevunhdy",
"type": "card",
"expiry_month": 9,
"expiry_year": 2022,
"scheme": "Visa",
"last4": "4242",
"fingerprint": "F31828E2BDABAE63EB694903825CDD36041CC6ED461440B81415895855502832",
"bin": "424242",
"card_type": "Credit",
"card_category": "Consumer",
"issuer": "JPMORGAN CHASE BANK NA",
"issuer_country": "US",
"product_id": "A",
"product_type": "Visa Traditional",
"avs_check": "S",
"cvv_check": ""
},
"customer": {
"id": "cus_udst2tfldj6upmye2reztkmm4i"
},
"processed_on": "2019-01-25T11:03:36Z",
"reference": "ORD-5023-4E89",
"_links": {
"self": {
"href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4"
},
"actions": {
"href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/actions"
},
"capture": {
"href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/captures"
},
"void": {
"href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/voids"
}
}
}
{
"id": "pay_y3oqhf46pyzuxjbcn2giaqnb44",
"status": "Pending",
"reference": "ORD-5023-4E89",
"customer": {
"id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
"email": "sarah.mitchell@checkout.com",
"name": "Sarah Mitchell"
},
"3ds": {
"downgraded": false,
"enrolled": "Y"
},
"_links": {
"self": {
"href": "https://api.checkout.com/payments/pay_y3oqhf46pyzuxjbcn2giaqnb44"
},
"redirect": {
"href": "https://api.checkout.com/3ds/pay_y3oqhf46pyzuxjbcn2giaqnb44"
}
}
}
{
"request_id": "0HL80RJLS76I7",
"error_type": "request_invalid",
"error_codes": [
"payment_source_required"
]
}
Possibly fraudulent authorization requests return the message risk.flagged: true
to show that the payment has been flagged.
Next step
Once you've successfully processed a card payment request, you're able to easily reuse those card details for subsequent payments.
Can we help?
Thanks for using Checkout.com. If you need help or have a question, message our Support team at support@checkout.com.