Cardholders

Cardholder management APIs including creation, update, and query operations.

Create Cardholder

Create a cardholder under the merchant. First name, last name, and email are required.

Item	Details
Endpoint	`POST /api/v1/merchant/cardholder/createCardholder`

Request Parameters

Field	Type	Required	Description
`clientRequestId`	String(64)	✅	Idempotent request ID
`firstName`	String(50)	✅	Cardholder first name
`lastName`	String(20)	✅	Cardholder last name
`email`	String(100)	✅	Email address, must be valid format
`mobile`	String(20)	—	Mobile number
`mobileAreaCode`	String(10)	—	Mobile area code, e.g. `+86`
`birthday`	String(20)	—	Date of birth, e.g. `1990-01-01`
`nationality`	String(2)	—	Nationality, ISO 3166-1 alpha-2 code
`addressRegionCode`	String(2)	—	Address country code
`addressStateCode`	String(50)	—	Address state/province code
`addressCityCode`	String(50)	—	Address city code
`addressDetailLine1`	String(200)	—	Address line 1
`addressDetailLine2`	String(200)	—	Address line 2
`addressPostalCode`	String(20)	—	Postal code
`remark`	String(200)	—	Remark

Request Example

{
  "clientRequestId": "REQ_20260101_001",
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@example.com",
  "mobile": "13800138000",
  "mobileAreaCode": "+86",
  "birthday": "1990-01-01",
  "nationality": "CN",
  "addressRegionCode": "CN",
  "addressStateCode": "GD",
  "addressCityCode": "SZ",
  "addressDetailLine1": "No.1 Test Road",
  "addressPostalCode": "518000"
}

Response Parameters

Field	Type	Description
`respCode`	String	Response code
`respMsg`	String	Response message
`data`	Object	Cardholder info
`data.cardholderId`	Long	Cardholder ID
`data.firstName`	String	First name
`data.lastName`	String	Last name
`data.email`	String	Email
`data.mobile`	String	Mobile number
`data.mobileAreaCode`	String	Mobile area code
`data.birthday`	String	Date of birth
`data.nationality`	String	Nationality
`data.addressRegionCode`	String	Address country code
`data.addressStateCode`	String	State/province code
`data.addressCityCode`	String	City code
`data.addressDetailLine1`	String	Address line 1
`data.addressDetailLine2`	String	Address line 2
`data.addressPostalCode`	String	Postal code
`data.remark`	String	Remark

Response Example

{
  "respCode": "20000",
  "respMsg": "success",
  "data": {
    "cardholderId": 300001,
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "mobile": "13800138000",
    "mobileAreaCode": "+86",
    "birthday": "1990-01-01",
    "nationality": "CN",
    "addressRegionCode": "CN",
    "addressStateCode": "GD",
    "addressCityCode": "SZ",
    "addressDetailLine1": "No.1 Test Road",
    "addressDetailLine2": null,
    "addressPostalCode": "518000",
    "remark": null
  }
}

Update Cardholder

Update an existing cardholder's information.

Item	Details
Endpoint	`POST /api/v1/merchant/cardholder/updateCardholder`

Request Parameters

Field	Type	Required	Description
`cardholderId`	Long	✅	Cardholder ID
`firstName`	String(50)	✅	First name
`lastName`	String(20)	✅	Last name
`email`	String(100)	✅	Email address
`mobile`	String(20)	—	Mobile number
`mobileAreaCode`	String(10)	—	Mobile area code
`birthday`	String(20)	—	Date of birth
`nationality`	String(2)	—	Nationality
`addressCountryCode`	String(2)	—	Address country code
`addressStateCode`	String(50)	—	State/province code
`addressCityCode`	String(50)	—	City code
`addressDetailLine1`	String(200)	—	Address line 1
`addressDetailLine2`	String(200)	—	Address line 2
`addressPostalCode`	String(20)	—	Postal code
`remark`	String(200)	—	Remark

Request Example

{
  "cardholderId": 300001,
  "firstName": "John",
  "lastName": "Smith",
  "email": "john.smith@example.com",
  "mobile": "13800138000",
  "mobileAreaCode": "+86",
  "birthday": "1990-01-01",
  "nationality": "CN",
  "addressCountryCode": "CN",
  "addressStateCode": "GD",
  "addressCityCode": "GZ",
  "addressDetailLine1": "No.2 Test Road",
  "addressPostalCode": "510000"
}

Response Parameters

Same as Create Cardholder response parameters.

Query Cardholders

Paginated query of cardholders under the merchant, filterable by cardholder ID or idempotent request ID.

Item	Details
Endpoint	`POST /api/v1/merchant/cardholder/queryCardholder`

Request Parameters

Field	Type	Required	Description
`cardholderId`	Long	—	Cardholder ID, queries all if omitted
`clientRequestId`	String(64)	—	Idempotent request ID for filtering
`pageNum`	Integer	✅	Page number, minimum 1
`pageSize`	Integer	✅	Page size, range 1–100

Request Example

{
  "pageNum": 1,
  "pageSize": 10
}

Response Parameters

Field	Type	Description
`respCode`	String	Response code
`respMsg`	String	Response message
`data`	Object	Paginated data
`data.totalRecords`	Long	Total records
`data.pageSize`	Long	Page size
`data.current`	Long	Current page (synonym of pageNum)
`data.pageNum`	Long	Current page number
`data.totalPages`	Long	Total pages
`data.records[]`	Array	Cardholder list for current page, each item same as Create Cardholder response

Response Example

{
  "respCode": "20000",
  "respMsg": "success",
  "data": {
    "totalRecords": 1,
    "pageSize": 10,
    "current": 1,
    "pageNum": 1,
    "totalPages": 1,
    "records": [
      {
        "cardholderId": 300001,
        "firstName": "John",
        "lastName": "Doe",
        "email": "john.doe@example.com",
        "mobile": "13800138000",
        "mobileAreaCode": "+86",
        "birthday": "1990-01-01",
        "nationality": "CN",
        "addressRegionCode": "CN",
        "addressStateCode": "GD",
        "addressCityCode": "SZ",
        "addressDetailLine1": "No.1 Test Road",
        "addressDetailLine2": null,
        "addressPostalCode": "518000",
        "remark": null
      }
    ]
  }
}

Queries

Card query APIs including operation records, basic info, balance, and sensitive information.

Common

Common query APIs including region list, city list, and mobile area codes.