4. Balance

GET /api/v1/balance

Request

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 body is empty.

Query

Parameter	Type	Required	Description
shop_code	string	No	Shop code. If omitted, balance uses the merchant's default active shop.
currency	string	No	ISO currency code. Use BDT for this GEO.

Example request

GET /api/v1/balance?shop_code=your_bdt_shop&currency=BDT

Response

Response fields

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

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 active processing states.
buckets	Full bucket map: available, pending, frozen, credit.
pending_breakdown	Breakdown of pending exposure. Currently includes payout_reserved.

Example response

Success

{
  "currency": "BDT",
  "shop": {
    "id": 42,
    "code": "your_bdt_shop"
  },
  "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"
  }
}

Error

{
  "message": "Default shop is not configured for this merchant",
  "code": "validation_error",
  "error": {
    "code": "validation_error",
    "message": "Default shop is not configured for this merchant"
  }
}