# List Refunds Retrieve a paginated list of refunds with optional filters. ## Request ### Headers ### Query Parameters ### Refund Status Values | Status | Description | |--------|-------------| | `requires_beneficiary` | Beneficiary details needed — re-submit with required fields | | `pending_approval` | Awaiting admin approval | | `approved` | Approved, being sent to provider | | `processing` | Being processed by payment provider | | `completed` | Refund completed successfully | | `failed` | Refund failed — check `failureReason` | | `rejected` | Rejected by admin | | `cancelled` | Cancelled before processing | ## Response ### Success (200 OK) ```json { "success": true, "data": [ { "refundId": "refund_1774683026458_oann5ibjf", "merchantId": "ZP_FIN_1774592804_0781001264", "customerId": "cust_mn8yfewm_37ntht", "transactionId": "txn_1774619159530_1_mn8yfmph_5iwb9b", "paymentIntentId": "pi_1774619159530_66d8s8v25", "amount": 30, "originalAmount": 100, "currency": "INR", "refundType": "partial", "status": "pending_approval", "tspProvider": "sulifu_pay", "externalRefundId": null, "reason": "Customer requested refund", "createdAt": "2026-03-28T07:30:26.479Z", "completedAt": null, "failureReason": null, "processingTimeMs": null } ], "metadata": { "pagination": { "page": 1, "limit": 20, "total": 45, "totalPages": 3 } } } ``` ## Examples ```bash curl -X GET "https://api.zenpayz.com/merchant/api/v1/refund-intents?status=completed&limit=50" \ -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 const crypto = require('crypto'); const apiKey = process.env.ZENPAYS_API_KEY; const secretSalt = process.env.ZENPAYS_SECRET_SALT; const timestamp = new Date().toISOString(); const signature = crypto .createHmac('sha256', secretSalt) .update(timestamp + '{}') .digest('hex'); const params = new URLSearchParams({ status: 'completed', limit: '50', }); const response = await fetch( `https://api.zenpayz.com/merchant/api/v1/refund-intents?${params}`, { method: 'GET', headers: { 'Authorization': `Bearer ${apiKey}`, 'X-Timestamp': timestamp, 'X-Signature': signature, 'X-Secret-Salt': secretSalt, }, } ); const result = await response.json(); console.log(`Found ${result.pagination.total} refunds`); ``` ```javascript const { data, total } = await zenpays.refunds.list({ status: 'completed', limit: 50, }); console.log(`Found ${total} refunds`); ``` ## Related Endpoints - [Confirm Refund Intent](/docs/rest-api/endpoints/refunds/create-refund) - [Get Refund](/docs/rest-api/endpoints/refunds/get-refund) - [Refund Statistics](/docs/rest-api/endpoints/refunds/refund-stats)