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.

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

Example Response

json

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

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

Example Response

json

{
  "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).

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)

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

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

Example Response

json

{
  "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.

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

Example Response

json

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

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

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
}

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.