Create Quote
Before executing a collection, you should create a quote to get pricing information including fees and the total amount the customer will pay.
Endpoint
1POST /api/v1/wallets/quoteNote: This endpoint is used for both collections and disbursements. Set transaction_type to COLLECTION or DISBURSEMENT.
💡
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": "COLLECTION",
4 "amount": "10000",
5 "currency": "XAF",
6 "payer": {
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 | Type of transaction: "COLLECTION" or "DISBURSEMENT" |
amount | string | Yes | Transaction amount (as string to avoid precision issues) |
currency | string | Yes | Currency code (e.g., "XAF", "XOF", "USD") |
payer | object | Yes | Payer information (for collections) |
payer.msisdn | string | Yes | Customer's phone number in international format |
Response
1{
2 "quote_id": "quote-uuid",
3 "fees": {
4 "gateway_fee": "50.00",
5 "platform_fee": "100.00"
6 },
7 "total_amount": "10150.00",
8 "net_to_merchant": "10150.00",
9 "expires_at": "2024-01-15T10:45:00.000Z"
10}Response Fields
| Field | Type | Description |
|---|---|---|
quote_id | string | Unique identifier for the quote (use this when executing collection) |
fees.gateway_fee | string | Fee charged by the mobile money provider |
fees.platform_fee | string | ZitoPay platform fee |
total_amount | string | Total amount customer will pay (amount + fees) |
net_to_merchant | string | Amount you will receive after fees |
expires_at | string | Quote expiration timestamp (ISO 8601) |
Example Request
1const response = await fetch('https://api.zopay.com/api/v1/wallets/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: 'COLLECTION',
15 amount: '10000',
16 currency: 'XAF',
17 payer: {
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 5-15 minutes). If a quote expires, you'll need to create a new one before executing the collection. Always check the expires_at field before using a quote.
Next Steps
Once you have a quote, proceed to Execute Collection to process the payment.