/account/balance Account Balance Query API

Background

Queries the account balance, account state, and currency of the merchant corresponding to X-Merchant-Id. This endpoint is rate-limited to 60 QPS by default.

Endpoint

Item	Value
Method	GET
Path	/account/balance
Content-Type	application/json
Purpose	Query the current merchant's account balance

Access Requirements

• Common Authentication

Request Fields

Field	Location	Type	Required	Description
X-Merchant-Id	Header	string	Yes	Merchant number assigned by Adopay, 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 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 merchant key version.

This endpoint has no query parameters or request body. Compute Digest over an empty byte string.

Request Example

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

Response Fields

The endpoint uses the standard status, msg, and data response structure.

Field	Type	Returned	Description
status	int	Yes	Response code
msg	string	Yes	Response message corresponding to status.
data	object	On success	Current merchant account balance; it may be omitted when signature validation or protocol parsing fails.
data.merchantNo	string	Yes	Merchant number that the account belongs to, up to 64 characters.
data.balance	decimal(25,2)	Yes	Total balance in the currency's major unit; balance = usableBalance + frozenBalance + presettleBalance.
data.usableBalance	decimal(25,2)	Yes	Usable balance in the currency's major unit.
data.frozenBalance	decimal(25,2)	Yes	Frozen balance in the currency's major unit.
data.presettleBalance	decimal(25,2)	Yes	Balance pending settlement in the currency's major unit.
data.accountState	string	Yes	Account state. See the enum below.
data.currency	string	Yes	ISO 4217 three-letter account 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": {
    "merchantNo": "2492265300",
    "balance": 1929.35,
    "usableBalance": 1500.35,
    "frozenBalance": 100.00,
    "presettleBalance": 329.00,
    "accountState": "a",
    "currency": "BRL"
  }
}

Response headers include X-Merchant-Id, X-Timestamp, X-Nonce, Digest, and Authorization. Verify the response signature with the platform public key as described in Response Signing.

Response Error Codes

• Response Status