Create Disbursement Quote
Before executing a disbursement, you should create a quote to get pricing information including fees, the amount the recipient receives, and the total merchant wallet deduction.
Endpoint
1POST /api/v1/disbursements/quoteNote: This endpoint returns the recipient amount in total_amount and the merchant wallet debit in net_to_merchant.
Quote Validity: Quotes expire after 15 minutes. Fees are locked in during this period, but after expiry, you must create a new quote as pricing may have changed. Each quote can only be used once.
Request Body
1{
2 "gateway": "MTN_MOMO",
3 "amount": "5000",
4 "currency": "XAF",
5 "recipientMsisdn": "+237612345678",
6 "reference": "Salary January",
7 "description": "Monthly salary payout"
8}Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
gateway | string | Yes | Payment gateway (e.g., "MTN_MOMO", "ORANGE_MONEY") |
amount | string | Yes | Payout amount as a string |
currency | string | Yes | 3-letter currency code (e.g., "XAF") |
recipientMsisdn | string | Yes | Recipient phone number in E.164 format |
reference | string | No | Your own reference for reconciliation (max 255 chars) |
description | string | No | Description of the payout (max 500 chars) |
Response
A 201 Created response returns the quote wrapped in a quote object:
1{
2 "quote": {
3 "id": "quote-uuid",
4 "merchantId": "merchant-uuid",
5 "gateway": "MTN_MOMO",
6 "transactionType": "DISBURSEMENT",
7 "amount": "5000.00",
8 "currency": "XAF",
9 "gatewayFee": "15.00",
10 "platformFee": "10.00",
11 "totalAmount": "5000.00",
12 "netToMerchant": "-5025.00",
13 "recipientName": null,
14 "expiresAt": "2024-01-15T10:15:00.000Z",
15 "status": "ACTIVE"
16 }
17}Response Fields
| Field | Type | Description |
|---|---|---|
quote.id | string | Quote ID - use this to execute the disbursement |
quote.gatewayFee | string | Fee charged by the mobile money provider |
quote.platformFee | string | ZoPay platform fee |
quote.totalAmount | string | What the recipient receives (the base amount you entered) |
quote.netToMerchant | string | Total deducted from merchant wallet (always negative for disbursements) |
quote.recipientName | string | null | Recipient name (if resolved via external lookup) |
quote.expiresAt | string | Quote expiration timestamp (ISO 8601, 15 minutes) |
quote.status | string | Quote status (ACTIVE when created) |
Example Request
1const response = await fetch('https://api.zopay.co/api/v1/disbursements/quote', {
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 gateway: 'MTN_MOMO',
14 amount: '5000',
15 currency: 'XAF',
16 recipientMsisdn: '+237612345678',
17 reference: 'Salary January'
18 })
19});
20
21const { quote } = await response.json();
22console.log('Quote ID:', quote.id);
23console.log('Net to Merchant:', quote.netToMerchant);Quote Expiration
Quotes expire after 15 minutes. If a quote expires, you'll need to create a new one before executing the disbursement. Always check the quote.expiresAt field before using a quote.
Next Steps
Once you have a quote, proceed to Execute Disbursement to process the payout.