Network tokens

You can use Visa or Mastercard network tokens to make payments through the unified payments endpoint.

The request

Use the details below to set up your request.

Endpoints

Live

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

Sandbox

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

Field name
Description

token
String
required

The network token PAN.

expiry_month
String
required

The two-digit expiry month of the token.

expiry_year
String
required

The four-digit expiry year of the token.

token_type
String
required

The type of token. Set this to vts for Visa or mdes for Mastercard.

eci
String
required

The Electronic Commerce Indicator security level associated with the token.
Optional if previous_payment_id is specified and 3ds.enabled is false.

For more information, see Stored card details.

cryptogram
String
required

Cryptographic identifier used by card schemes to validate the token verification result.
Optional if previous_payment_id is specified and 3ds.enabled is false.

For more information, see Stored card details.

Request example

This code snippet is an example of the request body.

{
  "source": {
    "type": "network_token",
    "token": "4242424242424242",
    "token_type": "vts",
    "expiry_month": "10",
    "expiry_year": "2025",
    "eci": "06",
    "cryptogram": "AgAAAAAAAIR8CQrXcIhbQAAAAAA"
  },
  "amount": 1000,
  "currency": "USD"
}

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.

A successful response will include a payment_account_reference value, which is a unique reference to the underlying card for network tokens. If the card scheme provided us with an eci value, it will be included in the response. The value indicates the security level with which the card scheme decided to authorize the payment.

Response example

{
  "id": "pay_k7yuyhvad5vujdl7zcb6de2qmm",
  "action_id": "act_k7yuyhvad5vujdl7zcb6de2qmm",
  "amount": 100,
  "currency": "GBP",
  "approved": true,
  "status": "Authorized",
  "auth_code": "000205",
  "eci": "05",
  "scheme_id": "17896",
  "response_code": "10000",
  "response_summary": "Approved",
  "risk": {
    "flagged": false
  },
  "source": {
    "id": "src_6h3fksgf7n4evi2cgv2vdekgua",
    "type": "card",
    "expiry_month": 6,
    "expiry_year": 2025,
    "scheme": "Visa",
    "last4": "4242",
    "fingerprint": "9F3BAD2E48C6C8579F2F5DC0710B7C11A8ACD5072C3363A72579A6FB227D64BE",
    "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": "UM",
    "cvv_check": "Y",
    "payment_account_reference": "2FCFE326D92D4C27EDD699560F484"
  },
  "customer": {
    "id": "cus_6wa6milnaqnutl3sysyjxwd4wq"
  },
  "processed_on": "2019-07-31T08:25:12Z",
  "processing": {
    "acquirer_transaction_id": "621237178574778015081",
    "retrieval_reference_number": "527881243825"
  },
  "_links": {
    "self": {
      "href": "https://qa.ckotech.co/gateway/payments/pay_k7yuyhvad5vujdl7zcb6de2qmm"
    },
    "actions": {
      "href": "https://qa.ckotech.co/gateway/payments/pay_k7yuyhvad5vujdl7zcb6de2qmm/actions"
    },
    "capture": {
      "href": "https://qa.ckotech.co/gateway/payments/pay_k7yuyhvad5vujdl7zcb6de2qmm/captures"
    },
    "void": {
      "href": "https://qa.ckotech.co/gateway/payments/pay_k7yuyhvad5vujdl7zcb6de2qmm/voids"
    }
  }

Can we help?

Thanks for using Checkout.com. If you need any help or support, then message our support team at support@checkout.com.

Network tokens


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.