Request a card payment

Last updated: April 29, 2022

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.

Information

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.

For the full API specification, see the API reference.

post

https://api.checkout.com/payments


1{
2  "source": {
3    "type": "token",
4    "token": "tok_4gzeau5o2uqubbk6fufs3m7p54"
5  },
6  "amount": 6500,
7  "currency": "USD",
8  "reference": "ORD-5023-4E89",
9  "metadata": {
10    "udf1": "TEST123",
11    "coupon_code": "NY2018",
12    "partner_id": 123989
13  }
14}

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.

Information

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, Captured, Card Verified, Declined, and Pending. Note that Pending only applies to 3D Secure payments and alternative payments.


1{
2  "id": "pay_mbabizu24mvu3mela5njyhpit4",
3  "action_id": "act_mbabizu24mvu3mela5njyhpit4",
4  "amount": 6500,
5  "currency": "USD",
6  "approved": true,
7  "status": "Authorized",
8  "auth_code": "770687",
9  "eci": "05",
10  "scheme_id": "638284745624527",
11  "response_code": "10000",
12  "response_summary": "Approved",
13  "risk": {
14    "flagged": false
15  },
16  "source": {
17    "id": "src_nwd3m4in3hkuddfpjsaevunhdy",
18    "type": "card",
19    "expiry_month": 9,
20    "expiry_year": 2022,
21    "scheme": "Visa",
22    "last4": "4242",
23    "fingerprint": "F31828E2BDABAE63EB694903825CDD36041CC6ED461440B81415895855502832",
24    "bin": "424242",
25    "card_type": "Credit",
26    "card_category": "Consumer",
27    "issuer": "JPMORGAN CHASE BANK NA",
28    "issuer_country": "US",
29    "product_id": "A",
30    "product_type": "Visa Traditional",
31    "avs_check": "S",
32    "cvv_check": ""
33  },
34  "customer": {
35    "id": "cus_udst2tfldj6upmye2reztkmm4i"
36  },
37  "processed_on": "2019-01-25T11:03:36Z",
38  "reference": "ORD-5023-4E89",
39  "_links": {
40    "self": {
41      "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4"
42    },
43    "actions": {
44      "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/actions"
45    },
46    "capture": {
47      "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/captures"
48    },
49    "void": {
50      "href": "https://api.sandbox.checkout.com/payments/pay_mbabizu24mvu3mela5njyhpit4/voids"
51    }
52  }
53}


1{
2  "id": "pay_y3oqhf46pyzuxjbcn2giaqnb44",
3  "status": "Pending",
4  "reference": "ORD-5023-4E89",
5  "customer": {
6    "id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
7    "email": "[email protected]",
8    "name": "Sarah Mitchell"
9  },
10  "3ds": {
11    "downgraded": false,
12    "enrolled": "Y"
13  },
14  "_links": {
15    "self": {
16      "href": "https://api.checkout.com/payments/pay_y3oqhf46pyzuxjbcn2giaqnb44"
17    },
18    "redirect": {
19      "href": "https://api.checkout.com/3ds/pay_y3oqhf46pyzuxjbcn2giaqnb44"
20    }
21  }
22}


1{
2  "request_id": "0HL80RJLS76I7",
3  "error_type": "request_invalid",
4  "error_codes": ["payment_source_required"]
5}

Information

Possibly fraudulent authorization requests return the message risk.flagged: true to show that the payment has been flagged.

Once you've successfully processed a card payment request, you're able to easily reuse those card details for subsequent payments.

Request a card payment

How it works

Information