Checkout.com API logo

Tokens

Create a token that represents a card's credentials that you can later use to request a payment, without you having to process or store any sensitive information.

Request a token

Exchange card details for a reference token that can be used later to request a card payment. Tokens are single use and expire after 15 minutes. To create a token, please authenticate using your public key.

Please note: You should only use the card type for testing purposes.

SecurityAPI Key: ApiPublicKey
Request
Request Body schema: application/json
type
required
string

The type of card details to be tokenized

number
required
string

The card number

expiry_month
required
integer [ 1 .. 2 ] characters >= 1

The expiry month of the card

expiry_year
required
integer = 4 characters

The expiry year of the card

name
string

The cardholder's name

cvv
string [ 3 .. 4 ] characters

The card verification value/code. 3 digits, except for American Express (4 digits)

pin
string = 2 characters

The first 2 digits of the card PIN

object

The payment source owner's billing address

object

The payment source owner's phone number

Responses
201

Reference token created successfully

401

Unauthorized

422

Invalid data was sent

504

Gateway timeout

post/tokens
Request samples
application/json
{
  • "type": "card",
  • "number": "4543474002249996",
  • "expiry_month": 6,
  • "expiry_year": 2025,
  • "name": "Bruce Wayne",
  • "cvv": "956",
  • "pin": "12",
  • "billing_address": {
    },
  • "phone": {
    }
}
Response samples
application/json
{
  • "type": "card",
  • "token": "tok_ubfj2q76miwundwlk72vxt2i7q",
  • "expires_on": "2019-08-24T14:15:22Z",
  • "billing_address": {
    },
  • "phone": {
    },
  • "expiry_month": 6,
  • "expiry_year": 2025,
  • "name": "Bruce Wayne",
  • "scheme": "VISA",
  • "scheme_local": "cartes_bancaires",
  • "last4": "9996",
  • "bin": "454347",
  • "card_type": "CREDIT",
  • "card_category": "CONSUMER",
  • "issuer": "GOTHAM STATE BANK",
  • "issuer_country": "US",
  • "product_id": "F",
  • "product_type": "CLASSIC"
}

Get token metadata

Returns the details for an active token without consuming it. The token remains usable after this call.

Possible responses:

  • 200 – Active and recently-used tokens (still within the 15-minute window).
  • 410 – Expired tokens.
  • 404 – Not found tokens, or of an unsupported type (for example, cvv or pin).
SecurityAPI Key: ApiSecretKey or OAuth2: OAuth
Request
path Parameters
tokenId
required
string^(tok)_(\w{26})$

The token ID

Example: tok_4gzeau5o2uqubbk6fudbloo47a
Responses
200

Token metadata retrieved successfully

401

Unauthorized

403

Forbidden

404

Token not found, or token type does not support metadata retrieval

410

Token has expired

422

Invalid data was sent

504

Gateway timeout

get/tokens/{tokenId}/metadata
Request samples 
Response samples 
application/json
{
  • "token": "tok_4gzeau5o2uqubbk6fudbloo47a",
  • "type": "card",
  • "expires_on": "2026-05-14T10:11:12Z",
  • "expiry_month": 12,
  • "expiry_year": 2030,
  • "scheme": "Visa",
  • "last4": "4242",
  • "bin": "424242",
  • "card_type": "CREDIT",
  • "card_category": "CONSUMER",
  • "issuer": "JPMORGAN CHASE BANK NA",
  • "issuer_country": "US",
  • "product_id": "A",
  • "product_type": "Visa Traditional",
  • "billing_address": {
    }
}
➔ Next to Instruments