Skip to main content

4. Balance

Get balance

GET /api/v1/balance

Returns the merchant's current shop-scoped balance snapshot and the amount on hold.

Shop routing: when using multiple shops, shop_code is optional. If shop_code is provided, the response is limited to that shop. If shop_code is omitted, the response uses the merchant's default active shop. If no default active shop is configured, the API returns 422.

Headers

Parameter	Type	Required	Description
X-API-Key	string	Yes	API key.
X-Timestamp	string	Yes	Request time.
X-Signature	string	Yes	HMAC-SHA256(secret, timestamp + body). For GET requests the body is empty.

Query parameters

Parameter	Type	Required	Description
shop_code	string	No	Shop code. If not provided, the balance is calculated for the merchant's default active shop.
currency	string	No	ISO currency code. Default — RUB.

Example

GET /api/v1/balance?shop_code=shop-001&currency=RUB

Response 200 (OK)

{
  "currency": "RUB",
  "shop": {
    "id": 42,
    "code": "shop-001"
  },
  "as_of": "2026-05-19T12:00:00+03:00",
  "balance": "98500.00",
  "available": "98500.00",
  "pending": "1500.00",
  "frozen": "0.00",
  "credit": "5000.00",
  "total": "105000.00",
  "on_hold": "1500.00",
  "buckets": {
    "available": "98500.00",
    "pending": "1500.00",
    "frozen": "0.00",
    "credit": "5000.00"
  },
  "pending_breakdown": {
    "payout_reserved": "1500.00"
  }
}

Field	Description
currency	Request currency.
shop	Selected shop id and code.
as_of	Snapshot time.
balance	Alias of `available` kept for the current `/api/v1/balance` path.
available	Spendable merchant funds in the selected shop.
pending	Reserved funds, including payout reserves.
frozen	Frozen funds unavailable for spending.
credit	Spendable credit bucket for payouts.
total	Sum of `available + pending + frozen + credit`.
on_hold	Amount on hold for payout transactions in raw statuses `pending`, `processing`, `processing_api`, or `waiting_api`.
buckets	Full bucket map: `available`, `pending`, `frozen`, `credit`.
pending_breakdown	Breakdown of pending exposure. Currently includes `payout_reserved`.

Monetary values are returned as decimal strings normalized by currency scale.

Get balance