/account/balance 账户余额查询接口

接口背景

查询 X-Merchant-Id 对应商户的账户余额、账户状态和币种。 该接口 qps 默认限流 60。

接口请求地址

项目	内容
请求方式	GET
请求路径	/account/balance
Content-Type	application/json
接口用途	查询当前商户的账户余额

接口接入规范

• common接入规范

接口请求字段

字段名	位置	类型	是否必填	说明
X-Merchant-Id	Header	string	是	Adopay 分配的商户号，最长 64 个字符。
X-Timestamp	Header	int	是	Unix 秒级请求时间戳，用于请求时效校验。
X-Nonce	Header	string	是	请求防重放随机字符串；同一商户在有效期内不得重复。
Digest	Header	string	是	GET 请求无报文体时使用空字节串计算摘要，格式为 SHA-256=<Base64摘要>。
Authorization	Header	string	是	ES256 请求签名信息，其中 keyId 为商户密钥版本号。

本接口无 Query 参数和请求体。计算 Digest 时使用空字节串。

请求示例

GET /account/balance HTTP/1.1
Host: api.example.com
X-Merchant-Id: 2492265300
X-Timestamp: 1787011200
X-Nonce: a9f3c1d47e8b9a2c4d1f9e8a7b6c5d4e
Digest: SHA-256=47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=
Authorization: Signature keyId="v1",alg="ES256",headers="(request-target) x-timestamp x-nonce digest",signature="<BASE64_SIGNATURE>"

接口响应字段

接口使用统一的 status、msg、data 响应结构。

字段名	类型	是否必返	说明
status	int	是	响应码
msg	string	是	与 status 对应
data	object	成功必返	当前商户的账户余额；请求在验签或协议解析阶段失败时可能不返回。
data.merchantNo	string	是	当前账户所属的商户号，最长 64 个字符。
data.balance	decimal(25,2)	是	总余额，单位为币种主单位；balance = usableBalance + frozenBalance + presettleBalance。
data.usableBalance	decimal(25,2)	是	可用余额，单位为币种主单位。
data.frozenBalance	decimal(25,2)	是	冻结金额，单位为币种主单位。
data.presettleBalance	decimal(25,2)	是	待结算金额，单位为币种主单位。
data.accountState	string	是	账户状态，取值见下方枚举。
data.currency	string	是	账户币种，使用 ISO 4217 三字母币种代码，例如 BRL。

accountState 枚举

枚举值	状态说明
na	未激活。
a	活跃。
fi	禁止收款。
fo	禁止付款。
f	冻结，即禁止收款且禁止付款。
c	已注销。

响应示例

{
  "status": 200,
  "msg": "sucesso",
  "data": {
    "merchantNo": "2492265300",
    "balance": 1929.35,
    "usableBalance": 1500.35,
    "frozenBalance": 100.00,
    "presettleBalance": 329.00,
    "accountState": "a",
    "currency": "BRL"
  }
}

响应头包含 X-Merchant-Id、X-Timestamp、X-Nonce、Digest 和 Authorization。调用方应使用平台公钥校验响应签名，具体规则见 请求签名的响应签名章节。

响应错误码

• 响应状态