Checkout.com API logo

Cards

Issue new cards to your cardholders, and manage cards you've already issued.

Create a card

Creates a physical or virtual card and issues it to the specified cardholder.

SecurityOAuth2: OAuth
Request
header Parameters
Cko-Idempotency-Key
string [ 1 .. 256 ] characters ^[A-Za-z0-9._-]+$

An optional idempotency key for safely retrying Issuing requests.

Example: 7c1b9f96-4f2e-4b1a-bc2b-3d0f1a2e9f3a
Request Body schema: application/json
required
type
required
string

The card type.

cardholder_id
required
string (IssuingCardholderId) = 30 characters ^crh_[a-z0-9]{26}$

The cardholder's unique identifier.

card_product_id
required
string = 30 characters ^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.

object (CardLifetime)

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"
  }
}
reference
string (IssuingReference) <= 256 characters

Your reference.

object

User's metadata

revocation_date
string (IssuingRevocationDate)

Date for the card to be automatically revoked. Must be after the current date and date only in the form yyyy-mm-dd.

display_name
string (DisplayName) [ 2 .. 26 ] characters ^[0-9a-zA-Z.\- ]{2,26}$

The name to display on the card.

is_single_use
boolean
Default: false

Sets whether the virtual card should expire after a single use.

activate_card
boolean
Default: true

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.

return_credentials
Array of strings

The credentials to retrieve on card creation.

Items Enum: "number" "cvc2"
control_profiles
Array of strings (IssuingControlProfileId)

The control profiles you want to add the card to as a target.

Array of objects (add-virtual-card-control-request)

The controls that will be set on the card.

Responses
201

Card created successfully

401

Unauthorized

422

Invalid data was sent

500

Internal Server Error

503

Service Unavailable

post/issuing/cards
Request samples
application/json
{
  • "type": "virtual",
  • "cardholder_id": "crh_d3ozhf43pcq2xbldn2g45qnb44",
  • "lifetime": {
    },
  • "reference": "X-123456-N11",
  • "metadata": {
    },
  • "revocation_date": "2027-03-12",
  • "card_product_id": "pro_7syjig3jq3mezlc3vjrdpfitl4",
  • "display_name": "JOHN KENNEDY",
  • "is_single_use": false,
  • "activate_card": true,
  • "return_credentials": [
    ],
  • "control_profiles": [
    ],
  • "controls": [
    ]
}
Response samples
application/json
{
  • "id": "crd_fa6psq242dcd6fdn5gifcq1491",
  • "client_id": "cli_vkuhvk4vjn2edkps7dfsq6emqm",
  • "entity_id": "ent_fa6psq242dcd6fdn5gifcq1491",
  • "display_name": "JOHN KENNEDY",
  • "last_four": "1234",
  • "expiry_month": 5,
  • "expiry_year": 2025,
  • "billing_currency": "USD",
  • "issuing_country": "US",
  • "status": "active",
  • "type": "virtual",
  • "reference": "X-123456-N11",
  • "scheme": "mastercard",
  • "created_date": "2019-09-10T10:11:12Z",
  • "_links": {},
  • "credentials": {
    },
  • "controls": [
    ]
}

Get card details

Retrieves the details for a card you issued previously.

The card's credentials are not returned in the response.

SecurityOAuth2: OAuth
Request
path Parameters
cardId
required
string (IssuingCardId) = 30 characters ^crd_[a-z0-9]{26}$

The card's unique identifier.

Example: crd_fa6psq242dcd6fdn5gifcq1491
Responses
200

Card retrieved successfully

401

Unauthorized

404

Card not found

500

Internal Server Error

get/issuing/cards/{cardId}
Request samples 
Response samples 
application/json
{}
Update card details
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.


SecurityOAuth2: OAuth 
Request 
path Parameters
cardId
required
string (IssuingCardId)   = 30 characters ^crd_[a-z0-9]{26}$
The card's unique identifier.


 
 Example:  crd_fa6psq242dcd6fdn5gifcq1491
Request Body schema: application/json
required
reference
string (IssuingReference)   <= 256 characters 
Your reference.


 
object (IssuingCardMetadata) 
User's metadata.


 
expiry_month
integer <int32>  (ExpiryMonth)   [ 1 .. 12 ] 
The card's expiration month.


 
expiry_year
integer <int32>  (ExpiryYear)   = 4 characters 
The card's expiration year.


 
Responses 
200
Card updated successfully


401
Unauthorized


404
Card not found


422
Invalid data was sent


500
Internal Server Error


patch/issuing/cards/{cardId}
Request samples 
application/json
{
  • "reference": "X-123456-N11",
  • "metadata": {
    },
  • "expiry_month": 5,
  • "expiry_year": 2025
}
Response samples 
application/json
{}
Enroll a card in 3DS
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.


SecurityOAuth2: OAuth 
Request 
path Parameters
cardId
required
string (IssuingCardId)   = 30 characters ^crd_[a-z0-9]{26}$
The card's unique identifier.


 
 Example:  crd_fa6psq242dcd6fdn5gifcq1491
Request Body schema: application/json
required
One of:
required
object (3dsSecurityPair) 
The question and answer security pair used to support knowledge-based 3DS authentication.


Security pairs are set per-card, not per-cardholder.


 
required
object (3dsPhoneNumber) 
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.


 
locale
string <language-COUNTRY>  (3dsLocale)   = 5 characters ^[a-z]{2}-[A-Z]{2}$
The 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. 


 Enum: "en-US" "fr-FR"  
Responses 
202
3DS card enrollment completed successfully


401
Unauthorized


404
Card not found


422
Invalid data was sent


500
Internal Server Error


post/issuing/cards/{cardId}/3ds-enrollment
Request samples 
application/json
{
  • "security_pair": {
    },
  • "locale": "en-US",
  • "phone_number": {
    }
}
Response samples 
application/json
{}
Update a card's 3DS details
Updates a card's 3DS enrollment details. At least one of the fields is required.


SecurityOAuth2: OAuth 
Request 
path Parameters
cardId
required
string (IssuingCardId)   = 30 characters ^crd_[a-z0-9]{26}$
The card's unique identifier.


 
 Example:  crd_fa6psq242dcd6fdn5gifcq1491
Request Body schema: application/json
required
One of:
object (3dsSecurityPair) 
The question and answer security pair used to support knowledge-based 3DS authentication.


Security pairs are set per-card, not per-cardholder.


 
locale
string <language-COUNTRY>  (3dsLocale)   = 5 characters ^[a-z]{2}-[A-Z]{2}$
The 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. 


 Enum: "en-US" "fr-FR"  
object (3dsPhoneNumber) 
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.


 
Responses 
202
Card 3DS details updated successfully


401
Unauthorized


404
Card not found


422
Invalid data was sent


500
Internal Server Error


patch/issuing/cards/{cardId}/3ds-enrollment
Request samples 
application/json
{
  • "security_pair": {
    },
  • "locale": "en-US",
  • "phone_number": {
    }
}
Response samples 
application/json
{}
Get a card's 3DS enrollment details
Retrieves a card's 3DS enrollment details.


SecurityOAuth2: OAuth 
Request 
path Parameters
cardId
required
string (IssuingCardId)   = 30 characters ^crd_[a-z0-9]{26}$
The card's unique identifier.


 
 Example:  crd_fa6psq242dcd6fdn5gifcq1491
Responses 
200
Card 3DS enrollment details retrieved successfully


401
Unauthorized


404
Card not found


500
Internal Server Error


get/issuing/cards/{cardId}/3ds-enrollment
Request samples 
Response samples 
application/json
{}
Activate a card
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.


SecurityOAuth2: OAuth 
Request 
path Parameters
cardId
required
string (IssuingCardId)   = 30 characters ^crd_[a-z0-9]{26}$
The card's unique identifier.


 
 Example:  crd_fa6psq242dcd6fdn5gifcq1491
Responses 
200
Card activated successfully


401
Unauthorized


404
Card not found


422
Invalid data was sent


post/issuing/cards/{cardId}/activate
Request samples 
Response samples 
application/json
{}
Get the card credentials
Retrieves the credentials for a card you issued previously.


SecurityOAuth2: OAuth 
Request 
path Parameters
cardId
required
string (IssuingCardId)   = 30 characters ^crd_[a-z0-9]{26}$
The card's unique identifier.


 
 Example:  crd_fa6psq242dcd6fdn5gifcq1491
query Parameters
credentials
string
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"



 Enum: "number" "cvc2" "number,cvc2"  
 Example:  credentials=number
Responses 
200
Card credentials retrieved successfully


401
Unauthorized


404
Card not found


422
Invalid data was sent


500
Internal Server Error


503
Service Unavailable


get/issuing/cards/{cardId}/credentials
Request samples 
Response samples 
application/json
{
  • "number": "4242424242424242",
  • "cvc2": "604"
}
Renew a card
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.


SecurityOAuth2: OAuth 
Request 
path Parameters
cardId
required
string (IssuingCardId)   = 30 characters ^crd_[a-z0-9]{26}$
The card's unique identifier.


 
 Example:  crd_fa6psq242dcd6fdn5gifcq1491
Request Body schema: application/json
required
One of:
display_name
string (DisplayName)   [ 2 .. 26 ] characters ^[0-9a-zA-Z.\- ]{2,26}$
The name to display on the card.


 
object (IssuingShippingInstruction) 
 
reference
string (IssuingReference)   <= 256 characters 
Your reference.


 
object
User's metadata


 
Responses 
200
Card renewed successfully


401
Unauthorized


404
Card not found


406
Not Acceptable


415
Unsupported Media Type


422
Invalid data was sent


429
Too Many Requests


post/issuing/cards/{cardId}/renew
Request samples 
application/json
{
  • "display_name": "JOHN KENNEDY",
  • "shipping_instructions": {
    },
  • "reference": "X-123456-N11",
  • "metadata": {
    }
}
Response samples 
application/json
{}
Revoke a card
Revokes an inactive, active, or suspended card to permanently decline all incoming authorizations.


This is a permanent action. Revoked cards cannot be reactivated.


SecurityOAuth2: OAuth 
Request 
path Parameters
cardId
required
string (IssuingCardId)   = 30 characters ^crd_[a-z0-9]{26}$
The card's unique identifier.


 
 Example:  crd_fa6psq242dcd6fdn5gifcq1491
Request Body schema: application/json
required
reason
string
The reason why the card is being revoked.


 Enum: "expired" "reported_lost" "reported_stolen"  
Responses 
200
Card revoked successfully


401
Unauthorized


404
Card not found


422
Invalid data was sent


post/issuing/cards/{cardId}/revoke
Request samples 
application/json
{
  • "reason": "reported_lost"
}
Response samples 
application/json
{}
Schedule card revocation
Schedules a card to be revoked at 00:00(UTC) on a specified date.


SecurityOAuth2: OAuth 
Request 
path Parameters
cardId
required
string (IssuingCardId)   = 30 characters ^crd_[a-z0-9]{26}$
The card's unique identifier.


 
 Example:  crd_fa6psq242dcd6fdn5gifcq1491
Request Body schema: application/json
required
revocation_date
required
string (IssuingRevocationDate) 
Date for the card to be automatically revoked. Must be after the current date and date only in the form yyyy-mm-dd.


 
Responses 
200
Revocation scheduled successfully


401
Unauthorized


422
Invalid data was sent


500
Internal Server Error


503
Service Unavailable


post/issuing/cards/{cardId}/schedule-revocation
Request samples 
application/json
{
  • "revocation_date": "2027-03-12"
}
Response samples 
application/json
{}
Delete scheduled revocation
Delete a card's scheduled revocation.


SecurityOAuth2: OAuth 
Request 
path Parameters
cardId
required
string (IssuingCardId)   = 30 characters ^crd_[a-z0-9]{26}$
The card's unique identifier.


 
 Example:  crd_fa6psq242dcd6fdn5gifcq1491
Responses 
200
Scheduled revocation deleted successfully


401
Unauthorized


500
Internal Server Error


503
Service Unavailable


delete/issuing/cards/{cardId}/schedule-revocation
Request samples 
Response samples 
application/json
{}
Suspend a card
Suspends an active or inactive card to temporarily decline all incoming authorizations.


A suspended card can be reactivated.


SecurityOAuth2: OAuth 
Request 
path Parameters
cardId
required
string (IssuingCardId)   = 30 characters ^crd_[a-z0-9]{26}$
The card's unique identifier.


 
 Example:  crd_fa6psq242dcd6fdn5gifcq1491
Request Body schema: application/json
required
reason
string
The reason why the card is being suspended.


 Enum: "suspected_lost" "suspected_stolen"  
Responses 
200
Card suspended successfully


401
Unauthorized


404
Card not found


422
Invalid data was sent


post/issuing/cards/{cardId}/suspend
Request samples 
application/json
{
  • "reason": "suspected_lost"
}
Response samples 
application/json
{}
➔ Next to Controls