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
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.
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.
The source of the payment
The source of the payment
Card Token Request
The type of card details to be tokenized
The card number
The expiry month of the card
The expiry year of the card
The cardholder's name
The card verification value/code. 3 digits, except for American Express (4 digits)
The first 2 digits of the card PIN
The payment source owner's billing address
The payment source owner's phone number
Your own key-value pairs to attach to the card token. Only supported when type is card.
The metadata is stored with the token for the token's lifetime. When you use the token to create a payment instrument, the metadata is stored with the instrument.
You can reference metadata values in Forward API requests using the {{metadata.KEY}} placeholder.
Unauthorized
Gateway timeout
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"
},
"metadata": {
"documentNumber": "12345678900",
"partnerId": "partner_123"
}
}'
{
"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",
"metadata": {
"documentNumber": "12345678900",
"partnerId": "partner_123"
}
}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).Pattern: ^(tok)_(\w{26})$The token ID
Unauthorized
Forbidden
Token not found, or token type does not support metadata retrieval
Gateway timeout
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"
},
"metadata": {
"documentNumber": "12345678900",
"partnerId": "partner_123"
}
}