Cardholder API

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
`merchantNo`	Long	✅	Merchant number
`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

Response Parameters

The response data object contains the full cardholder information:

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

Response Example

{
  "respCode": "20000",
  "respMsg": "success",
  "data": {
    "cardholderId": 300001,
    "firstName": "John",
    "lastName": "Doe",
    "email": "[email]",
    "mobile": "[phone_number]",
    "mobileAreaCode": "+86",
    "birthDay": "1990-01-01",
    "nationality": "CN",
    "addressRegionCode": "CN",
    "addressStateCode": "GD",
    "addressCityCode": "SZ",
    "addressDetailLine1": "[address]",
    "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
`merchantNo`	Long	✅	Merchant number
`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

Response Parameters

Same as Create Cardholder response parameters.

Response Example

{
  "respCode": "20000",
  "respMsg": "success",
  "data": {
    "cardholderId": 300001,
    "firstName": "John",
    "lastName": "Smith",
    "email": "[email]",
    "mobile": "[phone_number]",
    "mobileAreaCode": "+86",
    "birthDay": "1990-01-01",
    "nationality": "CN",
    "addressRegionCode": "CN",
    "addressStateCode": "GD",
    "addressCityCode": "GZ",
    "addressDetailLine1": "[address]",
    "addressDetailLine2": null,
    "addressPostalCode": "510000",
    "remark": null
  }
}

Get Cardholder Detail

Query cardholder details by cardholder ID.

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

Request Parameters

Field	Type	Required	Description
`merchantNo`	Long	✅	Merchant number
`cardholderId`	Long	✅	Cardholder ID

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
`merchantNo`	Long	—	Merchant number (overrides base merchantNo for cross-merchant queries)
`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

Response Parameters

Field	Type	Description
`data.records[]`	Array	Cardholder list, each item same as Create Cardholder response
`data.total`	Long	Total records
`data.current`	Long	Current page
`data.size`	Long	Page size

Response Example

{
  "respCode": "20000",
  "respMsg": "success",
  "data": {
    "records": [
      {
        "cardholderId": 300001,
        "firstName": "John",
        "lastName": "Doe",
        "email": "[email]",
        "mobile": "[phone_number]",
        "mobileAreaCode": "+86",
        "birthDay": "1990-01-01",
        "nationality": "CN",
        "addressRegionCode": "CN",
        "addressStateCode": "GD",
        "addressCityCode": "SZ",
        "addressDetailLine1": "[address]",
        "addressDetailLine2": null,
        "addressPostalCode": "518000",
        "remark": null
      }
    ],
    "total": 1,
    "current": 1,
    "size": 10
  }
}

Card Query API

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

Common & Transaction API

Common query APIs (regions, cities, mobile area codes) and transaction record query API.