CHcheckout
Tokens

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).
get/tokens/{tokenId}/metadata

Request

Path parameters

tokenIdstring required
Example:tok_4gzeau5o2uqubbk6fudbloo47a

The token ID

Response

Token metadata retrieved successfully

tokenstring required

The token ID

typestring required

The token type.

expires_onstring date-time required

Read-only UTC timestamp, automatically assigned by us

expiry_monthinteger required

The card expiry month.

expiry_yearinteger required

The card expiry year.

schemestring required

The card scheme.

last4string required

The last four digits of the card number.

binstring required

The card issuer BIN.

card_type'CREDIT' | 'DEBIT' | 'PREPAID' | 'CHARGE' | 'DEFERRED DEBIT'

The card type.

card_category'CONSUMER' | 'COMMERCIAL'

The card category.

issuerstring

The name of the card issuer.

issuer_countrystring

The card issuer's country (<a href="https://www.checkout.com/docs/previous/resources/codes/country-codes" target="blank">two-letter ISO code</a>).

product_idstring

The issuer or card scheme's product identifier.

product_typestring

The issuer or card scheme's product type.

metadataInstrumentMetadata

A set of key-value pairs that you can attach to a card token or payment instrument to store your own references, such as a customer document number or partner reference.

You can include a maximum of 20 key-value pairs. Each key must be between 1 and 100 characters long, and each value can be up to 100 characters long. Keys and values must be strings. Nested objects, arrays, numbers, booleans, and null values are not supported.

Metadata is stored encrypted, and is returned exactly as you provided it. Keys are case-sensitive.

Do not store card details, credentials, or personal data you do not have consent to store in metadata.

Example response

{
  "token": "tok_4gzeau5o2uqubbk6fudbloo47a",
  "type": "card",
  "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"
  },
  "metadata": {
    "documentNumber": "12345678900",
    "partnerId": "partner_123"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.