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.

Base URL: POST /api/v2.1/fincard/virtual/...

---

Country/Region List

Returns all supported countries and regions with ISO codes.

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

Example Response

{
  "success": true,
  "code": 200,
  "msg": "Success",
  "data": [
    { "code": "AU", "standardCode": "AUS", "name": "Australia" },
    { "code": "BD", "standardCode": "BGD", "name": "Bangladesh" }
  ]
}

This data changes very infrequently. Cache it locally to minimize API calls.

---

City List

Returns cities filtered by country/region code.

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

Example Response

{
  "success": true,
  "code": 200,
  "msg": "Success",
  "data": [
    { "code": "AU_01", "name": "test", "country": "AU" }
  ]
}

---

City List v2 (Hierarchical)

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

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)

Example Response

{
  "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": []
        }
      ]
    }
  ]
}

---

Mobile Code List

Returns mobile area codes by region.

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

Example Response

{
  "success": true,
  "code": 200,
  "msg": "Success",
  "data": [
    { "code": "+1", "name": "Canada", "areaCode": "CA", "language": "en_US", "enableGlobalTransfer": true }
  ]
}

---

Upload File

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

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

Example Response

{
  "success": true,
  "code": 200,
  "msg": "Success",
  "data": {
    "fileId": "c7bf3c1b-25d1-4b75-b519-1e6bf383d0a7"
  }
}

Use the returned fileId when creating cardholders (B2C model requires ID document uploads).

---

Submit Work Order

Submit a work order for card activation or support requests.

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

Example Response

{
  "merchantOrderNo": "13243897979979797999008085",
  "orderNo": "WORK-2025080719534",
  "title": "ApplePay",
  "target": "5533700042831234",
  "content": "Active",
  "tradeType": "CARD_ACTIVE",
  "tradeStatus": "processing",
  "remark": null,
  "createTime": 1754607865000,
  "updateTime": 1754648044000
}

---

Work Order List

Query work orders with optional filters and pagination.

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.