Create and manage cardholders

Last updated: September 11, 2024

Before you can issue a card, you must first create a cardholder to issue it to. You can then update the cardholder's details as required. For example, phone number, email address, last name.

Note

Some regions require Address Verification Service (AVS) checks during card-not-present (CNP) transactions. You must provide a valid billing address when creating or updating a cardholder so the AVS checks can be performed.

You can create a cardholder profile using the Dashboard and the API.

Sign in to the Dashboard.
Go to Issuing > Cardholders.
Select Create cardholder.
Enter the cardholder's details as required.
Select Create cardholder.
The cardholder's profile appears in the list on the Cardholders page.

Call the Create a cardholder endpoint:

post

https://api.checkout.com/issuing/cardholders


1{
2  "type": "individual",
3  "reference": "X-123456-N11",
4  "entity_id": "ent_fa6psq242dcd6fdn5gifcq1491",
5  "first_name": "Toby",
6  "middle_name": "Fitzgerald",
7  "last_name": "Arden",
8  "email": "[email protected]",
9  "phone_number": {
10    "country_code": "+1",
11    "number": "415 555 2671"
12  },
13  "date_of_birth": "1985-05-15",
14  "billing_address": {
15    "address_line1": "654 Example St.",
16    "address_line2": "Flat 987",
17    "city": "London",
18    "state": "London",
19    "zip": "W1T 4TJ",
20    "country": "GB"
21  },
22  "residency_address": {
23    "address_line1": "654 Example St.",
24    "address_line2": "Flat 987",
25    "city": "London",
26    "state": "London",
27    "zip": "W1T 4TJ",
28    "country": "GB"
29  },
30  "document": {
31    "type": "national_identity_card",
32    "front_document_id": "file_6lbss42ezvoufcb2beo76rvwly",
33    "back_document_id": "file_aaz5pemp6326zbuvevp6qroqu4"
34  }
35}


1{
2  "id": "crh_d3ozhf43pcq2xbldn2g45qnb44",
3  "client_id": "cli_vkuhvk4vjn2edkps7dfsq6emqm",
4  "entity_id": "ent_fa6psq242dcd6fdn5gifcq1491",
5  "type": "individual",
6  "status": "active",
7  "reference": "X-123456-N11",
8  "created_date": "string",
9  "last_modified_date": "2019-09-10T10:11:12Z",
10  "_links": {
11    "self": {
12      "href": "https://api.checkout.com/issuing/cardholders/crh_d3ozhf43pcq2xbldn2g45qnb44",
13      "actions": [
14        "GET"
15      ],
16      "types": [
17        "application/json"
18      ]
19    },
20    "cards": {
21      "href": "https://api.checkout.com/issuing/cards",
22      "actions": [
23        "POST"
24      ],
25      "types": [
26        "application/json"
27      ]
28    }
29  }
30}

After creating a cardholder profile, to retrieve their details, you can call the Get cardholder details endpoint.

You can update a cardholder profile using the Dashboard and the API.

Sign in to the Dashboard.
Go to Issuing > Cardholders.
Find the cardholder using the search or filters and select them.
On the Cardholders details page, select Edit cardholder.
On the Edit cardholder details page, update their information as required.
Select Save.
The updated details are displayed on the Cardholders details page.

Call the Update a cardholder endpoint.

With this request, you can:

Change a field's value.
Provide a value for a field that wasn't included when you created the cardholder.
Remove certain details by passing null as a field's value.

patch

https://api.checkout.com/issuing/cardholders/{cardholderId}


1{
2  "first_name": "Hannah",
3  "middle_name": null,
4  "last_name": "Bret",
5  "date_of_birth": "1985-05-15",
6  "phone_number": {
7    "country_code": "+1",
8    "number": "113 496 0872"
9  },
10  "email": "[email protected]",
11  "billing_address": {
12    "address_line1": "123 High St.",
13    "address_line2": "Flat 456",
14    "city": "London",
15    "state": "London",
16    "zip": "SW1A 1AA",
17    "country": "GB"
18  },
19  "residency_address": {
20    "address_line1": "123 High St.",
21    "address_line2": "Flat 456",
22    "city": "London",
23    "state": "London",
24    "zip": "SW1A 1AA",
25    "country": "GB"
26  },
27  "document": {
28    "type": "national_identity_card",
29    "front_document_id": "file_6lbss42ezvoufcb2beo76rvwly",
30    "back_document_id": "file_aaz5pemp6326zbuvevp6qroqu4"
31  }
32}


1{
2"last_modified_date": "2019-09-10T10:11:12Z",
3"_links": {
4    "self": {
5        "href": "https://api.checkout.com/issuing/cardholders/crh_d3ozhf43pcq2xbldn2g45qnb44",
6        "actions": [ "GET"],
7        "types": ["application/json"]
8    }
9  }
10}

Create and manage cardholders

Note

Create a cardholder

Create a cardholder in the Dashboard

Create a cardholder using the API

Request example

Response example

Retrieve a cardholder using the API

Update a cardholder

Update a cardholder in the Dashboard

Update a cardholder using the API

Request example

Response example