Get Ledger Balances

Retrieve authoritative ledger account balances for the merchant. This is the source of truth for all balance calculations.

GEThttps://api.zenpayz.com/merchant/api/v1/ledger/balances

Bearer · API key

Request

Headers

Header	Description
Authorization REQUIRED	Bearer {api_key}
X-Signature REQUIRED	HMAC-SHA256 signature
X-Timestamp REQUIRED	ISO 8601 timestamp
X-Secret-Salt REQUIRED	Secret salt for HMAC validation

Query Parameters

Parameter	Type	Description
currency OPTIONAL	string-	Filter by currency code (e.g., INR, USD)

Response

Success (200 OK)

{
  "success": true,
  "data": [
    {
      "accountCategory": "MERCHANT_AVAILABLE",
      "currency": "INR",
      "balance": 10000
    },
    {
      "accountCategory": "MERCHANT_PENDING",
      "currency": "INR",
      "balance": 2500
    },
    {
      "accountCategory": "MERCHANT_BLOCKED",
      "currency": "INR",
      "balance": 500
    },
    {
      "accountCategory": "MERCHANT_AVAILABLE",
      "currency": "USD",
      "balance": 250
    }
  ],
  "message": "Ledger balances retrieved successfully"
}

Account Categories

Category	Description
MERCHANT_AVAILABLE	Funds available for withdrawal/payout
MERCHANT_PENDING	Funds being processed (incoming payments not yet settled)
MERCHANT_BLOCKED	Funds blocked for pending operations (payouts, settlements)
RESERVE_PAYOUT	Reserved funds for pending payout operations
RESERVE_RISK	Risk reserve allocation based on merchant risk profile
RESERVE_CHARGEBACK	Funds reserved for potential chargebacks

Examples

cURL

curl -X GET "https://api.zenpays.com/merchant/api/v1/ledger/balances?currency=INR" \
  -H "Authorization: Bearer zp_test_xxxxx" \
  -H "X-Timestamp: 2024-01-15T10:30:00.000Z" \
  -H "X-Signature: a1b2c3d4e5f6..." \
  -H "X-Secret-Salt: your_secret_salt"

SDK

const balances = await zenpays.ledger.getBalances({ currency: 'INR' });

balances.forEach(balance => {
  console.log(`${balance.accountCategory}: ${balance.balance} ${balance.currency}`);
});

// Get available balance
const available = balances.find(b => b.accountCategory === 'MERCHANT_AVAILABLE');
console.log(`Available for withdrawal: ${available?.balance || 0}`);