Common & Transaction API

Common query APIs (regions, cities, mobile area codes) and transaction record query API.

Region List

Get the list of supported regions (countries).

Item	Details
Endpoint	`POST /api/v1/merchant/common/regionList`

No request body required, only the X-ONERWAY-APIKEY header.

Response Parameters

Field	Type	Description
`data[]`	Array	Region list
`data[].regionCode`	String	Region/country code, ISO 3166-1 alpha-2
`data[].regionName`	String	Region/country name

Response Example

{
  "respCode": "20000",
  "respMsg": "success",
  "data": [
    { "regionCode": "CN", "regionName": "China" },
    { "regionCode": "US", "regionName": "United States" },
    { "regionCode": "HK", "regionName": "Hong Kong" }
  ]
}

City List

Query cities under a specified region.

Item	Details
Endpoint	`POST /api/v1/merchant/common/cityList`

Request Parameters

Field	Type	Required	Description
`merchantNo`	Long	✅	Merchant number
`regionCode`	String(2)	✅	Region/country code
`parentCode`	String	—	Parent administrative division code for cascading queries

Response Parameters

Field	Type	Description
`data[]`	Array	City list
`data[].regionCode`	String	Parent region code
`data[].parentCode`	String	Parent administrative division code
`data[].cityCode`	String	City code
`data[].cityName`	String	City name

Response Example

{
  "respCode": "20000",
  "respMsg": "success",
  "data": [
    {
      "regionCode": "CN",
      "parentCode": "GD",
      "cityCode": "SZ",
      "cityName": "Shenzhen"
    },
    {
      "regionCode": "CN",
      "parentCode": "GD",
      "cityCode": "GZ",
      "cityName": "Guangzhou"
    }
  ]
}

Mobile Area Code List

Get the list of supported mobile area codes.

Item	Details
Endpoint	`POST /api/v1/merchant/common/mobileAreaCodeList`

No request body required, only the X-ONERWAY-APIKEY header.

Response Parameters

Field	Type	Description
`data[]`	Array	Area code list
`data[].regionCode`	String	Region/country code
`data[].regionName`	String	Region/country name
`data[].areaCode`	String	Mobile area code, e.g. `+86`

Response Example

{
  "respCode": "20000",
  "respMsg": "success",
  "data": [
    { "regionCode": "CN", "regionName": "China", "areaCode": "+86" },
    { "regionCode": "US", "regionName": "United States", "areaCode": "+1" },
    { "regionCode": "HK", "regionName": "Hong Kong", "areaCode": "+852" }
  ]
}

Query Transaction Records

Paginated query of merchant transaction push records, filterable by transaction type, status, and time range.

Item	Details
Endpoint	`POST /api/v1/merchant/queryTxnList`

Request Parameters

Field	Type	Required	Description
`merchantNo`	Long	✅	Merchant number
`txnType`	String(20)	—	Transaction type: `AUTHORIZATION` / `REVERSAL` / `CLEARING` / `REFUND` / `VERIFICATION`
`txnStatus`	String(20)	—	Push status: `S` Success / `F` Failed / `P` Processing
`startTime`	Long	—	Query start time, timestamp in milliseconds
`endTime`	Long	—	Query end time, timestamp in milliseconds
`pageNum`	Integer	✅	Page number, minimum 1
`pageSize`	Integer	✅	Page size, range 1–100

Response Parameters

Field	Type	Description
`data.total`	Long	Total records
`data.pages`	Long	Total pages
`data.list[]`	Array	Transaction record list
`list[].txnType`	String	Transaction type
`list[].txnStatus`	String	Push status
`list[].txnOrderNo`	String	Transaction order number
`list[].originTxnOrderNo`	String	Original transaction order number
`list[].cardNo`	String	Card number (masked)
`list[].transactionAmount`	BigDecimal	Transaction amount
`list[].transactionCurrency`	String	Transaction currency
`list[].transactionTime`	Long	Transaction time (timestamp, milliseconds)
`list[].cardAmount`	BigDecimal	Card amount
`list[].cardCurrency`	String	Card currency
`list[].settleAmount`	BigDecimal	Settlement amount
`list[].settleCurrency`	String	Settlement currency
`list[].transactionFee`	BigDecimal	Transaction fee
`list[].crossBorderFee`	BigDecimal	Cross-border fee
`list[].exchangeFee`	BigDecimal	Exchange fee
`list[].merchantName`	String	Merchant name
`list[].merchantCountryCode`	String	Merchant country code
`list[].merchantMccCode`	String	Merchant MCC code
`list[].sendStatus`	String	Push status: `S` Success / `F` Failed / `P` Processing
`list[].sendTimes`	Integer	Push attempts

The full transaction record also includes authorizationCode, authMessageDesc, settleTime, fee currency fields, and merchant address details. See the response example for all fields.

Response Example

{
  "respCode": "20000",
  "respMsg": "success",
  "data": {
    "total": 1,
    "pages": 1,
    "pageNum": 1,
    "pageSize": 10,
    "list": [
      {
        "txnType": "CHARGE",
        "txnStatus": "S",
        "txnOrderNo": "TXN20260101001",
        "originTxnOrderNo": null,
        "originTxnOrderNoForRefund": null,
        "cardNo": "411111******1111",
        "authTime": 1735689600000,
        "authorizationCode": "AUTH001",
        "authMessageDesc": "Approved",
        "transactionAmount": 50.00,
        "transactionCurrency": "USD",
        "transactionTime": 1735689600000,
        "cardAmount": 50.00,
        "cardCurrency": "USD",
        "settleAmount": 50.00,
        "settleCurrency": "USD",
        "settleTime": 1735776000000,
        "transactionFee": 0.50,
        "transactionFeeCurrency": "USD",
        "crossBorderFee": null,
        "crossBorderFeeCurrency": null,
        "exchangeFee": null,
        "exchangeFeeCurrency": null,
        "merchantId": "MCH001",
        "merchantName": "Amazon",
        "merchantCountry": "United States",
        "merchantCountryCode": "US",
        "merchantStateProvince": "WA",
        "merchantCity": "Seattle",
        "merchantPostalCode": "98101",
        "merchantMccCode": "5411",
        "sendStatus": "S",
        "sendTimes": 1
      }
    ]
  }
}

Cardholder API

Cardholder management APIs including creation, update, and query operations.

Webhooks

Card operation and transaction event webhook notifications with signature verification.