> ## Documentation Index
> Fetch the complete documentation index at: https://docs.finhub.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Common

> Reference data, file uploads, and work order management

# Common APIs

Reference data endpoints for countries, cities, mobile codes, plus file upload and work order management.

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

***

## Country/Region List

Returns all supported countries and regions with ISO codes.

```bash theme={null}
POST /api/v2.1/fincard/virtual/common/region
```

**Request:** `{}` (empty body)

**Response `data[]`:**

| Field          | Type   | Description                     |
| -------------- | ------ | ------------------------------- |
| `code`         | String | ISO 3166-1 alpha-2 (e.g. `US`)  |
| `standardCode` | String | ISO 3166-1 alpha-3 (e.g. `USA`) |
| `name`         | String | Country/region name             |

<Accordion title="Example Response">
  ```json theme={null}
  {
    "success": true,
    "code": 200,
    "msg": "Success",
    "data": [
      { "code": "AU", "standardCode": "AUS", "name": "Australia" },
      { "code": "BD", "standardCode": "BGD", "name": "Bangladesh" }
    ]
  }
  ```
</Accordion>

<Warning>
  This data changes very infrequently. **Cache it locally** to minimize API calls.
</Warning>

***

## City List

Returns cities filtered by country/region code.

```bash theme={null}
POST /api/v2.1/fincard/virtual/common/city
```

**Request:**

| Field        | Type   | Required | Description               |
| ------------ | ------ | -------- | ------------------------- |
| `regionCode` | String | No       | ISO 3166-1 alpha-2 filter |

**Response `data[]`:**

| Field     | Type   | Description        |
| --------- | ------ | ------------------ |
| `code`    | String | City code          |
| `name`    | String | City name          |
| `country` | String | ISO 3166-1 alpha-2 |

<Accordion title="Example Response">
  ```json theme={null}
  {
    "success": true,
    "code": 200,
    "msg": "Success",
    "data": [
      { "code": "AU_01", "name": "test", "country": "AU" }
    ]
  }
  ```
</Accordion>

***

## City List v2 (Hierarchical)

Returns cities with province/state/city hierarchy (two levels).

```bash theme={null}
POST /api/v2.1/fincard/virtual/common/v2/city
```

**Request:** Same as City List

**Response `data[]`:**

| Field                 | Type   | Description                               |
| --------------------- | ------ | ----------------------------------------- |
| `code`                | String | Province/state code                       |
| `name`                | String | Province/state name                       |
| `country`             | String | ISO 3166-1 alpha-2                        |
| `countryStandardCode` | String | ISO 3166-1 alpha-3                        |
| `parentCode`          | String | Parent code (`"0"` for root)              |
| `children[]`          | Array  | Child cities (same structure recursively) |

<Accordion title="Example Response">
  ```json theme={null}
  {
    "success": true,
    "code": 200,
    "msg": "Success",
    "data": [
      {
        "code": "AU-ACT",
        "name": "Australian Capital Territory",
        "parentCode": "0",
        "country": "AU",
        "countryStandardCode": "AUS",
        "children": [
          {
            "code": "AU-ACT-80100",
            "name": "Australian Capital Territory (Canberra)",
            "parentCode": "AU-ACT",
            "country": "AU",
            "countryStandardCode": "AUS",
            "children": []
          }
        ]
      }
    ]
  }
  ```
</Accordion>

***

## Mobile Code List

Returns mobile area codes by region.

```bash theme={null}
POST /api/v2.1/fincard/virtual/common/mobileAreaCode
```

**Request:** `{}` (empty body)

**Response `data[]`:**

| Field                  | Type    | Description                    |
| ---------------------- | ------- | ------------------------------ |
| `code`                 | String  | Mobile code (e.g. `+1`)        |
| `name`                 | String  | Region name (e.g. `Canada`)    |
| `areaCode`             | String  | ISO 3166-1 alpha-2 (e.g. `CA`) |
| `language`             | String  | `zh_CN` or `en_US`             |
| `enableGlobalTransfer` | Boolean | Is global transfer available   |

<Accordion title="Example Response">
  ```json theme={null}
  {
    "success": true,
    "code": 200,
    "msg": "Success",
    "data": [
      { "code": "+1", "name": "Canada", "areaCode": "CA", "language": "en_US", "enableGlobalTransfer": true }
    ]
  }
  ```
</Accordion>

***

## Upload File

Upload a file for use in cardholder KYC or work orders. Supports **jpg, png, pdf** formats, max **2MB**.

```bash theme={null}
POST /api/v2.1/fincard/virtual/common/file/upload
Content-Type: multipart/form-data
```

**Request (multipart):**

| Field      | Type   | Required | Description          |
| ---------- | ------ | -------- | -------------------- |
| `category` | String | Yes      | Use `card`           |
| `file`     | File   | Yes      | jpg/png/pdf, max 2MB |

**Response `data`:**

| Field    | Type   | Description                          |
| -------- | ------ | ------------------------------------ |
| `fileId` | String | UUID reference for the uploaded file |

<Accordion title="Example Response">
  ```json theme={null}
  {
    "success": true,
    "code": 200,
    "msg": "Success",
    "data": {
      "fileId": "c7bf3c1b-25d1-4b75-b519-1e6bf383d0a7"
    }
  }
  ```
</Accordion>

<Note>
  Use the returned `fileId` when creating cardholders (B2C model requires ID document uploads).
</Note>

***

## Submit Work Order

Submit a work order for card activation or support requests.

```bash theme={null}
POST /api/v2.1/fincard/virtual/work/submit
```

**Request:**

| Field             | Type          | Required | Description                                           |
| ----------------- | ------------- | -------- | ----------------------------------------------------- |
| `merchantOrderNo` | String        | Yes      | Client transaction ID. Length `[20..40]`              |
| `title`           | String        | Yes      | Title. Length `[1..255]`                              |
| `target`          | String        | Yes      | Target. Length `[1..255]`. Card number for activation |
| `content`         | String        | No       | Content. Length `[0..1000]`                           |
| `files`           | List\<String> | No       | File IDs from upload endpoint                         |
| `tradeType`       | String        | Yes      | `CARD_ACTIVE` or `OTHER`                              |

**Response `data`:**

| Field             | Type   | Description                                        |
| ----------------- | ------ | -------------------------------------------------- |
| `merchantOrderNo` | String | Client transaction ID                              |
| `orderNo`         | String | Platform transaction ID                            |
| `title`           | String | Title                                              |
| `target`          | String | Target                                             |
| `content`         | String | Content                                            |
| `tradeType`       | String | `CARD_ACTIVE` / `OTHER`                            |
| `tradeStatus`     | String | `wait_process` / `processing` / `success` / `fail` |
| `remark`          | String | Remark                                             |
| `createTime`      | Long   | Millisecond timestamp                              |
| `updateTime`      | Long   | Millisecond timestamp                              |

<Accordion title="Example Response">
  ```json theme={null}
  {
    "merchantOrderNo": "13243897979979797999008085",
    "orderNo": "WORK-2025080719534",
    "title": "ApplePay",
    "target": "5533700042831234",
    "content": "Active",
    "tradeType": "CARD_ACTIVE",
    "tradeStatus": "processing",
    "remark": null,
    "createTime": 1754607865000,
    "updateTime": 1754648044000
  }
  ```
</Accordion>

***

## Work Order List

Query work orders with optional filters and pagination.

```bash theme={null}
POST /api/v2.1/fincard/virtual/work/list
```

**Request:** All fields optional (used as filters):

| Field             | Type   | Required | Description                                        |
| ----------------- | ------ | -------- | -------------------------------------------------- |
| `merchantOrderNo` | String | No       | Filter by client tx ID                             |
| `orderNo`         | String | No       | Filter by platform tx ID                           |
| `target`          | String | No       | Filter by target                                   |
| `tradeType`       | String | No       | `CARD_ACTIVE` / `OTHER`                            |
| `tradeStatus`     | String | No       | `wait_process` / `processing` / `success` / `fail` |

**Response `data`:** `{ total: Long, records: [...] }` — records have same shape as Submit response plus `description`.