SupportAPI referenceClassic API docs
Guides
Start typing to search…

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.

1234

Click to enlarge.

📘

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.

The request

Use the details below to set up your request.

Endpoints

Live

POSThttps://api.checkout.com/payments

Sandbox

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

Header parameters

Header

Value

Authorization Required

secret key

Use the valid secret key of your Checkout.com account. You can find this in the Hub.

Content-Type\ 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

sourceObjectrequired

Details about the payment source.

source.type\ String\ required

The type of payment source. Set this to token.

source.token\ String\ required

The Checkout.com token. This could be for a card, wallet or alternative payment method.

amount\ integer\ optional

The payment amount in your chosen currency. Omit the amount or provide a value of 0 to perform a card verification.\ The format depends on the currency. For more information, see calculating the value.

currency\ String\ required

A three-letter ISO currency code representing the currency of the payment.

reference\ 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.

metadata\ 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 (udf1 to udf5), which can be used for reporting purposes.\ udf1 is also used for some of our risk rules.

📘

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

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": "[email protected]",
    "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 any help or support, then message our support team at [email protected].

Updated 5 months ago