Onerway
快速开始

接入准备

配置账户服务请求域名、apikey、x-timestamp 和出口 IP 白名单，开始调用账户余额、账户流水、账户账单与 Global Account 接口。
查看 Markdown

账户服务 API 使用独立请求域名和特定环境的 apikey 请求 Header。开始调用账户余额、账户流水、账户账单或 Global Account 接口前，请先确认目标环境、接口访问权限、apikey、x-timestamp 和出口 IP 白名单已经准备完成。

接入步骤

确认接口权限

账户服务接口为受限接口，需要 Onerway 为商户开通对应能力后才能访问。

  • 调用账户余额、账户流水和账户账单接口前，请确认账户服务 API 权限已开通。
  • 调用 Global Account 接口前，请确认 Global Account 开户、收款或资金转出能力已开通。
  • 如果平台商户需要代子商户查询，请确认父子商户关系和 onBehalfOf 使用权限已配置。

选择请求域名

请使用与 apikey 所属环境一致的账户服务请求域名。

环境Base URL
Productionhttps://api.onerway.com/account-server
Sandboxhttps://sandbox-api.onerway.com/account-server
沙盒与生产环境的凭据相互独立。接口路径以 /api/v2/... 或当前 Global Account 页面展示的 /api/v1/... 开头，Base URL、接口路径和 apikey 必须来自同一环境。

保存 apikey

账户服务通过 apikey 请求 Header 识别调用方权限。

Header必填说明
apikey是Onerway 分配的账户服务访问密钥。
请将 apikey 保存在服务端。不要把它暴露在前端页面、移动端应用、客户端 bundle、日志或公开代码仓库中。

设置 x-timestamp

账户余额、账户流水和账户账单接口需要同时提供 apikey 和 x-timestamp。网关使用 x-timestamp 判断请求是否在有效时间窗口内，降低请求被重放的风险。

Header必填说明
x-timestamp是请求时间戳；支持 10 位秒级或 13 位毫秒级，必须与服务端时间偏差在 10分钟以内。
Content-Type是（POST）application/json。

提供出口 IP

调用账户服务前，请向 Onerway 提供稳定的服务端出口 IP，用于配置账户服务访问白名单。

  • 仅提交稳定的服务端出口 IP。
  • 如果沙盒与生产环境使用不同出口 IP，请分别提供。
  • 如果出口 IP 发生变更，请在切换流量前更新白名单。

发起服务端请求

环境、apikey、x-timestamp 与 IP 白名单就绪后，从服务端调用接口，并在请求 Header 中传入对应字段。

curl https://sandbox-api.onerway.com/account-server/api/v2/account/balance/overview/query \
  -H 'Content-Type: application/json' \
  -H 'apikey: replace_with_account_service_apikey' \
  -H 'x-timestamp: 1776931200' \
  -d '{
    "requestId": "REQ-BAL-OV-20260423-0001",
    "displayCurrency": "USD"
  }'

接口地址

当前对外展示的账户服务接口地址如下。请以当前环境的 Base URL 拼接接口路径发起请求。

类别接口MethodPath
账户余额查询账户余额总览POST/api/v2/account/balance/overview/query
账户余额查询账户余额POST/api/v2/account/balance/query
账户交易查询账户流水POST/api/v2/account/transactions/query
账户交易按交易单号查询账户流水POST/api/v2/account/transactions/service/query
账户账单导出每日账户账单POST/api/v2/account/statement/daily/export
Global Account（全球收付账户）创建 Global AccountPOST/api/v1/account/global/create
Global Account（全球收付账户）查询 Global Account 详情POST/api/v1/account/global/getDetail

完整 Sandbox 示例：

  • https://sandbox-api.onerway.com/account-server/api/v2/account/balance/overview/query
  • https://sandbox-api.onerway.com/account-server/api/v2/account/balance/query
  • https://sandbox-api.onerway.com/account-server/api/v2/account/transactions/query
  • https://sandbox-api.onerway.com/account-server/api/v2/account/transactions/service/query
  • https://sandbox-api.onerway.com/account-server/api/v2/account/statement/daily/export
  • https://sandbox-api.onerway.com/account-server/api/v1/account/global/create
  • https://sandbox-api.onerway.com/account-server/api/v1/account/global/getDetail

幂等

账户余额、账户流水和账户账单接口支持幂等控制。在 10分钟内复用同一个 requestId 可以安全重试请求；命中重复时返回 10006 DUPLICATE_REQUEST 错误，错误类型为 idempotency_error。

下一步

概览

账户余额、账户流水、账户账单与 Global Account（全球收付账户）管理服务。

创建 Global Account

创建用于收单收款与资金转出场景的 Global Account（全球收付账户）。