Skip to main content

Cardholder

A cardholder represents the person who will use a card. You must create a cardholder before issuing any card to them. Once a card is linked to a cardholder, the association cannot be changed.

Create Cardholder​

This API allows you to create a new cardholder profile in the system.

{{baseUrl}}/hashdt/issuing/api/v1/card/cardholder

Description

Cardholders are authorized representatives of your business and are associated with a named individual who represents your business. A cardholder can be associated with a card.
Creating a cardholder requires passing a name screening process, which involves submitting basic information about the cardholder.

Cardholders residing in restricted countries cannot be issued cards, and some nationalities require proof of address (POA). See Cardholder Region Restrictions before submitting.

Note: The sample request below includes both required and optional fields. Adjust the payload to match your use case, for example:

  • back_file is required only when identity.type is ID_CARD.
  • proof_of_address, proof_of_address_issue_date, and proof_of_address_issuing_country are required only when POA applies to the cardholder's nationality.
  • kyc_verification is required only if you use your own KYC provider.
  • country_code and address.line2 are optional.

📩 Request Headers

x-api-key string required

Shared X-API key

x-product-id string required

Shared Product ID

x-request-id string required

Idempotency key for request tracking

x-user-id string required

User identification key

agent-code string required

Shared Agent Code

subagent-code string required

Shared Sub Agent Code

Content-Type string required

Must be application/json

Authorization string required

Bearer access token

📦 Request Body

email string required

Email address of the cardholder.

gender string required

Cardholder's gender. Allowed value: MALE or FEMALE.

nationality string required

Cardholder's nationality (2-letter ISO 3166-1). Determines whether proof of address is required. See Cardholder Region Restrictions.

mobile_number string required

Cardholder's mobile number without country code.
💡 See Phone Number Validation Rules for country-specific length requirements.

country_code string

2-letter ISO 3166-1 country code for the individual's mobile number. If not provided, it defaults to the individual's country.

individual object required

Details about the cardholder.

date_of_birth string required

Date of birth (ISO 8601 date format: YYYY-MM-DD). Cardholders must be at least 18 and under 80 years old.

name object required

Full name of the Individual. Only characters in English are supported.

first_name string required

First name of cardholder.

last_name string required

Last name of cardholder.

address object required

Physical address of cardholder.

city string required

City of address.

country string required

Country code (2-letter ISO 3166-1) of address. Must be the cardholder’s actual country of residence. Residents of restricted countries are rejected at card issuance. See Cardholder Region Restrictions.

line1 string required

Address line 1

line2 string

Address line 2

state string required

Address state

postcode string required

Address postal code

identity object required

The cardholder's identity documents and supporting materials.

type string required

Identity document type. Allowed value: ID_CARD or PASSPORT.

number string required

Identity document number.

front_file string required

Base64 encoded front side image of the identity document. Maximum file size: 2 MB (2,097,152 bytes) after Base64 decoding.

back_file string conditional

Base64 encoded back side image of the identity document. Required when identity type is ID_CARD. Maximum file size: 2 MB (2,097,152 bytes) after Base64 decoding.

proof_of_address string conditional

Proof-of-address (POA) file, uploaded as Base64-encoded content. Required when the cardholder’s nationality is in the Red group, see Cardholder Region Restrictions. Supports PDF, PNG, JPG, and JPEG, up to 10 MB (10,485,760 bytes) after decoding.

proof_of_address_issue_date string conditional

Actual issue date of the POA document. Submission require a document issued within the last 12 months of submission. Date must be in ISO 8601 format: YYYY-MM-DD. Required when POA is applicable.

proof_of_address_issuing_country string conditional

2-letter ISO 3166-1 code of the country or region that issued the POA document. Required when POA is applicable.

kyc_verification object conditional

KYC verification information.

Note:

  • Required only if the client uses its own KYC provider for verification.
  • Not required if the platform's default KYC provider is used.
  • The user's KYC verification must be completed before submitting these details.

method string required

KYC verification method. Accepted value: THIRD_PARTY.

  • THIRD_PARTY - Cardholder has completed verification via a third-party provider and submits proof.

kyc_proof object required

Proof associated with the completed KYC verification.

provider string required

Name of the third party KYC provider used for verification. Accepted values: SUMSUB, MYINFO, JUMIO, DIDIT, SHUFTI, REGTANK.

reference_id string required

Unique reference ID returned by the third party KYC provider for the completed verification. Minimum length: 10 characters; maximum length: 64 characters.

type string required

Type of cardholder. Allowed value: INDIVIDUAL

created_by string required

Creator identifier

Request Example

curl --location --request POST \
--url '{{baseUrl}}/hashdt/issuing/api/v1/card/cardholder' \
--header 'x-api-key: {{Shared X-API key}}' \
--header 'x-product-id: {{Shared ProductID}}' \
--header 'x-request-id: {{IdempotencyKey}}' \
--header 'x-user-id: {{UserID}}' \
--header 'agent-code: {{Shared Agent Code}}' \
--header 'subagent-code: {{Shared Sub-Agent Code}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{AccessToken}}'
--data-raw '{
"email": "demo@yopmail.com",
"gender": "MALE",
"nationality": "SG",
"mobile_number": "92271434",
"country_code": "SG",
"individual": {
"date_of_birth": "1990-01-01",
"name": {
"first_name": "John",
"last_name": "Doe"
},
"address": {
"city": "Singapore",
"country": "SG",
"line1": "123 Bukit Timah Road",
"state": "Singapore",
"postcode": "229837"
}
},
"identity": {
"type": "PASSPORT",
"number": "E12345678",
"front_file": "base64-encode-string",
"back_file": "base64-encode-string",
"proof_of_address": "base64-encode-string",
"proof_of_address_issue_date": "2026-10-15",
"proof_of_address_issuing_country": "SG"
},
"kyc_verification": {
"method": "THIRD_PARTY",
"kyc_proof": {
"provider": "SUMSUB",
"reference_id": "SUMSUB-123456"
}
},
"type": "INDIVIDUAL",
"created_by": "Test User"
}'

Response Example

{
"status": "success",
"message": "Cardholder created successfully.",
"code": 201,
"data": [
{
"id": "cardholder-id"
}
]
}

Get All Cardholders​

{{baseUrl}}/hashdt/issuing/api/v1/card/cardholder

Description

This API returns a list of all cardholders, allowing you to view and manage cardholder details easily.

📩 Request Headers

x-api-key string required

Shared X-API key

x-product-id string required

Shared Product ID

x-request-id string required

Idempotency key for request tracking

x-user-id string required

User identification key

agent-code string required

Shared Agent Code

subagent-code string required

Shared Sub Agent Code

Content-Type string required

Must be application/json

Authorization string required

Bearer access token

🔍 Query Parameters

page_num integer

Page number for pagination. Defaults to 1.

page_size integer

Number of items per page. Defaults to 10.

Request Example

curl --location --request GET \
--url '{{baseUrl}}/hashdt/issuing/api/v1/card/cardholder' \
--header 'x-api-key: {{Shared X-API key}}' \
--header 'x-product-id: {{Shared ProductID}}' \
--header 'x-request-id: {{IdempotencyKey}}' \
--header 'x-user-id: {{UserID}}' \
--header 'agent-code: {{Shared Agent Code}}' \
--header 'subagent-code: {{Shared Sub-Agent Code}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{AccessToken}}'

Response Example

{
"status": "success",
"message": "Cardholder fetched successfully",
"code": 200,
"totalcount": 2,
"data": [
{
"id": "cardholder-id",
"email": "demo@yopmail.com",
"country_code": "SG",
"mobile_number": "92271434",
"kyc_status": null,
"status": "SUCCESS",
"type": "INDIVIDUAL",
"postal_address": {
"line1": "123 5th Avenue",
"line2": null,
"city": "New York",
"state": "NY",
"country": "SG",
"postcode": "10001"
},
"individual": {
"address": {
"line1": "123 5th Avenue",
"line2": null,
"city": "New York",
"state": "NY",
"country": "SG",
"postcode": "10001"
},
"date_of_birth": "1990-01-01",
"employers": null,
"name": {
"title": null,
"first_name": "John",
"middle_name": null,
"last_name": "Doe",
"name_on_card": null
}
},
"created_at": "2026-08-11 14:50:41",
"review_status": "SUCCESS"
},
{
"id": "cardholder-id",
"email": "sandeep.test@yopmail.com",
"country_code": "SG",
"mobile_number": "92271430",
"kyc_status": null,
"status": "SUCCESS",
"type": "INDIVIDUAL",
"postal_address": {
"line1": "5678 Oak Avenue",
"line2": null,
"city": "Los Angeles",
"state": "CA",
"country": "US",
"postcode": "94932"
},
"individual": {
"address": {
"line1": "5678 Oak Avenue",
"line2": null,
"city": "Los Angeles",
"state": "CA",
"country": "US",
"postcode": "94932"
},
"date_of_birth": "1998-08-11",
"employers": null,
"name": {
"title": null,
"first_name": "Sandeep",
"middle_name": null,
"last_name": "Sharma",
"name_on_card": null
}
},
"created_at": "2026-08-10 16:48:22",
"review_status": "SUCCESS"
}
]
}

Get Cardholder Details​

This API is used to retrieve the cardholder details.

{{baseUrl}}/hashdt/issuing/api/v1/card/cardholder

Description

This API is used to retrieve the details of a specific cardholder. You must provide the Cardholder ID or email ID as a query parameter to identify the cardholder.

📩 Request Headers

x-api-key string required

Shared X-API key

x-product-id string required

Shared Product ID

x-request-id string required

Idempotency key for request tracking

x-user-id string required

User identification key

agent-code string required

Shared Agent Code

subagent-code string required

Shared Sub Agent Code

Content-Type string required

Must be application/json

Authorization string required

Bearer access token

🔍 Query Parameters

id string

Unique identifier for cardholder

email string

Unique identifier for cardholder

Request Example

curl --location --request GET \
--url '{{baseUrl}}/hashdt/issuing/api/v1/card/cardholder?id={{CardholderID}}' \
--header 'x-api-key: {{Shared X-API key}}' \
--header 'x-product-id: {{Shared ProductID}}' \
--header 'x-request-id: {{IdempotencyKey}}' \
--header 'x-user-id: {{UserID}}' \
--header 'agent-code: {{Shared Agent Code}}' \
--header 'subagent-code: {{Shared Sub-Agent Code}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{AccessToken}}'

Response Example

{
"status": "success",
"message": "Cardholder fetched successfully",
"code": 200,
"data": [
{
"id": "cardholder-id",
"email": "demo@yopmail.com",
"country_code": "SG",
"mobile_number": "92271434",
"kyc_status": null,
"status": "SUCCESS",
"type": "INDIVIDUAL",
"postal_address": {
"line1": "123 5th Avenue",
"line2": null,
"city": "New York",
"state": "NY",
"country": "SG",
"postcode": "10001"
},
"individual": {
"address": {
"line1": "123 5th Avenue",
"line2": null,
"city": "New York",
"state": "NY",
"country": "SG",
"postcode": "10001"
},
"date_of_birth": "1990-01-01",
"employers": null,
"name": {
"title": null,
"first_name": "John",
"middle_name": null,
"last_name": "Doe",
"name_on_card": null
}
},
"created_at": "2026-08-11 14:48:02",
"review_status": "SUCCESS"
}
]
}

Update Cardholder​

This API allows you to update a cardholder profile in the system.

{{baseUrl}}/hashdt/issuing/api/v1/card/cardholder

Description

This endpoint updates cardholder information, including physical address, postal address, and contact details. All fields are optional, and only the fields provided will be updated. For composite objects, such as name, all child fields must be provided and valid when the object is included.

💡 mobile_number and country_code must be provided together. Updating either field individually is not supported.

📩 Request Headers

x-api-key string required

Shared X-API key

x-product-id string required

Shared Product ID

x-request-id string required

Idempotency key for request tracking

x-user-id string required

User identification key

Content-Type string required

Must be application/json

Authorization string required

Bearer access token

📦 Request Body

mobile_number string

Cardholder's mobile number without country code.
💡 See Phone Number Validation Rules for country-specific length requirements.

country_code string

2-letter ISO 3166-1 country code for the individual's mobile number.

individual object

Details about the cardholder.

address object required

Physical address of cardholder

city string required

City of address

country string required

Country code (2-letter ISO 3166-1) of address

line1 string required

Address line 1

line2 string

Address line 2

state string required

Address state

postcode string required

Address postal code

updated_by string required

User updating the details

🔍 Query Parameters

id string required

Unique identifier for cardholder

Request Example

curl --location --request PATCH \
--url '{{baseUrl}}/hashdt/issuing/api/v1/card/cardholder?id={{CardholderID}}' \
--header 'x-api-key: {{Shared X-API key}}' \
--header 'x-product-id: {{Shared ProductID}}' \
--header 'x-request-id: {{IdempotencyKey}}' \
--header 'x-user-id: {{UserID}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{AccessToken}}'
--data '{
"individual": {
"address": {
"city": "Austin",
"country": "US",
"line1": "1234 Elm Street",
"state": "TX",
"postcode": "94932"
}
},
"updated_by": "user"
}'

Response Example

{
"status": "success",
"message": "Cardholder updated successfully.",
"code": 200
}