List Payouts
Retrieve a list of all your payouts with optional filtering and pagination.
Endpoint
1GET /api/v1/disbursementsQuery Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
status | string | No | Filter by status (PENDING, PROCESSING, SUCCESS, FAILED, CANCELLED) |
gateway | string | No | Filter by gateway (MTN_MOMO, ORANGE_MONEY) |
limit | number | No | Number of results per page (default: 20, max: 100) |
offset | number | No | Number of results to skip (for pagination) |
startDate | string | No | Start date filter (ISO 8601 format, e.g., "2024-01-01T00:00:00Z") |
endDate | string | No | End date filter (ISO 8601 format, e.g., "2024-01-31T23:59:59Z") |
Response
1{
2 "payouts": [
3 {
4 "id": "payout-uuid",
5 "merchantId": "merchant-uuid",
6 "gateway": "MTN_MOMO",
7 "amount": "5000.00",
8 "currency": "XAF",
9 "status": "SUCCESS",
10 "recipient": {
11 "msisdn": "+237612345678"
12 },
13 "gatewayReference": "MTN_REF_123456789",
14 "gatewayFee": "50.00",
15 "platformFee": "100.00",
16 "totalAmount": "5150.00",
17 "createdAt": "2024-01-15T10:00:00.000Z",
18 "completedAt": "2024-01-15T10:01:00.000Z"
19 }
20 ],
21 "total": 150,
22 "limit": 20,
23 "offset": 0,
24 "hasMore": true
25}Response Fields
| Field | Type | Description |
|---|---|---|
payouts | array | Array of payout objects |
total | number | Total number of payouts matching the filters |
limit | number | Number of results per page |
offset | number | Number of results skipped |
hasMore | boolean | Whether there are more results available |
Example Requests
Get All Payouts
1const response = await fetch('https://api.zopay.com/api/v1/disbursements', {
2 method: 'GET',
3 headers: {
4 'x-zo-key': apiKey,
5 'x-zo-timestamp': timestamp,
6 'x-zo-nonce': nonce,
7 'x-zo-origin': origin,
8 'x-zo-signature': signature,
9 'x-zo-version': '1.0'
10 }
11});
12
13const data = await response.json();
14console.log('Total payouts:', data.total);
15console.log('Payouts:', data.payouts);Filter by Status
1const response = await fetch('https://api.zopay.com/api/v1/disbursements?status=SUCCESS', {
2 method: 'GET',
3 headers: {
4 'x-zo-key': apiKey,
5 'x-zo-timestamp': timestamp,
6 'x-zo-nonce': nonce,
7 'x-zo-origin': origin,
8 'x-zo-signature': signature,
9 'x-zo-version': '1.0'
10 }
11});Pagination
1// Get second page (20 results per page)
2const response = await fetch('https://api.zopay.com/api/v1/disbursements?limit=20&offset=20', {
3 method: 'GET',
4 headers: {
5 'x-zo-key': apiKey,
6 'x-zo-timestamp': timestamp,
7 'x-zo-nonce': nonce,
8 'x-zo-origin': origin,
9 'x-zo-signature': signature,
10 'x-zo-version': '1.0'
11 }
12});Date Range Filter
1const startDate = '2024-01-01T00:00:00Z';
2const endDate = '2024-01-31T23:59:59Z';
3
4const response = await fetch(
5 `https://api.zopay.com/api/v1/disbursements?startDate=${startDate}&endDate=${endDate}`,
6 {
7 method: 'GET',
8 headers: {
9 'x-zo-key': apiKey,
10 'x-zo-timestamp': timestamp,
11 'x-zo-nonce': nonce,
12 'x-zo-origin': origin,
13 'x-zo-signature': signature,
14 'x-zo-version': '1.0'
15 }
16 }
17);Pagination Best Practices
- Use
limitto control page size (default: 20, max: 100) - Use
offsetto navigate through pages - Check
hasMoreto determine if there are more results - For large datasets, consider using date range filters to reduce result size
Filtering Tips
- Combine multiple filters (e.g., status + date range) for precise queries
- Use date filters to retrieve payouts from specific time periods
- Filter by gateway to see payouts for a specific payment method
- Filter by status to find failed payouts that need attention
Next Steps
Learn more about:
- Bulk Payouts for processing multiple payouts
- Get Status for detailed payout information