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

Request: {} (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

Request: Same fields as Create + 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

Request:

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

Response 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`

Connectors

PaaS Journey

PaaS Operations

FinCard Virtual

Card Holders

Card Holder APIs

Cardholder Occupations

Create Cardholder V2

B2B Model Request

B2C Model Request (additional fields)

ID Types by Region

Restricted Countries/Regions

Response `data`

Update Cardholder V2

Cardholder List

Deprecated Endpoints

​Card Holder APIs

​Cardholder Occupations

​Create Cardholder V2

​B2B Model Request

​B2C Model Request (additional fields)

​ID Types by Region

​Restricted Countries/Regions

​Response data

​Update Cardholder V2

​Cardholder List

​Deprecated Endpoints

Card Holder APIs

Cardholder Occupations

Create Cardholder V2

B2B Model Request

B2C Model Request (additional fields)

ID Types by Region

Restricted Countries/Regions

Response `data`

Update Cardholder V2

Cardholder List

Deprecated Endpoints