Create new cardholders to issue cards to, and manage your existing cardholders.
Create new cardholders to issue cards to, and manage your existing cardholders.
Create a new cardholder that you can issue a card to at a later point.
The cardholder to create.
The cardholder to create.
The type of cardholder to create.
Pattern: ^ent_[a-z0-9]{26}$The entity's unique identifier.
The cardholder's first name.
The cardholder's last name.
The cardholder's billing address.
Your reference.
The cardholder's middle name.
The cardholder's email address.
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.
The cardholder's date of birth.
Format – YYYY-MM-DD
The cardholder's residential address. If this value is not provided, the cardholder's billing address is used instead, by default.
Unauthorized
Internal Server Error
curl 'https://{prefix}.api.sandbox.checkout.com/issuing/cardholders' \
--request POST \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
--data '{
"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": {
"country_code": "+1",
"number": "415 555 2671"
},
"date_of_birth": "1985-05-15",
"billing_address": {
"address_line1": "Checkout.com",
"address_line2": "90 Tottenham Court Road",
"city": "London",
"state": "London",
"zip": "W1T 4TJ",
"country": "GB"
},
"residency_address": {
"address_line1": "Checkout.com",
"address_line2": "90 Tottenham Court Road",
"city": "London",
"state": "London",
"zip": "W1T 4TJ",
"country": "GB"
}
}'
{
"id": "crh_d3ozhf43pcq2xbldn2g45qnb44",
"client_id": "cli_vkuhvk4vjn2edkps7dfsq6emqm",
"entity_id": "ent_fa6psq242dcd6fdn5gifcq1491",
"type": "individual",
"status": "active",
"reference": "X-123456-N11",
"created_date": "2026-09-23T13:52:07.856Z",
"last_modified_date": "2019-09-10T10:11:12Z",
"_links": {
"self": {
"href": "https://{prefix}.api.checkout.com/issuing/cardholders/crh_d3ozhf43pcq2xbldn2g45qnb44",
"actions": [
"GET"
],
"types": [
"application/json"
]
},
"cards": {
"href": "https://{prefix}.api.checkout.com/issuing/cards",
"actions": [
"POST"
],
"types": [
"application/json"
]
}
}
}Retrieve the details for a cardholder you created previously.
Pattern: ^crh_[a-z0-9]{26}$The cardholder's unique identifier.
Unauthorized
Cardholder not found
Internal Server Error
curl 'https://{prefix}.api.sandbox.checkout.com/issuing/cardholders/crh_d3ozhf43pcq2xbldn2g45qnb44' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
"id": "crh_d3ozhf43pcq2xbldn2g45qnb44",
"type": "individual",
"first_name": "John",
"middle_name": "Fitzgerald",
"last_name": "Kennedy",
"email": "john.kennedy@myemaildomain.com",
"phone_number": {
"country_code": "+1",
"number": "415 555 2671"
},
"date_of_birth": "1985-05-28",
"billing_address": {
"address_line1": "Checkout.com",
"address_line2": "90 Tottenham Court Road",
"city": "London",
"state": "London",
"zip": "W1T 4TJ",
"country": "GB"
},
"residency_address": {
"address_line1": "Checkout.com",
"address_line2": "90 Tottenham Court Road",
"city": "London",
"state": "London",
"zip": "W1T 4TJ",
"country": "GB"
},
"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": {
"self": {
"href": "https://{prefix}.api.checkout.com/issuing/cardholders/crh_d3ozhf43pcq2xbldn2g45qnb44",
"actions": [
"GET"
],
"types": [
"application/json"
]
},
"cards": {
"href": "https://{prefix}.api.checkout.com/issuing/cards",
"actions": [
"POST"
],
"types": [
"application/json"
]
}
}
}Updates the details of an existing cardholder.
Pattern: ^crh_[a-z0-9]{26}$The cardholder's unique identifier.
The cardholder's fields to update.
The cardholder's first name.
The cardholder's middle name. To set this field to null, pass null in your request.
The cardholder's last name.
The cardholder's date of birth in the YYYY-MM-DD format. To set this field to null, pass null in your request.
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.
The cardholder's email address. To set this field to null, pass null in your request.
The cardholder's billing address.
The cardholder's residency address. To set this field to null, pass null in your request.
Unauthorized
Cardholder not found
Internal Server Error
curl 'https://{prefix}.api.sandbox.checkout.com/issuing/cardholders/crh_d3ozhf43pcq2xbldn2g45qnb44' \
--request PATCH \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
--data '{
"first_name": "John",
"middle_name": "Fitzgerald",
"last_name": "Kennedy",
"date_of_birth": "1985-05-15",
"phone_number": {
"country_code": "+1",
"number": "415 555 2671"
},
"email": "john.kennedy@myemaildomain.com",
"billing_address": {
"address_line1": "Checkout.com",
"address_line2": "90 Tottenham Court Road",
"city": "London",
"state": "London",
"zip": "W1T 4TJ",
"country": "GB"
},
"residency_address": {
"address_line1": "Checkout.com",
"address_line2": "90 Tottenham Court Road",
"city": "London",
"state": "London",
"zip": "W1T 4TJ",
"country": "GB"
}
}'
{
"last_modified_date": "2019-09-10T10:11:12Z",
"_links": {
"self": {
"href": "https://{prefix}.api.checkout.com/issuing/cardholders/crh_d3ozhf43pcq2xbldn2g45qnb44",
"actions": [
"GET"
],
"types": [
"application/json"
]
}
}
}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.
Pattern: ^crh_[a-z0-9]{26}$The cardholder's unique identifier.
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
Unauthorized
Cardholder not found
Internal Server Error
curl 'https://{prefix}.api.sandbox.checkout.com/issuing/cardholders/crh_d3ozhf43pcq2xbldn2g45qnb44/cards' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
"cards": [
{
"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": "virtual",
"billing_currency": "USD",
"issuing_country": "US",
"reference": "X-123456-N11",
"metadata": {
"udf1": "metadata1",
"udf2": "metadata2",
"udf3": "metadata3",
"udf4": "metadata4",
"udf5": "metadata5"
},
"scheduled_activation_date": "2026-06-01T10:00Z",
"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"
]
}
},
"is_single_use": false
}
]
}