---
title: "Get token metadata"
method: GET
path: "/tokens/{tokenId}/metadata"
tags: ["Tokens"]
---

# Get token metadata

`GET /tokens/{tokenId}/metadata`

## Request

- Base URL: `https://{prefix}.api.sandbox.checkout.com`
- URL: `https://{prefix}.api.sandbox.checkout.com/tokens/{tokenId}/metadata`
- Auth: one of:
  - API key in header `Authorization`
  - OAuth 2
    - Client credentials
    - Token URL: `string` scopes: `vault:tokens-metadata`
- TypeScript: <https://skmtc.dev/checkout/apis/checkout-com-api-reference/docs/tokens/:tokenId/metadata/get.ts> (a function with typed inputs; its response is checked against the schema)

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` string, required

## Response `200`

Token metadata retrieved successfully

- TokenMetadataResponse
  - `token` string, required: The token ID
  - `type` string, required: The token type.
  - `expires_on` string, date-time, required: Read-only UTC timestamp, automatically assigned by us
  - `expiry_month` integer, required: The card expiry month.
  - `expiry_year` integer, required: The card expiry year.
  - `scheme` string, required: The card scheme.
  - `last4` string, required: The last four digits of the card number.
  - `bin` string, required: The card issuer BIN.
  - `card_type` 'CREDIT' | 'DEBIT' | 'PREPAID' | 'CHARGE' | 'DEFERRED DEBIT': The card type.
  - `card_category` 'CONSUMER' | 'COMMERCIAL': The card category.
  - `issuer` string: The name of the card issuer.
  - `issuer_country` string: 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_id` string: The issuer or card scheme's product identifier.
  - `product_type` string: The issuer or card scheme's product type.
  - `billing_address` object, nullable: Partial billing address — city and country only.
    - `city` string: The address city
    - `country` string: The billing address country's (<a href="https://www.checkout.com/docs/previous/resources/codes/country-codes" target="blank">two-letter ISO code</a>).
  - `metadata` InstrumentMetadata: 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.

## Other responses

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

---

[API](https://skmtc.dev/checkout/apis/checkout-com-api-reference.md) - [All operations](https://skmtc.dev/checkout/apis/checkout-com-api-reference/llms.txt) - [OpenAPI document](https://skmtc.dev/checkout/apis/checkout-com-api-reference/revisions/0f1abdb1c3e9?raw)