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 "transaction_type": "DISBURSEMENT",
4 "amount": "5000",
5 "currency": "XAF",
6 "recipient": {
7 "msisdn": "+237612345678"
8 }
9}Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
gateway | string | Yes | Payment gateway (e.g., "MTN_MOMO", "ORANGE_MONEY") |
transaction_type | string | Yes | Must be "DISBURSEMENT" |
amount | string | Yes | Payout amount as a string |
currency | string | Yes | Currency code (e.g., "XAF", "USD") |
recipient | object | Yes | Recipient information |
recipient.msisdn | string | Yes | Recipient phone number in E.164 format |
Response
1{
2 "gateway_fee": "15.00",
3 "platform_fee": "10.00",
4 "total_amount": "500.00",
5 "net_to_merchant": "-525.00"
6}Response Fields
| Field | Type | Description |
|---|---|---|
gateway_fee | string | Fee charged by the mobile money provider |
platform_fee | string | ZoPay platform fee |
total_amount | string | What the recipient receives (the base amount you entered) |
net_to_merchant | string | Total deducted from merchant wallet (always negative for disbursements) |
Example Request
1const response = await fetch('https://api.zopay.com/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 transaction_type: 'DISBURSEMENT',
15 amount: '5000',
16 currency: 'XAF',
17 recipient: {
18 msisdn: '+237612345678'
19 }
20 })
21});
22
23const quote = await response.json();
24console.log('Quote ID:', quote.quote_id);
25console.log('Total Amount:', quote.total_amount);Quote Expiration
Quotes expire after a set period (typically 15 minutes). If a quote expires, you'll need to create a new one before executing the disbursement. Always check the expires_at field before using a quote.
Next Steps
Once you have a quote, proceed to Execute Disbursement to process the payout.