Checkout.com API logo

Cardholders

Create new cardholders to issue cards to, and manage your existing cardholders.

Create a cardholder

Create a new cardholder that you can issue a card to at a later point.

SecurityOAuth2: OAuth
Request
Request Body schema: application/json
required
first_name
required
string [ 1 .. 40 ] characters

The cardholder's first name.

last_name
required
string [ 1 .. 40 ] characters

The cardholder's last name.

required
object

The cardholder's billing address.

type
required
string

The type of cardholder to create.

entity_id
required
string (IssuingEntityId) = 30 characters ^ent_[a-z0-9]{26}$

The entity's unique identifier.

reference
string (IssuingReference) <= 256 characters

Your reference.

middle_name
string [ 1 .. 40 ] characters

The cardholder's middle name.

email
string <email> [ 3 .. 254 ] characters

The cardholder's email address.

object

The cardholder's mobile phone number. This is used in the card tokenization one-time passcode (OTP) challenge flow and in delivery details for physical cards.

date_of_birth
string <date>

The cardholder's date of birth.
Format – YYYY-MM-DD

object

The cardholder's residential address. If this value is not provided, the cardholder's billing address is used instead, by default.

object (IdentificationDocument)

A legal document used to verify the cardholder's identity.

Responses
201

Cardholder created successfully

401

Unauthorized

422

Invalid data was sent

500

Internal Server Error

post/issuing/cardholders
Request samples
application/json
{
  • "type": "individual",
  • "reference": "X-123456-N11",
  • "entity_id": "ent_fa6psq242dcd6fdn5gifcq1491",
  • "first_name": "John",
  • "middle_name": "Fitzgerald",
  • "last_name": "Kennedy",
  • "email": "john.kennedy@myemaildomain.com",
  • "phone_number": {
    },
  • "date_of_birth": "1985-05-15",
  • "billing_address": {
    },
  • "residency_address": {
    },
  • "document": {
    }
}
Response samples
application/json
{}

Get cardholder details

Retrieve the details for a cardholder you created previously.

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

The cardholder's unique identifier.

Example: crh_d3ozhf43pcq2xbldn2g45qnb44
Responses
200

Cardholder retrieved successfully

401

Unauthorized

404

Cardholder not found

500

Internal Server Error

get/issuing/cardholders/{cardholderId}
Request samples 
Response samples 
application/json
{
  • "id": "crh_d3ozhf43pcq2xbldn2g45qnb44",
  • "type": "individual",
  • "first_name": "John",
  • "middle_name": "Fitzgerald",
  • "last_name": "Kennedy",
  • "email": "john.kennedy@myemaildomain.com",
  • "phone_number": {
    },
  • "date_of_birth": "1985-05-28",
  • "billing_address": {
    },
  • "residency_address": {
    },
  • "reference": "X-123456-N11",
  • "client_id": "cli_vkuhvk4vjn2edkps7dfsq6emqm",
  • "account_entity_id": "ent_fa6psq242dcd6fdn5gifcq1491",
  • "parent_sub_entity_id": "ent_fa6psq242dcd6fdn5gifcq1491",
  • "entity_id": "ent_fa6psq242dcd6fdn5gifcq1491",
  • "status": "active",
  • "created_date": "2019-09-10T10:11:12Z",
  • "last_modified_date": "2019-09-11T10:11:12Z",
  • "_links": {}
}
Update a cardholder
Updates the details of an existing cardholder.


SecurityOAuth2: OAuth 
Request 
path Parameters
cardholderId
required
string (IssuingCardholderId)   = 30 characters ^crh_[a-z0-9]{26}$
The cardholder's unique identifier.


 
 Example:  crh_d3ozhf43pcq2xbldn2g45qnb44
Request Body schema: application/json
required
first_name
string  [ 1 .. 40 ] characters 
The cardholder's first name.


 
middle_name
string  [ 1 .. 40 ] characters 
The cardholder's middle name. To set this field to null, pass null in your request.


 
last_name
string  [ 1 .. 40 ] characters 
The cardholder's last name.


 
date_of_birth
string <date> 
The cardholder's date of birth in the YYYY-MM-DD format. To set this field to null, pass null in your request.


 
object
The cardholder's mobile phone number. This is used in the card tokenization one-time passcode (OTP) challenge flow and in delivery details for physical cards.


 
email
string <email>   [ 3 .. 254 ] characters 
The cardholder's email address. To set this field to null, pass null in your request.


 
object
The  cardholder's billing address.


 
object
The cardholder's residency address. To set this field to null, pass null in your request.


 
object (IdentificationDocument) 
A legal document used to verify the cardholder's identity.


 
Responses 
200
Cardholder updated successfully


401
Unauthorized


404
Cardholder not found


422
Invalid data was sent


500
Internal Server Error


patch/issuing/cardholders/{cardholderId}
Request samples 
application/json
{
  • "first_name": "John",
  • "middle_name": "Fitzgerald",
  • "last_name": "Kennedy",
  • "date_of_birth": "1985-05-15",
  • "phone_number": {
    },
  • "email": "john.kennedy@myemaildomain.com",
  • "billing_address": {
    },
  • "residency_address": {
    },
  • "document": {
    }
}
Response samples 
application/json
{}
Get a cardholder's cards
Retrieves the cards issued to the specified cardholder.


Card credentials are not returned in the response.
The response is limited to a maximum of 150 cards.


SecurityOAuth2: OAuth 
Request 
path Parameters
cardholderId
required
string (IssuingCardholderId)   = 30 characters ^crh_[a-z0-9]{26}$
The cardholder's unique identifier.


 
 Example:  crh_d3ozhf43pcq2xbldn2g45qnb44
query Parameters
statuses
string
The card statuses to filter the results by.
Cards matching any status in this list are returned. If the list is empty, all cards are returned.
Format - Comma-separated list


 
 Example:  statuses=active,suspended
Responses 
200
Cardholder's cards retrieved successfully


401
Unauthorized


404
Cardholder not found


500
Internal Server Error


get/issuing/cardholders/{cardholderId}/cards
Request samples 
Response samples 
application/json
{}
➔ Next to Cards