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.

Tokens Operations

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.

Body·
application/json

  • The source of the payment

    Card Token Request

    • type
      Discriminator
      enum
      const:  
      card
      required

      The type of card details to be tokenized

      values
      • card
    • number
      Type: string
      required

      The card number

    • expiry_month
      Type: integer
      min:  
      1
      required

      The expiry month of the card

    • expiry_year
      Type: integer
      required

      The expiry year of the card

    • name
      Type: string

      The cardholder's name

    • cvv
      Type: string
      min length:  
      3
      max length:  
      4

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

    • pin
      Type: string
      min length:  
      2
      max length:  
      2

      The first 2 digits of the card PIN

    • billing_address
      Type: object ·

      The payment source owner's billing address

    • phone
      Type: object ·

      The payment source owner's phone number

Responses
  • application/json
  • 401

    Unauthorized

  • application/json
  • 504

    Gateway timeout

Request Example for post/tokens
curl 'https://{prefix}.api.sandbox.checkout.com/tokens' \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: YOUR_SECRET_TOKEN' \
  --data '{
  "type": "card",
  "number": "4543474002249996",
  "expiry_month": 6,
  "expiry_year": 2025,
  "name": "Bruce Wayne",
  "cvv": "956",
  "pin": "12",
  "billing_address": {
    "address_line1": "123 High St.",
    "address_line2": "Flat 456",
    "city": "London",
    "state": "",
    "zip": "SW1A 1AA",
    "country": "GB"
  },
  "phone": {
    "country_code": "+1",
    "number": "415 555 2671"
  }
}'

{
  "type": "card",
  "token": "tok_ubfj2q76miwundwlk72vxt2i7q",
  "expires_on": "2023-07-11T15:57:32.435+00:00",
  "expiry_month": 6,
  "expiry_year": 2025,
  "name": "Bruce Wayne",
  "scheme": "VISA",
  "last4": "9996",
  "bin": "454347",
  "card_type": "CREDIT",
  "card_category": "CONSUMER",
  "issuer": "GOTHAM STATE BANK"
}

Reference token created successfully

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).
Path Parameters
  • tokenId
    Type: string Pattern: ^(tok)_(\w{26})$
    required

    The token ID

Responses
  • application/json
  • 401

    Unauthorized

  • 403

    Forbidden

  • 404

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

  • application/json
  • application/json
  • 504

    Gateway timeout

Request Example for get/tokens/{tokenId}/metadata
Shell Curl
curl 'https://{prefix}.api.sandbox.checkout.com/tokens/tok_4gzeau5o2uqubbk6fudbloo47a/metadata' \
  --header 'Authorization: YOUR_SECRET_TOKEN'

{
  "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": {
    "city": "London",
    "country": "GB"
  }
}

Token metadata retrieved successfully