Guides
API Reference

Our reference library for integrating with our API

FAQ

Find answers to our most frequently asked questions

Classic Docs

Documentation for our Classic API

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

Endpoints

For the full API specification, see the API reference.

https://api.checkout.com/payments
https://api.sandbox.checkout.com/payments

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
  }
}

Response example

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:

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.