Skip to main content

​
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[]:
FieldTypeDescription
codeStringISO 3166-1 alpha-2 (e.g. US)
standardCodeStringISO 3166-1 alpha-3 (e.g. USA)
nameStringCountry/region name
{
  "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:
FieldTypeRequiredDescription
regionCodeStringNoISO 3166-1 alpha-2 filter
Response data[]:
FieldTypeDescription
codeStringCity code
nameStringCity name
countryStringISO 3166-1 alpha-2
{
  "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[]:
FieldTypeDescription
codeStringProvince/state code
nameStringProvince/state name
countryStringISO 3166-1 alpha-2
countryStandardCodeStringISO 3166-1 alpha-3
parentCodeStringParent code ("0" for root)
children[]ArrayChild cities (same structure recursively)
{
  "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[]:
FieldTypeDescription
codeStringMobile code (e.g. +1)
nameStringRegion name (e.g. Canada)
areaCodeStringISO 3166-1 alpha-2 (e.g. CA)
languageStringzh_CN or en_US
enableGlobalTransferBooleanIs global transfer available
{
  "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):
FieldTypeRequiredDescription
categoryStringYesUse card
fileFileYesjpg/png/pdf, max 2MB
Response data:
FieldTypeDescription
fileIdStringUUID reference for the uploaded file
{
  "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:
FieldTypeRequiredDescription
merchantOrderNoStringYesClient transaction ID. Length [20..40]
titleStringYesTitle. Length [1..255]
targetStringYesTarget. Length [1..255]. Card number for activation
contentStringNoContent. Length [0..1000]
filesList<String>NoFile IDs from upload endpoint
tradeTypeStringYesCARD_ACTIVE or OTHER
Response data:
FieldTypeDescription
merchantOrderNoStringClient transaction ID
orderNoStringPlatform transaction ID
titleStringTitle
targetStringTarget
contentStringContent
tradeTypeStringCARD_ACTIVE / OTHER
tradeStatusStringwait_process / processing / success / fail
remarkStringRemark
createTimeLongMillisecond timestamp
updateTimeLongMillisecond timestamp
{
  "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):
FieldTypeRequiredDescription
merchantOrderNoStringNoFilter by client tx ID
orderNoStringNoFilter by platform tx ID
targetStringNoFilter by target
tradeTypeStringNoCARD_ACTIVE / OTHER
tradeStatusStringNowait_process / processing / success / fail
Response data: { total: Long, records: [...] } — records have same shape as Submit response plus description.