URL: /paas/fincard-virtual/common

---
title: 'Common'
description: '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
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
{
  "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
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
{
  "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
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
{
  "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
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
{
  "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
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
{
  "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
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
{
  "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
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`.