Execute Disbursement
After creating a quote, use this endpoint to process the actual payout to the recipient.
Endpoint
1POST /api/v1/disbursements/executeRequest Body
1{
2 "quoteId": "quote-uuid"
3}Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
quoteId | string (UUID) | Yes | Quote ID (quote.id) from the create quote response. The recipient, amount, and fees are all locked in from the quote. |
Note: The recipient phone number and amount are taken from the quote you created. You only need to pass the quoteId to execute.
Response
A 201 Created response returns the payout wrapped in a payout object:
1{
2 "payout": {
3 "id": "payout-uuid",
4 "merchantId": "merchant-uuid",
5 "gateway": "MTN_MOMO",
6 "amount": "5000.00",
7 "currency": "XAF",
8 "recipientMsisdn": "+237612345678",
9 "recipientName": null,
10 "gatewayFee": "15.00",
11 "platformFee": "10.00",
12 "totalDeduction": "5025.00",
13 "gatewayReference": "MTN_REF_123456789",
14 "status": "PROCESSING",
15 "createdAt": "2024-01-15T10:00:00.000Z"
16 }
17}Response Fields
| Field | Type | Description |
|---|---|---|
payout.id | string | Unique identifier for the payout (use this to check status) |
payout.status | string | Current payout status (PENDING, PROCESSING, SUCCESS, FAILED, CANCELLED) |
payout.totalDeduction | string | Total amount deducted from your wallet (amount + fees) |
payout.gatewayReference | string | null | Reference from the mobile money provider |
payout.createdAt | string | Payout creation timestamp (ISO 8601) |
Example Request
1const response = await fetch('https://api.zopay.co/api/v1/disbursements/execute', {
2 method: 'POST',
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 'Content-Type': 'application/json'
11 },
12 body: JSON.stringify({
13 quoteId: 'quote-uuid-from-previous-step'
14 })
15});
16
17const { payout } = await response.json();
18console.log('Payout ID:', payout.id);
19console.log('Status:', payout.status);Idempotency
Each quote can only be executed once. If you attempt to execute the same quoteId twice, the second request is rejected because the quote is already consumed. This built-in single-use behavior prevents duplicate payouts — create a new quote for each payout you want to send.
Important: Payouts are processed asynchronously. The initial response may show a status of "PROCESSING". Use the payout ID to check the status later, or set up webhooks to receive notifications when the payout completes.
Next Steps
After executing a disbursement, you can:
- Check the payout status using Get Status
- View all payouts using List Payouts
- Set up webhooks to receive real-time notifications