URL: /paas/fincard-virtual/card-holders

---
title: 'Card Holders'
description: 'KYC cardholder creation, update, approval tracking, and listing'
---

# 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.

<Info>
  **Base URL:** `POST /api/v2.1/fincard/virtual/card/holder/...`
</Info>

<Warning>
  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](/paas/fincard-virtual/cards) response.
</Warning>

---

## Cardholder Occupations

List available occupation codes for B2C cardholder creation.

```bash
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`.

```bash
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](/paas/fincard-virtual/common)) |
| `address` | String | Yes | Bill address `[2..40]` (letters, numbers, hyphens, spaces) |
| `postCode` | String | Yes | Postal code `[2..15]` |

<Note>
  Total length of `firstName` + `lastName` cannot exceed 32 characters (including spaces).
</Note>

### 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](#cardholder-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](/paas/fincard-virtual/common)) |
| `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 |

<Note>
  Approval flow: **admin** review first → then **channel** (bank) review. Cardholder can only be used for card creation when `status=pass_audit`.
</Note>

---

## Update Cardholder V2

Update a rejected cardholder. Only allowed when `statusFlowLocation=admin` AND `status=reject`.

```bash
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.

<Warning>
  Cardholder information **cannot be modified after bank submission**. Email and ID number are **globally unique** per card type — duplicates are rejected.
</Warning>

---

## Cardholder List

Query cardholders with pagination and filters.

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