Issue new cards to your cardholders, and manage cards you've already issued.
Creates a physical or virtual card and issues it to the specified cardholder.
Pattern: ^[A-Za-z0-9._-]+$An optional idempotency key for safely retrying Issuing requests.
The card type.
Pattern: ^crh_[a-z0-9]{26}$The cardholder's unique identifier.
Pattern: ^pro_[a-z0-9]{26}$The card product's unique identifier. This field is required if there are multiple card products associated with the entity.
The duration of time during which the card will accept incoming authorizations.
The unit and value combination you supply will determine the card's expiry date from the date of issue. For example, to set the card to expire in a year and a half, pass the following:
{
"lifetime": {
"unit": "Months",
"value": "18"
}
}
Your reference.
User's metadata
Deprecated. Use scheduled_revocation_date instead.
If you provide both fields, the scheduled_revocation_date value overrides this value.
Date scheduling the card's first activation. Only applies to the initial activation of a card. Two formats are supported:
YYYY-MM-DD (treated as midnight UTC)YYYY-MM-DDTHH:mmZ (UTC) or YYYY-MM-DDTHH:mm±HH:mm (offset)Only round hours are allowed when a time is provided (HH:00). The value must be at least the next round hour after the request time.
Pattern: ^[0-9a-zA-Z.\- ]{2,26}$The name to display on the card.
Sets whether the virtual card should expire after a single use.
Sets whether to activate the newly created card upon creation.
If set to false, the cardholder will not be able to process transactions until you activate the card.
The credentials to retrieve on card creation.
The control profiles you want to add the card to as a target.
The controls that will be set on the card.
The control to create.
Unauthorized
Internal Server Error
Service Unavailable
curl 'https://{prefix}.api.sandbox.checkout.com/issuing/cards' \
--request POST \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
--data '{
"type": "virtual",
"cardholder_id": "crh_d3ozhf43pcq2xbldn2g45qnb44",
"lifetime": {
"unit": "Months",
"value": 6
},
"reference": "X-123456-N11",
"metadata": {
"udf1": "metadata1",
"udf2": "metadata2",
"udf3": "metadata3",
"udf4": "metadata4",
"udf5": "metadata5"
},
"scheduled_revocation_date": "2027-03-12",
"scheduled_activation_date": "2026-06-01T10:00Z",
"card_product_id": "pro_7syjig3jq3mezlc3vjrdpfitl4"
}'
{
"id": "crd_fa6psq242dcd6fdn5gifcq1491",
"client_id": "cli_vkuhvk4vjn2edkps7dfsq6emqm",
"entity_id": "ent_fa6psq242dcd6fdn5gifcq1491",
"last_four": "1234",
"expiry_month": 5,
"expiry_year": 2025,
"billing_currency": "USD",
"issuing_country": "US",
"status": "active",
"type": "virtual",
"scheme": "mastercard",
"created_date": "2019-09-10T10:11:12Z"
}Retrieves the details for a card you issued previously.
The card's credentials are not returned in the response.
Pattern: ^crd_[a-z0-9]{26}$The card's unique identifier.
Unauthorized
Card not found
Internal Server Error
curl 'https://{prefix}.api.sandbox.checkout.com/issuing/cards/crd_fa6psq242dcd6fdn5gifcq1491' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
"id": "crd_fa6psq242dcd6fdn5gifcq1491",
"client_id": "cli_vkuhvk4vjn2edkps7dfsq6emqm",
"entity_id": "ent_fa6psq242dcd6fdn5gifcq1491",
"cardholder_id": "crh_d3ozhf43pcq2xbldn2g45qnb44",
"card_product_id": "pro_7syjig3jq3mezlc3vjrdpfitl4",
"last_four": "1234",
"expiry_month": 5,
"expiry_year": 2025,
"status": "active",
"type": "virtual",
"billing_currency": "USD",
"issuing_country": "US",
"scheme": "mastercard"
}Update the details of an issued card.
Only the fields for which you provide values will be updated. If you pass null, the existing value will be removed.
Pattern: ^crd_[a-z0-9]{26}$The card's unique identifier.
The card fields to update.
Set the card's status to active to activate an inactive or suspended card.
If you submit this field, you cannot specify a scheduled_activation_date. If you do, you receive a scheduled_activation_date_conflicts_with_activation error.
Your reference.
User's metadata.
The card's expiration month.
The card's expiration year.
The card will be revoked at midnight UTC on the date specified.
YYYY-MM-DDDeprecated. Use scheduled_revocation_date instead.
If you provide both fields, the scheduled_revocation_date value overrides this value.
Date scheduling the card's first activation. Only applies to the initial activation of a card. Two formats are supported:
YYYY-MM-DD (treated as midnight UTC)YYYY-MM-DDTHH:mmZ (UTC) or YYYY-MM-DDTHH:mm±HH:mm (offset)Only round hours are allowed when a time is provided (HH:00). The value must be at least the next round hour after the request time.
Unauthorized
Card not found
Internal Server Error
curl 'https://{prefix}.api.sandbox.checkout.com/issuing/cards/crd_fa6psq242dcd6fdn5gifcq1491' \
--request PATCH \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
--data '{
"status": "active",
"reference": "X-123456-N11",
"metadata": {
"udf1": "metadata1",
"udf2": "metadata2",
"udf3": "metadata3",
"udf4": "metadata4",
"udf5": "metadata5"
},
"expiry_month": 5,
"expiry_year": 2025,
"scheduled_revocation_date": "2027-03-12",
"scheduled_activation_date": "2026-06-01T10:00Z"
}'
{
"id": "crd_fa6psq242dcd6fdn5gifcq1491",
"client_id": "cli_vkuhvk4vjn2edkps7dfsq6emqm",
"entity_id": "ent_fa6psq242dcd6fdn5gifcq1491",
"cardholder_id": "crh_d3ozhf43pcq2xbldn2g45qnb44",
"card_product_id": "pro_7syjig3jq3mezlc3vjrdpfitl4",
"user_id": "usr_fa6psq242dcd6fdn5gifcq1491",
"last_four": "1234",
"expiry_month": 5,
"expiry_year": 2025,
"status": "active",
"display_name": "JOHN KENNEDY",
"type": "string",
"billing_currency": "USD",
"issuing_country": "US",
"reference": "X-123456-N11",
"metadata": {
"udf1": "metadata1",
"udf2": "metadata2",
"udf3": "metadata3",
"udf4": "metadata4",
"udf5": "metadata5"
},
"scheduled_revocation_date": "2027-03-12",
"scheduled_activation_date": "2026-06-01T10:00Z",
"last_activated_on": "2019-09-10T10:11:12Z",
"root_card_id": "crd_fa6psq242dcd6fdn5gifcq1491",
"parent_card_id": "crd_qm26t52qz3yejjo2t4btqvxtzi",
"scheme": "mastercard",
"created_date": "2021-09-09T19:41:39Z",
"last_modified_date": "2021-09-09T19:41:39Z",
"_links": {
"self": {
"href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491",
"actions": [
"GET"
],
"types": [
"application/json"
]
},
"credentials": {
"href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491/credentials",
"actions": [
"GET"
],
"types": [
"application/json"
]
},
"revoke": {
"href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491/revoke",
"actions": [
"POST"
],
"types": [
"application/json"
]
},
"controls": {
"href": "https://{prefix}.api.checkout.com/issuing/controls?target_id=crd_fa6psq42dcdd6fdn5gifcq1491",
"actions": [
"GET"
],
"types": [
"application/json"
]
}
}
}Enrolls a card in 3D Secure (3DS). Additional information is requested from the cardholder through a 3DS challenge when performing a transaction.
Two-factor authentication (2FA) is supported. For maximum security, we recommend using a combination of a one-time password (OTP) sent via SMS, along with a password or question and answer security pair.
Pattern: ^crd_[a-z0-9]{26}$The card's unique identifier.
The question and answer security pair used to support knowledge-based 3DS authentication.
Security pairs are set per-card, not per-cardholder.
The phone number to send the one-time password (OTP) for 3DS authentication to.
This phone number is independent of the cardholder's mobile phone number on file. The number is used for authorizations that require a 3DS challenge.
Pattern: ^[a-z]{2}-[A-Z]{2}$Format: language-COUNTRYenumThe card's locale, as one of the possible BCP 47 formatted enum values.
The locale determines the language that text messages and 3DS challenge prompts are displayed to the user in, as well as the format used for amounts and dates.
When not provided, the locale of the card product is used.
Unauthorized
Card not found
Internal Server Error
curl 'https://{prefix}.api.sandbox.checkout.com/issuing/cards/crd_fa6psq242dcd6fdn5gifcq1491/3ds-enrollment' \
--request POST \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
--data '{
"security_pair": {
"question": "Who are you?",
"answer": "Bond. James Bond."
},
"locale": "en-US",
"phone_number": {
"country_code": "+1",
"number": "415 555 2671"
}
}'
{
"_links": {
"self": {
"href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491/3ds-enrollment",
"actions": [
"GET"
],
"types": [
"application/json"
]
}
}
}Updates a card's 3DS enrollment details. At least one of the fields is required.
Pattern: ^crd_[a-z0-9]{26}$The card's unique identifier.
The question and answer security pair used to support knowledge-based 3DS authentication.
Security pairs are set per-card, not per-cardholder.
Pattern: ^[a-z]{2}-[A-Z]{2}$Format: language-COUNTRYenumThe card's locale, as one of the possible BCP 47 formatted enum values.
The locale determines the language that text messages and 3DS challenge prompts are displayed to the user in, as well as the format used for amounts and dates.
When not provided, the locale of the card product is used.
The phone number to send the one-time password (OTP) for 3DS authentication to.
This phone number is independent of the cardholder's mobile phone number on file. The number is used for authorizations that require a 3DS challenge.
Unauthorized
Card not found
Internal Server Error
curl 'https://{prefix}.api.sandbox.checkout.com/issuing/cards/crd_fa6psq242dcd6fdn5gifcq1491/3ds-enrollment' \
--request PATCH \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
--data '{
"security_pair": {
"question": "Who are you?",
"answer": "Bond. James Bond."
},
"locale": "en-US",
"phone_number": {
"country_code": "+1",
"number": "415 555 2671"
}
}'
{
"_links": {
"self": {
"href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491/3ds-enrollment",
"actions": [
"GET"
],
"types": [
"application/json"
]
}
}
}Retrieves a card's 3DS enrollment details.
Pattern: ^crd_[a-z0-9]{26}$The card's unique identifier.
Unauthorized
Card not found
Internal Server Error
curl 'https://{prefix}.api.sandbox.checkout.com/issuing/cards/crd_fa6psq242dcd6fdn5gifcq1491/3ds-enrollment' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
"locale": "en-US",
"phone_number": {
"country_code": "+1",
"number": "415 555 2671"
},
"security_question": {
"question": "****",
"answer": "****"
},
"password": "string",
"created_date": "2019-09-10T10:11:12Z",
"last_modified_date": "2019-09-11T10:11:12Z",
"_links": {
"self": {
"href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491/3ds-enrollment",
"actions": [
"GET"
],
"types": [
"application/json"
]
}
}
}Activates an inactive or suspended card so that incoming authorizations can be approved.
Activating a renewed card will schedule the parent card for revocation the following day, and transfer all configurations to the newly activated card. This includes 3DS enrollment, card controls, control profiles and tokenisation.
Pattern: ^crd_[a-z0-9]{26}$The card's unique identifier.
Unauthorized
Card not found
curl 'https://{prefix}.api.sandbox.checkout.com/issuing/cards/crd_fa6psq242dcd6fdn5gifcq1491/activate' \
--request POST \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
"last_activated_on": "2019-09-10T10:11:12Z",
"_links": {
"self": {
"href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491",
"actions": [
"GET"
],
"types": [
"application/json"
]
},
"revoke": {
"href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491/revoke",
"actions": [
"POST"
],
"types": [
"application/json"
]
},
"suspend": {
"href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491/suspend",
"actions": [
"POST"
],
"types": [
"application/json"
]
},
"controls": {
"href": "https://{prefix}.api.checkout.com/issuing/controls?target_id=crd_fa6psq42dcdd6fdn5gifcq1491",
"actions": [
"GET"
],
"types": [
"application/json"
]
}
}
}Retrieves the credentials for a card you issued previously.
Pattern: ^crd_[a-z0-9]{26}$The card's unique identifier.
The credentials to retrieve.
You can either specify number or cvc2 to retrieve the specified credential, or both as a comma-separated list. For example, to retrieve both the CVC and PAN:
"credentials": "number, cvc2"
Unauthorized
Card not found
Internal Server Error
Service Unavailable
curl 'https://{prefix}.api.sandbox.checkout.com/issuing/cards/crd_fa6psq242dcd6fdn5gifcq1491/credentials' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
"number": "4242424242424242",
"cvc2": "604"
}Renew an active, inactive, or suspended card. A card cannot be renewed if it is revoked, expired, or is a single use virtual card.
The renewed card will have a different, nonconsecutive number (PAN), expiry date, and CVV.
Any configuration set on the parent card will be copied to the renewed card when the renewed card is activated. This includes 3DS enrollment, card controls, control profiles, and tokenisation.
Pattern: ^crd_[a-z0-9]{26}$The card's unique identifier.
Pattern: ^[0-9a-zA-Z.\- ]{2,26}$The name to display on the card.
Your reference.
User's metadata
Unauthorized
Card not found
Not Acceptable
Unsupported Media Type
Too Many Requests
curl 'https://{prefix}.api.sandbox.checkout.com/issuing/cards/crd_fa6psq242dcd6fdn5gifcq1491/renew' \
--request POST \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
--data '{
"display_name": "JOHN KENNEDY",
"shipping_instructions": {
"shipping_address": {
"address_line1": "Checkout.com",
"address_line2": "90 Tottenham Court Road",
"city": "London",
"state": "London",
"zip": "W1T 4TJ",
"country": "GB"
}
},
"reference": "X-123456-N11",
"metadata": {
"udf1": "metadata1",
"udf2": "metadata2",
"udf3": "metadata3",
"udf4": "metadata4",
"udf5": "metadata5"
}
}'
{
"parent_card_id": "crd_fa6psq242dcd6fdn5gifcq1491",
"cardholder_id": "crh_d3ozhf43pcq2xbldn2g45qnb44",
"status": "inactive",
"type": "string",
"id": "crd_zdihd7452165pk5lgywaa52147",
"client_id": "cli_vkuhvk4vjn2edkps7dfsq6emqm",
"entity_id": "ent_fa6psq242dcd6fdn5gifcq1491",
"last_four": "1234",
"expiry_year": 2025,
"expiry_month": 5,
"display_name": "JOHN KENNEDY",
"reference": "X-123456-N11",
"created_date": "2021-09-09T19:41:39Z",
"billing_currency": "USD",
"issuing_country": "US",
"_links": {
"self": {
"href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491",
"actions": [
"GET"
],
"types": [
"application/json"
]
},
"credentials": {
"href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491/credentials",
"actions": [
"GET"
],
"types": [
"application/json"
]
},
"activate": {
"href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491/activate",
"actions": [
"POST"
],
"types": [
"application/json"
]
},
"controls": {
"href": "https://{prefix}.api.checkout.com/issuing/controls?target_id=crd_fa6psq42dcdd6fdn5gifcq1491",
"actions": [
"GET"
],
"types": [
"application/json"
]
}
}
}Revokes an inactive, active, or suspended card to permanently decline all incoming authorizations.
This is a permanent action. Revoked cards cannot be reactivated.
Pattern: ^crd_[a-z0-9]{26}$The card's unique identifier.
The reason why the card is being revoked.
Unauthorized
Card not found
curl 'https://{prefix}.api.sandbox.checkout.com/issuing/cards/crd_fa6psq242dcd6fdn5gifcq1491/revoke' \
--request POST \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
--data '{
"reason": "reported_lost"
}'
{
"_links": {
"self": {
"href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491",
"actions": [
"GET"
],
"types": [
"application/json"
]
},
"controls": {
"href": "https://{prefix}.api.checkout.com/issuing/controls?target_id=crd_fa6psq42dcdd6fdn5gifcq1491",
"actions": [
"GET"
],
"types": [
"application/json"
]
}
}
}Suspends an active or inactive card to temporarily decline all incoming authorizations.
A suspended card can be reactivated.
Pattern: ^crd_[a-z0-9]{26}$The card's unique identifier.
The reason why the card is being suspended.
Unauthorized
Card not found
curl 'https://{prefix}.api.sandbox.checkout.com/issuing/cards/crd_fa6psq242dcd6fdn5gifcq1491/suspend' \
--request POST \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
--data '{
"reason": "suspected_lost"
}'
{
"_links": {
"self": {
"href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491",
"actions": [
"GET"
],
"types": [
"application/json"
]
},
"activate": {
"href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491/activate",
"actions": [
"POST"
],
"types": [
"application/json"
]
},
"revoke": {
"href": "https://{prefix}.api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491/revoke",
"actions": [
"POST"
],
"types": [
"application/json"
]
},
"controls": {
"href": "https://{prefix}.api.checkout.com/issuing/controls?target_id=crd_fa6psq42dcdd6fdn5gifcq1491",
"actions": [
"GET"
],
"types": [
"application/json"
]
}
}
}