Onerway
POST

Query account balance movements

Restricted
View as Markdown
Use this endpoint to page through account balance movements, which are the balance increase and decrease records created in Onerway Account by acquiring, payout, and related business activity. By default, the query returns records for the merchant account associated with the apikey. When a platform merchant queries on behalf of a sub-merchant, provide onBehalfOf to identify the sub-merchant account. The response includes records that match the currency, balance type, business type, and balance update time range filters.
Restricted access
Access to the Account service APIs is enabled by Onerway approval.

Request

apikeystringrequired
Account service API key request header assigned by Onerway. Use the value for the same environment as the request base URL.
Example:replace_with_account_service_apikey
x-timestampstringrequired
Request timestamp. The gateway uses it to identify replay attempts.
Example:1776931200
Constraints
Rule
The timestamp must be within 10 minutes of the server time. Both 10-digit seconds and 13-digit milliseconds are accepted.
requestIdstringrequired
Request ID used for idempotency control and request tracing.
Example:REQ-TRX-20260423-0001
onBehalfOfstringoptional
Sub-merchant number when a platform merchant queries on behalf of its sub-merchant. If omitted, the query uses the merchant account associated with the apikey. When provided, the caller merchant from apikey must be the parent merchant.
Example:replace_with_sub_merchant_no
currencystringoptional
Optional transaction currency filter. Use a three-letter ISO 4217 currency code.
Example:USD
balanceTypestringoptional
Optional balance type filter.
Allowed values
PAYMENT
Payment balance.
FUNDING
Funding balance.
PENDING_SETTLEMENT
Pending settlement balance.
acntTxnIdstringoptional
Optional exact-match filter for the account transaction ID. Numeric string is expected.
Example:replace_with_acnt_txn_id
beginTimestringrequired
Inclusive start of the query range, filtered by balanceUpdDate.
Example:2026-04-01T00:00:00+08:00
Constraints
Rule
Use an ISO-8601 timestamp with timezone offset, for example 2026-07-20T00:00:00+08:00.
endTimestringrequired
Inclusive end of the query range, filtered by balanceUpdDate.
Example:2026-04-30T23:59:59+08:00
Constraints
Consistency
endTime cannot be earlier than beginTime.
Range
31daysThe query time range cannot exceed 31 days.
businessTypestringoptional
Optional business type filter.
Allowed values
ACQUIRING
Acquiring business balance movement.
PAYOUT
Payout business balance movement.
currentnumberoptionaldefault1
Current page number. size is controlled by the server; use current to paginate.
Example:1

Request example

curl -X POST 'https://sandbox-api.onerway.com/account-server/api/v2/account/transactions/query' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "requestId": "REQ-TRX-20260423-0001",
  "currency": "USD",
  "beginTime": "2026-04-01T00:00:00+08:00",
  "endTime": "2026-04-23T23:59:59+08:00",
  "current": 1
}'

Response

respCodestring
Standardized response code. 20000 indicates a successful response.
respMsgstring
Human-readable response message aligned with respCode.
Paginated balance movement payload for the merchant account selected by apikey and optional onBehalfOf.
Standardized error object. It is null for successful responses and omitted from the JSON body.

Response example

{
  "respCode": "20000",
  "respMsg": "Success",
  "data": {
    "total": 50,
    "pages": 3,
    "current": 1,
    "list": [
      {
        "acntTxnId": 10001,
        "serviceId": 20001,
        "currency": "USD",
        "balanceType": "PAYMENT",
        "amount": "-100.00",
        "balanceUpdDate": "2026-04-20T10:30:00Z",
        "businessType": "PAYOUT",
        "externalOrderId": "replace_with_external_order_id",
        "remark": "Payout to bank account"
      },
      {
        "acntTxnId": 10002,
        "serviceId": 20002,
        "currency": "USD",
        "balanceType": "PAYMENT",
        "amount": "500.00",
        "balanceUpdDate": "2026-04-19T08:15:00Z",
        "businessType": "ACQUIRING",
        "externalOrderId": "replace_with_external_order_id",
        "remark": "Payment received"
      }
    ]
  }
}
No error responses are documented for this endpoint.

Get Global Account details

Retrieve Global Account details by Global Account ID or account number.

Query account transactions by transaction order number

Query account balance movement records associated with one or more transaction order numbers.