Cardholder

Create Cardholder

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

Endpoint

POST {{baseUrl}}/issuing/api/:version/cardholder

Description

Creates a new cardholder record within the issuing platform. This API captures the personal details, contact information, and billing/delivery addresses of the customer. The created cardholder profile is then linked to future card issuance requests, ensuring proper identity, delivery, and billing setup.

Request Path Parameters

Parameter	Type	Required	Description
version	string	Yes	API version number

Request Headers

Parameter	Type	Required	Description
x-api-key	string	Yes	Shared X-API key
x-product-id	string	Yes	Shared ProductID
x-agent-code	string	Yes	Shared Agent Code
x-subagent-code	string	Yes	Shared Sub-Agent Code
x-client-id	string	Yes	Client Identification
x-client-name	string	Yes	Name of the Client
x-request-id	string	Yes	Idempotency key for request tracking
Content-Type	string	Yes	Must be `application/json`

Request Body Parameters

Parameter	Type	Required	Description
title	string	Yes	Cardholder title (e.g., "Mr", "Ms")
firstName	string	Yes	First name of the cardholder
middleName	string	No	Middle name of the cardholder
lastName	string	Yes	Last name of the cardholder
preferredName	string	Yes	Display/preferred name for the card
gender	string	Yes	Gender of the cardholder ("M", "F", "O")
dateOfBirth	string	Yes	Date of birth (format: YYYY-MM-DD)
mobileCountryCode	string	Yes	Mobile country code (e.g., "91" for India)
mobile	string	Yes	Mobile number without country code
nationality	string	Yes	ISO country code of nationality (e.g., "IN")
email	string	Yes	Email address of the cardholder
deliveryAddress1	string	Yes	Primary delivery address line
deliveryAddress2	string	Yes	Secondary delivery address line
deliveryCity	string	Yes	Delivery city
deliveryState	string	Yes	Delivery state/province
deliveryCountry	string	Yes	Delivery country (ISO code, e.g., "SG")
deliveryZipCode	string	Yes	Delivery postal/zip code
billingAddress1	string	Yes	Primary billing address line
billingAddress2	string	Yes	Secondary billing address line
billingCity	string	Yes	Billing city
billingState	string	Yes	Billing state/province
billingCountry	string	Yes	Billing country (ISO code, e.g., "SG")
billingZipCode	string	Yes	Billing postal/zip code

Request Example

cURL

curl --location --request POST \
--url '{{baseUrl}}/issuing/api/:version/cardholder' \
--header 'x-api-key: {{Shared X-API key}}' \
--header 'x-product-id: {{Shared ProductID}}' \
--header 'x-agent-code: {{Shared Agent Code}}' \
--header 'x-subagent-code: {{Shared Sub-Agent Code}}' \
--header 'x-client-id: {{ClientID}}' \
--header 'x-client-name: {{ClientName}}' \
--header 'x-request-id: {{IdempotencyKey}}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "title": "Mr",
  "firstName": "S",
  "middleName": "",
  "lastName": "Sharma",
  "preferredName": "S Sharma",
  "gender": "M",
  "dateOfBirth": "1998-08-11",
  "mobileCountryCode": "62",
  "mobile": "8234567896",
  "nationality": "IN",
  "email": "sandeep.test@yopmail.com",
  "deliveryAddress1": "Mani Casadona",
  "deliveryAddress2": "Action Area",
  "deliveryCity": "Kolkata",
  "deliveryState": "West Bengal",
  "deliveryCountry": "SG",
  "deliveryZipCode": "12SDF5",
  "billingAddress1": "Park Street",
  "billingAddress2": "Chowk Homes",
  "billingCity": "Malda",
  "billingState": "Punjab",
  "billingCountry": "SG",
  "billingZipCode": "144003"
}'

Response Example

200: Success
400: Error

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

{
  "code": 400,
  "message": "Error Message",
  "status": "error"
}

Get Cardholder Details

This API is used to retrieve the cardholder details.

Endpoint

GET {{baseUrl}}/issuing/api/:version/cardholder

Description

Retrieves detailed information of a cardholder using the unique cardholderHash-id. This API provides cardholder profile data such as personal details, contact info, and address information.

Request Path Parameters

Parameter	Type	Required	Description
version	string	Yes	API version number

Request Headers

Parameter	Type	Required	Description
x-api-key	string	Yes	Shared X-API key
x-product-id	string	Yes	Shared ProductID
x-cardholderHash-id	string	Yes	Unique identifier of the cardholder
x-client-id	string	Yes	Client identification
x-client-name	string	Yes	Name of the client
x-request-id	string	Yes	Idempotency key for request tracking
Content-Type	string	Yes	Must be `application/json`

Request Example

cURL

curl --location --request GET \
--url '{{baseUrl}}/issuing/api/:version/cardholder' \
--header 'x-api-key: {{Shared X-API key}}' \
--header 'x-product-id: {{Shared ProductID}}' \
--header 'x-cardholderHash-id: {{CardholderID}}' \
--header 'x-client-id: {{ClientID}}' \
--header 'x-client-name: {{ClientName}}' \
--header 'x-request-id: {{IdempotencyKey}}' \
--header 'Content-Type: application/json' \

Response Example

200: Success
400: Error

{
  "status": "success",
  "message": "Cardholder details retrieved successfully",
  "code": 200,
  "data": [
    {
      "lastName": "Sharma",
      "gender": "M",
      "title": "Mr",
      "createAt": "2025-09-22 11:25:47",
      "billingAddress2": "Chowk Homes",
      "billingAddress1": "Park Street",
      "deliveryZipCode": "12SDF5",
      "billingCountry": "SG",
      "id": "cardholder-id",
      "preferredName": "S Sharma",
      "email": "sandeep.test@yopmail.com",
      "deliveryCity": "Kolkata",
      "mobileCountryCode": "65",
      "mobile": "123123123",
      "deliveryAddress2": "Action Area",
      "billingZipCode": "144003",
      "dateOfBirth": "1998-08-11",
      "billingState": "Punjab",
      "deliveryAddress1": "Mani Casadona",
      "firstName": "S",
      "nationality": "IN",
      "deliveryState": "West Bengal",
      "deliveryCountry": "SG",
      "middleName": "",
      "billingCity": "Malda",
      "status": "ACTIVE"
    }
  ]
}

{
  "code": 400,
  "message": "Error Message",
  "status": "error"
}

Get Cardholder List

This API allows you to retrieve a list of existing cardholders from the system.

Endpoint

GET {{baseUrl}}/issuing/api/:version/cardholder/list

Description

This API allows you fetch a paginated list of cardholders with optional filters. It supports pagination (page, size) and optional date range filters (from_date, to_date) to narrow down results. The response contains cardholder details along with metadata for navigation across pages.

Request Path Parameters

Parameter	Type	Required	Description
version	string	Yes	API version number

Request Headers

Parameter	Type	Required	Description
x-api-key	string	Yes	Shared X-API key
x-product-id	string	Yes	Shared ProductID
x-agent-code	string	Yes	Shared Agent Code
x-subagent-code	string	Yes	Shared Sub-Agent Code
x-client-id	string	Yes	Client identification
x-client-name	string	Yes	Name of the client
x-request-id	string	Yes	Idempotency key for request tracking
Content-Type	string	Yes	Must be `application/json`

Request Query Parameters

Parameter	Type	Required	Description
from_date	string	No	Start date filter (format: YYYY-MM-DD)
to_date	string	No	End date filter (format: YYYY-MM-DD)
page	integer	Yes	Page number for pagination (default: 1)
size	integer	Yes	Number of records per page (default: 20)

Request Example

cURL

curl --location --request GET \
--url '{{baseUrl}}/issuing/api/:version/cardholder/list?from_date=&to_date=&page=1&size=20' \
--header 'x-api-key: {{Shared X-API key}}' \
--header 'x-product-id: {{Shared ProductID}}' \
--header 'x-agent-code: {{Shared Agent Code}}' \
--header 'x-subagent-code: {{Shared Sub-Agent Code}}' \
--header 'x-client-id: {{ClientID}}' \
--header 'x-client-name: {{ClientName}}' \
--header 'x-request-id: {{IdempotencyKey}}' \
--header 'Content-Type: Application/json' 

Response Example

200: Success
400: Error

{
  "status": "success",
  "message": "Cardholder details retrieved successfully",
  "code": 200,
  "data": [
    {
      "cardHolders": [
        {
          "id": "cardholder-id",
          "firstName": "John Das",
          "middleName": "",
          "lastName": "Verma",
          "preferredName": "John Das Verma",
          "title": "Mr",
          "gender": "M",
          "dateOfBirth": "1995-03-13",
          "email": "johnsmith14@yopmail.com",
          "mobileCountryCode": "65",
          "mobile": "1000110011",
          "nationality": "IN",
          "deliveryAddress1": "19 C, South City",
          "deliveryAddress2": "Chowk Homes",
          "deliveryCity": "Malda",
          "deliveryState": "Punjab",
          "deliveryCountry": "SG",
          "deliveryZipCode": "258220",
          "billingAddress1": "19 C, Silver Residency Apartment",
          "billingAddress2": "Chowk Homes",
          "billingCity": "Malda",
          "billingState": "Punjab",
          "billingCountry": "SG",
          "billingZipCode": "144003",
          "status": "ACTIVE",
          "createAt": "2025-09-11 06:24:50",
          "kycStatus": null
        },
        {
          "id": "cardholder-id",
          "firstName": "Khushbu",
          "middleName": "Kailash",
          "lastName": "Mandal",
          "preferredName": "Khushbu Kailash Mandal",
          "title": "Miss",
          "gender": "F",
          "dateOfBirth": "1985-09-04",
          "email": "check122@yopmail.com",
          "mobileCountryCode": "62",
          "mobile": "9112347654",
          "nationality": "IN",
          "deliveryAddress1": "Mani",
          "deliveryAddress2": "Casadona",
          "deliveryCity": "Kolkata",
          "deliveryState": "West Bengal",
          "deliveryCountry": "ID",
          "deliveryZipCode": "700156",
          "billingAddress1": "Mani",
          "billingAddress2": "Casadona",
          "billingCity": "Kolkata",
          "billingState": "West Bengal",
          "billingCountry": "ID",
          "billingZipCode": "700156",
          "status": "ACTIVE",
          "createAt": "2025-09-04 05:42:21",
          "kycStatus": "COMPLETED"
        }
      ],
      "totalCount": 2
    }
  ]
}

{
  "code": 400,
  "message": "Error Message",
  "status": "error"
}

Activate Cardholder

This API is used to reactivate / enable a previously deactivated cardholder profile in the system.

Endpoint

POST {{baseUrl}}/issuing/api/:version/cardholder/activate

Description

This API allows you to activate a registered cardholder whose profile was previously temporarily or permanently deactivated. Once activated, the cardholder regains full access to wallet and card functionalities.

Request Path Parameters

Parameter	Type	Required	Description
version	string	Yes	API version number

Request Headers

Parameter	Type	Required	Description
x-api-key	string	Yes	Shared X-API key
x-product-id	string	Yes	Shared ProductID
x-cardholder-id	string	Yes	Unique identifier of the cardholder
x-client-id	string	Yes	Client Identification
x-client-name	string	Yes	Name of the Client
x-request-id	string	Yes	Idempotency key for request tracking
Content-Type	string	Yes	Must be `application/json`

Request Example

cURL

curl --location --request POST \
--url '{{baseUrl}}/issuing/api/:version/cardholder/activate' \
--header 'x-api-key: {{Shared X-API key}}' \
--header 'x-product-id: {{Shared ProductID}}' \
--header 'x-cardholder-id: {{CardholderID}}' \
--header 'x-client-id: {{ClientID}}' \
--header 'x-client-name: {{ClientName}}' \
--header 'x-request-id: {{IdempotencyKey}}' \
--header 'Content-Type: application/json' \

Response Example

200: Success
400: Error

{
  "status": "success",
  "message": "CardHolder activated successfully!",
  "code": 200,
  "data": [
    "ACTIVE"
  ]
}

{
  "code": 400,
  "message": "Error Message",
  "status": "error"
}

Deactivate Cardholder

This API is used to deactivates a cardholder profile from the system.

Endpoint

DELETE {{baseUrl}}/issuing/api/:version/cardholder

Description

This API allows you to deactivate a registered cardholder. The deactivation can be temporary or permanent depending on the value passed in the status field.

Request Path Parameters

Parameter	Type	Required	Description
version	string	Yes	API version number

Request Headers

Parameter	Type	Required	Description
x-api-key	string	Yes	Shared X-API key
x-product-id	string	Yes	Shared ProductID
x-cardholder-id	string	Yes	Unique identifier of the cardholder
x-client-id	string	Yes	Client Identification
x-client-name	string	Yes	Name of the Client
x-request-id	string	Yes	Idempotency key for request tracking
Content-Type	string	Yes	Must be `application/json`

Request Body Parameters

Parameter	Type	Required	Description
status	string	Yes	Allowed values: `Temporary Deactivate` or `Permanent Deactivate`
reason	string	Yes	Reason for deactivation

Request Example

cURL

curl --location --request DELETE \
--url '{{baseUrl}}/issuing/api/:version/cardholder' \
--header 'x-api-key: {{Shared X-API key}}' \
--header 'x-product-id: {{Shared ProductID}}' \
--header 'x-cardholder-id: {{CardholderID}}' \
--header 'x-client-id: {{ClientID}}' \
--header 'x-client-name: {{ClientName}}' \
--header 'x-request-id: {{IdempotencyKey}}' \
--header 'Content-Type: application/json' \
--data '{
  "status": "Temporary Deactivate",
  "reason": ""
}'

Response Example

200: Success
400: Error

{
  "status": "success",
  "message": "CardHolder deactivated successfully!",
  "code": 200,
  "data": [
    "Temporary Deactivate"
  ]
}

{
  "code": 400,
  "message": "Error Message",
  "status": "error"
}

Create Cardholder​

Description

Request Path Parameters

Request Headers

Request Body Parameters

Request Example

Response Example

Get Cardholder Details​

Description

Request Path Parameters

Request Headers

Request Example

Response Example

Get Cardholder List​

Description

Request Path Parameters

Request Headers

Request Query Parameters

Request Example

Response Example

Activate Cardholder​

Description

Request Path Parameters

Request Headers

Request Example

Response Example

Deactivate Cardholder​

Description

Request Path Parameters

Request Headers

Request Body Parameters

Request Example

Response Example

Create Cardholder

Get Cardholder Details

Get Cardholder List

Activate Cardholder

Deactivate Cardholder