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.

ItemDetails
EndpointPOST /api/v1/merchant/cardholder/createCardholder

Request Parameters

FieldTypeRequiredDescription

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

FieldTypeDescription
respCodeStringResponse code
respMsgStringResponse message
dataObjectCardholder info
data.cardholderIdLongCardholder ID
data.firstNameStringFirst name
data.lastNameStringLast name
data.emailStringEmail
data.mobileStringMobile number
data.mobileAreaCodeStringMobile area code
data.birthdayStringDate of birth
data.nationalityStringNationality
data.addressRegionCodeStringAddress country code
data.addressStateCodeStringState/province code
data.addressCityCodeStringCity code
data.addressDetailLine1StringAddress line 1
data.addressDetailLine2StringAddress line 2
data.addressPostalCodeStringPostal code
data.remarkStringRemark

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.

ItemDetails
EndpointPOST /api/v1/merchant/cardholder/updateCardholder

Request Parameters

FieldTypeRequiredDescription

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.

ItemDetails
EndpointPOST /api/v1/merchant/cardholder/queryCardholder

Request Parameters

FieldTypeRequiredDescription

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

FieldTypeDescription
respCodeStringResponse code
respMsgStringResponse message
dataObjectPaginated data
data.totalRecordsLongTotal records
data.pageSizeLongPage size
data.currentLongCurrent page (synonym of pageNum)
data.pageNumLongCurrent page number
data.totalPagesLongTotal pages
data.records[]ArrayCardholder 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.