# Get Ledger Reserves Retrieve reserve allocations for the merchant. Reserves are funds set aside for payouts, risk mitigation, and potential chargebacks. ## Request ### Headers ### Query Parameters ## Response ### Success (200 OK) ```json { "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 ```bash # 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" ``` ```javascript // 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); ```