List Balance History

Retrieve a paginated list of balance change records for the merchant's account. Each record captures a single credit or debit event, including the change amount, the resulting balance snapshot, and the transaction timestamp. Useful for reconciliation and auditing.
Request Parameters
limitinteger
Number of records to return per page. Range: 1–100. Default: 20.
cursorstring
Pagination cursor token returned by a previous call. Pass this to fetch the next or previous page. Omit for the first page.
currencystring
Filter by currency. ISO 4217 three-letter code (e.g., USD, EUR). If omitted, all currencies are returned. See Data Types.
fromTransactAtdatetime
Start of the transaction time range. ISO 8601 extended format (e.g., 2026-04-01T00:00:00+08:00). See Data Types.
toTransactAtdatetime
End of the transaction time range. ISO 8601 extended format. Maximum range: 3 months from fromTransactAt. See Data Types.
Response Parameters
resultResult
API call result. See Result.
nextCursorstring
Cursor token for the next page. null when the current page is the last page.
prevCursorstring
Cursor token for the previous page. null when the current page is the first page.
itemsarray
List of balance change records, sorted by transactedAt in descending order. Maximum 100 elements per page.
Show child parametersShow child parameters
Error Codes
resultCoderesultStatusresultMessageTroubleshooting
SUCCESSSSuccessN/A
PARAM_ILLEGALFIllegal parametersCheck the request parameters. For example, non-numeric input, invalid date.
INVALID_CURSORFThe cursor token is invalid or expiredThe `cursor` token is invalid or expired. Start a new query without `cursor`.
ACCOUNT_NOT_EXISTFAccount does not existThe merchant account (or the sub-merchant specified by the `account-id` header) does not exist. Verify the account identifier.
CONTRACT_CHECK_FAILFThe contract check has failedThe merchant contract does not cover balance history query. Contact support to verify the contract scope.
AUTHORIZATION_NOT_EXISTFThe authorization does not existNo valid authorization found for the target account. Complete the authorization flow first.
Definition
POST /api/open/v1/balances/listHistory
Request
{
"limit": 50,
"currency": "USD",
"fromTransactAt": "2026-04-01T00:00:00+08:00",
"toTransactAt": "2026-04-30T23:59:59+08:00"
}
Response
{
"result": {
  "resultStatus": "S",
  "resultCode": "SUCCESS",
  "resultMessage": "success"
},
"nextCursor": "eyJpZCI6Ijk4NzY1NDMyMTAiLCJ0cmFuc2FjdGVkQXQiOiIyMDI2LTA0L****",
"prevCursor": null,
"items": [
  {
    "id": "bc_20260425****",
    "changeAmount": {
      "value": 100000,
      "currency": "USD"
    },
    "balanceAmount": {
      "value": 500000,
      "currency": "USD"
    },
    "currency": "USD",
    "description": "Bank transfer deposit",
    "transactedAt": "2026-04-25T10:30:01+08:00"
  },
  {
    "id": "bc_20260424****",
    "changeAmount": {
      "value": -50000,
      "currency": "USD"
    },
    "balanceAmount": {
      "value": 400000,
      "currency": "USD"
    },
    "currency": "USD",
    "description": "Payout to beneficiary",
    "transactedAt": "2026-04-24T14:20:01+08:00"
  }
]
}