/account/balance-partner Account Balance Query API

Background

The partner sends the primary merchant number in X-Merchant-Id. subMerchantNo is an optional parameter, and the endpoint always returns results as a list:

• When subMerchantNo is provided, only the account information of that sub-merchant is returned; the list contains a single record, and the pagination parameters have no effect.
• When subMerchantNo is omitted, the endpoint queries, with pagination, the account balances of all sub-merchants under the primary merchant; the returned list also includes the primary merchant's own account balance, and each record is identified by the merchant number merchantNo.

The endpoint is rate-limited to 60 QPS by default.

Endpoint

Item	Value
Method	GET
Path	/account/balance-partner
Content-Type	application/json
Purpose	Query, with pagination, the account balances of the primary merchant and its sub-merchants, or query the account balance of a specified sub-merchant

Access Requirements

• Common Authentication

Request Fields

Field	Location	Type	Required	Description
X-Merchant-Id	Header	string	Yes	Primary merchant number assigned to the partner, up to 64 characters.
X-Timestamp	Header	int	Yes	Unix request timestamp in seconds, used to validate request freshness.
X-Nonce	Header	string	Yes	Anti-replay random value; it must not be reused by the same primary merchant during the validity window.
Digest	Header	string	Yes	For a GET request without a body, compute the digest over an empty byte string in the format SHA-256=<Base64 digest>.
Authorization	Header	string	Yes	ES256 request signature information; keyId identifies the partner key version.
subMerchantNo	Query	string	No	Sub-merchant number to query, up to 64 characters; it must belong to the partner identified by X-Merchant-Id. When omitted, the endpoint queries, with pagination, the account balances of all sub-merchants under the primary merchant (including the primary merchant itself).
limit	Query	int	No	Number of records per page; minimum 1, maximum 100, default 10. Has no effect when subMerchantNo is provided.
id	Query	string	No	Merchant number at the pagination cursor position, up to 64 characters. Has no effect when subMerchantNo is provided.
direction	Query	string	No	Pagination direction: next (next page) or previous (previous page), default next. Has no effect when subMerchantNo is provided.

This endpoint has no request body. The (request-target) line in the canonical string must include the raw query string exactly as sent; Digest is still computed over an empty byte string.

Pagination Behavior

• Cursor-based pagination is more efficient and more consistent than offset-based pagination when the underlying data set changes.
• First request: omit the id and direction parameters.
• Next page: use the full URL provided by the data.next field in the response.
• Previous page: use the full URL provided by the data.previous field in the response.
• When subMerchantNo is provided to query a single sub-merchant, the result is not paginated, and the cursor fields are null.

Request Example

Example 1: Query the balances of all sub-merchants with pagination (including the primary merchant itself, first page)

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>"

Example 2: Query the balance of a specified sub-merchant

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>"

Example 3: Jump to the next page

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>"

Response Fields

The endpoint uses the standard status, msg, and data response structure. The account balance list and the pagination cursors are located in data.

Pagination Fields

Field	Type	Always Returned	Description
status	int	Yes	Response code
msg	string	Yes	Corresponds to status
data	object	On success	Pagination result; it may be omitted when the request fails at the signature verification or protocol parsing stage.
data.next	string	Yes	Full URL of the next page; null when there are no more pages, maximum length 512 characters.
data.previous	string	Yes	Full URL of the previous page; null when on the first page, maximum length 512 characters.
data.results	array	Yes	List of account balances.
data.results[].merchantNo	string	Yes	Merchant number that the record belongs to, up to 64 characters. When queried without subMerchantNo, the list contains the primary merchant's own merchant number and the merchant numbers of all its sub-merchants.
data.results[].balance	decimal(25,2)	Yes	Total balance in the currency's major unit; balance = usableBalance + frozenBalance + presettleBalance.
data.results[].usableBalance	decimal(25,2)	Yes	Usable balance in the currency's major unit.
data.results[].frozenBalance	decimal(25,2)	Yes	Frozen balance in the currency's major unit.
data.results[].presettleBalance	decimal(25,2)	Yes	Balance pending settlement in the currency's major unit.
data.results[].accountState	string	Yes	Account state. See the enum below for values.
data.results[].currency	string	Yes	Account currency, using the ISO 4217 three-letter currency code, such as BRL.

accountState Enum

Value	Description
na	Not activated.
a	Active.
fi	Collections prohibited.
fo	Payouts prohibited.
f	Frozen; both collections and payouts are prohibited.
c	Closed.

Response Example

{
  "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"
      }
    ]
  }
}

Response headers include X-Merchant-Id, X-Timestamp, X-Nonce, Digest, and Authorization. Callers should verify the response signature with the platform public key; see Response and Webhook Verification for the detailed rules.

Response Error Codes

• Response Status