Card Holder APIs
Manage KYC-verified cardholders. Required when card type has needCardHolder=true. Supports B2B (simplified) and B2C (full KYC with ID documents) models.
Base URL: POST /api/v2.1/fincard/virtual/card/holder/...
The cardHolderModel values B2B and B2C are internal codes — they do NOT correspond to company vs individual. Check the metadata.cardHolderModel field from the Card Types response.
Cardholder Occupations
List available occupation codes for B2C cardholder creation.
POST /api/v2.1/fincard/virtual/card/holder/occupations
{} (empty body)
Response data[]:
| Field | Type | Description |
|---|
occupationCode | String | Occupation code (e.g. 11-1011) |
description | String | Occupation description (e.g. Chief Executives) |
Create Cardholder V2
Create a new KYC-verified cardholder. Fields differ based on cardHolderModel.
POST /api/v2.1/fincard/virtual/card/holder/v2/create
B2B Model Request
| Field | Type | Required | Description |
|---|
cardHolderModel | String | Yes | B2B |
merchantOrderNo | String | Yes | Client tx ID [20..40] |
cardTypeId | Long | Yes | Card type ID |
areaCode | String | Yes | Mobile area code [2..5] (from supportHolderAreaCode) |
mobile | String | Yes | Mobile number [5..20] |
email | String | Yes | Email [5..50] (receives verification codes) |
firstName | String | Yes | First name (English only) [2..32] |
lastName | String | Yes | Last name (English only) [2..32] |
birthday | String | Yes | Date of birth yyyy-MM-dd |
country | String | Yes | Bill address country (ISO alpha-2, from supportHolderRegin) |
town | String | Yes | Bill address city code (from City List) |
address | String | Yes | Bill address [2..40] (letters, numbers, hyphens, spaces) |
postCode | String | Yes | Postal code [2..15] |
Total length of firstName + lastName cannot exceed 32 characters (including spaces).
B2C Model Request (additional fields)
All B2B fields plus:
| Field | Type | Required | Description |
|---|
nationality | String | Yes | ISO alpha-2 (from supportHolderRegin) |
gender | String | Yes | M (male) / F (female) |
occupation | String | Yes | Occupation code (from Occupations) |
annualSalary | String | Yes | e.g. 100000 USD |
accountPurpose | String | Yes | English only (e.g. Living Expense) |
expectedMonthlyVolume | String | Yes | e.g. 10000 USD |
idType | String | Yes | PASSPORT / HK_HKID / DLN / GOVERNMENT_ISSUED_ID_CARD |
idNumber | String | Yes | ID number [2..50] |
issueDate | String | Yes | ID issue date yyyy-MM-dd |
idNoExpiryDate | String | Yes | ID expiry date yyyy-MM-dd |
idFrontId | String | Yes | Front photo file ID (from Upload File) |
idBackId | String | Yes | Back photo file ID |
idHoldId | String | Yes | Selfie photo file ID |
ipAddress | String | Yes | IPv4 address |
ID Types by Region
| Region | Supported ID Types |
|---|
| Hong Kong | PASSPORT, HK_HKID |
| All other | PASSPORT, DLN, GOVERNMENT_ISSUED_ID_CARD |
Restricted Countries/Regions
Cuba, North Korea, Egypt, Iran, Myanmar, Nigeria, Russia, Belarus, South Africa, Syria, Ukraine, Venezuela, Sudan, South Sudan, Libya, Crimea, Burundi, Central African Republic, Somalia, Zimbabwe, Afghanistan.
Response data
| Field | Type | Description |
|---|
holderId | Long | Cardholder ID (use in create card) |
merchantOrderNo | String | Client tx ID |
cardTypeId | Long | Card type ID |
statusFlowLocation | String | admin (platform review) / channel (bank review) |
status | String | wait_audit / pass_audit / under_review / reject |
description | String | Status description |
Approval flow: admin review first → then channel (bank) review. Cardholder can only be used for card creation when status=pass_audit.
Update Cardholder V2
Update a rejected cardholder. Only allowed when statusFlowLocation=admin AND status=reject.
POST /api/v2.1/fincard/virtual/card/holder/v2/update
holderId (required). All fields are re-submitted.
Response: Same as Create response.
Cardholder information cannot be modified after bank submission. Email and ID number are globally unique per card type — duplicates are rejected.
Cardholder List
Query cardholders with pagination and filters.
POST /api/v2.1/fincard/virtual/card/holder/list
| Field | Type | Required | Description |
|---|
pageNum | Integer | Yes | Page number (default 1) |
pageSize | Integer | Yes | Page size (max 100, default 10) |
holderId | Long | No | Filter by holder ID |
areaCode | String | No | Filter by area code (requires mobile too) |
mobile | String | No | Filter by mobile |
email | String | No | Filter by email |
merchantOrderNo | String | No | Filter by client tx ID |
data: { total, records[] }
| Field | Type | Description |
|---|
holderId | String | Cardholder ID |
merchantOrderNo | String | Client tx ID |
cardTypeId | String | Card type ID |
areaCode | String | Mobile area code |
mobile | String | Mobile number |
email | String | Email |
firstName | String | First name |
lastName | String | Last name |
birthday | String | Date of birth |
country | String | Country |
town | String | City code |
address | String | Address |
postCode | String | Postal code |
statusFlowLocation | String | admin / channel |
status | String | wait_audit / pass_audit / under_review / reject |
description | String | Status description |
createTime | Long | Creation time (ms) |
updateTime | Long | Update time (ms) |
Deprecated Endpoints
The following V1 endpoints are still available but deprecated:
| Endpoint | Path | Replacement |
|---|
| Create V1 | /card/holder/create | Use /card/holder/v2/create |
| Update V1 | /card/holder/update | Use /card/holder/v2/update |
