Get Ledger Reserves

Retrieve reserve allocations for the merchant. Reserves are funds set aside for payouts, risk mitigation, and potential chargebacks.

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

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
reserveType OPTIONAL	string-	Filter by reserve type (PAYOUT_RESERVE, RISK_RESERVE, CHARGEBACK_RESERVE)
status OPTIONAL	string-	Filter by status (ACTIVE, PARTIALLY_RELEASED, FULLY_RELEASED, FORFEITED)

Response

Success (200 OK)

{
  "success": true,
  "data": {
    "reserves": [
      {
        "reserveId": "rsv_abc123",
        "merchantId": "mer_xyz789",
        "walletId": "wal_def456",
        "reserveType": "PAYOUT_RESERVE",
        "reserveReason": "Pending payout batch processing",
        "originalAmount": 50000,
        "currentAmount": 50000,
        "releasedAmount": 0,
        "currency": "INR",
        "status": "ACTIVE",
        "reservedAt": "2024-01-15T10:00:00.000Z",
        "releaseScheduledAt": "2024-01-16T10:00:00.000Z",
        "releasedAt": null,
        "releasePeriodDays": 1,
        "reservePercentage": null,
        "sourceTransactionId": "payout_batch_001",
        "createdBy": "system",
        "releasedBy": null,
        "releaseNotes": null
      },
      {
        "reserveId": "rsv_def456",
        "merchantId": "mer_xyz789",
        "walletId": "wal_def456",
        "reserveType": "RISK_RESERVE",
        "reserveReason": "Monthly rolling risk reserve",
        "originalAmount": 25000,
        "currentAmount": 20000,
        "releasedAmount": 5000,
        "currency": "INR",
        "status": "PARTIALLY_RELEASED",
        "reservedAt": "2024-01-01T00:00:00.000Z",
        "releaseScheduledAt": "2024-02-01T00:00:00.000Z",
        "releasedAt": null,
        "releasePeriodDays": 30,
        "reservePercentage": 5.0,
        "sourceTransactionId": null,
        "createdBy": "risk_engine",
        "releasedBy": null,
        "releaseNotes": null
      },
      {
        "reserveId": "rsv_ghi789",
        "merchantId": "mer_xyz789",
        "walletId": "wal_def456",
        "reserveType": "CHARGEBACK_RESERVE",
        "reserveReason": "Chargeback dispute CBK-2024-001",
        "originalAmount": 1500,
        "currentAmount": 1500,
        "releasedAmount": 0,
        "currency": "INR",
        "status": "ACTIVE",
        "reservedAt": "2024-01-10T14:30:00.000Z",
        "releaseScheduledAt": "2024-04-10T14:30:00.000Z",
        "releasedAt": null,
        "releasePeriodDays": 90,
        "reservePercentage": null,
        "sourceTransactionId": "txn_chargeback_001",
        "createdBy": "chargeback_service",
        "releasedBy": null,
        "releaseNotes": null
      }
    ],
    "totalReserved": 71500
  },
  "message": "Reserves retrieved successfully"
}

Reserve Types

Type	Description
PAYOUT_RESERVE	Funds reserved for pending payout operations
RISK_RESERVE	Rolling reserve based on merchant risk profile (typically 5-10% of volume)
CHARGEBACK_RESERVE	Funds held during chargeback dispute resolution

Reserve Statuses

Status	Description
ACTIVE	Reserve is currently held, full amount blocked
PARTIALLY_RELEASED	Part of the reserve has been released
FULLY_RELEASED	Reserve has been completely released back to merchant
FORFEITED	Reserve was forfeited (e.g., chargeback lost)

Examples

cURL

# Get all reserves
curl -X GET "https://api.zenpays.com/merchant/api/v1/ledger/reserves" \
  -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"

# Get only active payout reserves
curl -X GET "https://api.zenpays.com/merchant/api/v1/ledger/reserves?reserveType=PAYOUT_RESERVE&status=ACTIVE" \
  -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

// Get all reserves
const { reserves, totalReserved } = await zenpays.ledger.getReserves();

console.log(`Total reserved: ${totalReserved}`);

reserves.forEach(reserve => {
  console.log(`${reserve.reserveType}: ${reserve.currentAmount} ${reserve.currency} (${reserve.status})`);
});

// Get only active risk reserves
const riskReserves = await zenpays.ledger.getReserves({
  reserveType: 'RISK_RESERVE',
  status: 'ACTIVE'
});

// Calculate upcoming releases
const upcomingReleases = reserves.filter(r => {
  const releaseDate = new Date(r.releaseScheduledAt);
  const nextWeek = new Date();
  nextWeek.setDate(nextWeek.getDate() + 7);
  return releaseDate <= nextWeek && r.status === 'ACTIVE';
});

console.log('Reserves releasing in next 7 days:', upcomingReleases);