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

接口背景

合作商使用 X-Merchant-Id 携带一级商户号。subMerchantNo 为可选参数，接口统一以列表形式返回结果：

• 传入 subMerchantNo 时，仅返回该二级商户的账户信息，列表中只包含一条记录，分页参数不生效。
• 不传 subMerchantNo 时，为一级商户分页查询名下全部二级商户的账户余额；返回列表中同样包含一级商户自身的账户余额，每条记录通过商户号 merchantNo 区分归属。

该接口 qps 默认限流 60。

接口请求地址

项目	内容
请求方式	GET
请求路径	/account/balance-partner
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 为合作商密钥版本号。
subMerchantNo	Query	string	否	要查询的二级商户号，最长 64 个字符，且必须归属于 X-Merchant-Id 对应的合作商；不传时为一级商户分页查询名下全部二级商户（含一级商户自身）的账户余额。
limit	Query	int	否	每页记录数，最小 1，最大 100，默认 10；传入 subMerchantNo 时不生效。
id	Query	string	否	分页游标所在位置的商户号，最长 64 个字符；传入 subMerchantNo 时不生效。
direction	Query	string	否	分页方向：next（下一页）或 previous（上一页），默认 next；传入 subMerchantNo 时不生效。

本接口无请求体。签名串中的 (request-target) 必须包含实际发送的原始 Query 字符串；Digest 仍对空字节串计算。

分页行为

• 基于游标的分页在底层数据集发生变化时，比基于 offset 的分页更高效、更一致。
• 首次请求： 省略 id 和 direction 参数。
• 下一页： 使用响应中 data.next 字段提供的完整 URL。
• 上一页： 使用响应中 data.previous 字段提供的完整 URL。
• 传入 subMerchantNo 查询单个二级商户时，返回结果不分页，游标字段为 null。

请求示例

示例 1：分页查询名下二级商户余额（含一级商户自身，获取第一页）

GET /account/balance-partner?limit=10 HTTP/1.1
Host: api.example.com
X-Merchant-Id: 92315566000120
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>"

示例 2：查询指定二级商户余额

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

示例 3：跳转到下一页

GET /account/balance-partner?limit=10&id=24922653000123&direction=next HTTP/1.1
Host: api.example.com
X-Merchant-Id: 92315566000120
X-Timestamp: 1787011200
X-Nonce: c7d1e0f28a6b9c0d2e3f4a5b6c7d8e9f
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 响应结构。账户余额列表与分页游标位于 data 中。

分页字段

字段名	类型	是否必返	说明
status	int	是	响应码
msg	string	是	与 status 对应
data	object	成功必返	分页结果；请求在验签或协议解析阶段失败时可能不返回。
data.next	string	是	下一页结果的完整 URL；无更多页时为 null，最大长度 512 个字符。
data.previous	string	是	上一页结果的完整 URL；位于首页时为 null，最大长度 512 个字符。
data.results	array	是	账户余额列表。
data.results[].merchantNo	string	是	该条记录所属的商户号，最长 64 个字符；不传 subMerchantNo 查询时，列表包含一级商户自身的商户号及其名下各二级商户的商户号。
data.results[].balance	decimal(25,2)	是	总余额，单位为币种主单位；balance = usableBalance + frozenBalance + presettleBalance。
data.results[].usableBalance	decimal(25,2)	是	可用余额，单位为币种主单位。
data.results[].frozenBalance	decimal(25,2)	是	冻结金额，单位为币种主单位。
data.results[].presettleBalance	decimal(25,2)	是	待结算金额，单位为币种主单位。
data.results[].accountState	string	是	账户状态，取值见下方枚举。
data.results[].currency	string	是	账户币种，使用 ISO 4217 三字母币种代码，例如 BRL。

accountState 枚举

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

响应示例

{
  "status": 200,
  "msg": "sucesso",
  "data": {
    "next": "https://api.adopay.com.br/account/balance-partner?id=24922653000123&direction=next&limit=10",
    "previous": null,
    "results": [
      {
        "merchantNo": "92315566000120",
        "balance": 1929.35,
        "usableBalance": 1500.35,
        "frozenBalance": 100.00,
        "presettleBalance": 329.00,
        "accountState": "a",
        "currency": "BRL"
      },
      {
        "merchantNo": "24922653000123",
        "balance": 852.10,
        "usableBalance": 652.10,
        "frozenBalance": 50.00,
        "presettleBalance": 150.00,
        "accountState": "fi",
        "currency": "BRL"
      }
    ]
  }
}

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

响应错误码

• 响应状态