Disbursements

Disbursements allow you to send money to customers, suppliers, employees, or partners via mobile money. This section covers everything you need to know about processing payouts through ZoPay.

Overview

The disbursement process involves several steps:

1. Create a Quote: Get pricing information for the payout
2. Execute Disbursement: Process the payout to the recipient
3. Check Status: Monitor the payout status
4. List Payouts: View all your payouts with filters
5. Bulk Payouts: Process multiple payouts from a CSV file

Supported Gateways

• MTN Mobile Money: Available in Cameroon, Ivory Coast, and other supported countries
• Orange Money: Push payment integration

Disbursement Flow

1. You initiate a payout on your platform
2. Your application creates a quote via POST /api/v1/disbursements/quote
3. Quote includes gateway fee, platform fee, recipient amount, and total wallet deduction
4. Your application executes disbursement via POST /api/v1/disbursements/execute
5. ZoPay processes payout with the mobile money provider
6. Webhook notification sent when payout completes
7. Check payout status via GET /api/v1/disbursements/:id

Payout Statuses

• PENDING: Payout initiated, awaiting processing
• PROCESSING: Payout is being processed
• SUCCESS: Payout completed successfully
• FAILED: Payout failed (check error details)
• CANCELLED: Payout was cancelled

Fees

Each disbursement includes:

• Gateway Fee: Fee charged by the mobile money provider
• Platform Fee: ZoPay service fee
• Total Amount: Amount the recipient receives
• Net to Merchant: Total deducted from the merchant wallet

Create Disbursement Quote

Before executing a disbursement, you should create a quote to see the fee breakdown, the amount the recipient receives, and the total wallet deduction for the merchant.

Endpoint

1POST /api/v1/disbursements/quote

Note: This endpoint returns the amount the recipient receives in total_amount and the total merchant wallet debit in net_to_merchant.

Request Body

1{
2  "merchant_id": "uuid",
3  "gateway": "MTN_MOMO",
4  "amount": "5000",
5  "currency": "XAF",
6  "transaction_type": "DISBURSEMENT"
7}

Request Parameters

Response

1{
2  "gateway_fee": "15.00",
3  "platform_fee": "10.00",
4  "total_amount": "5000.00",
5  "net_to_merchant": "-5025.00"
6}

Execute Disbursement

After creating a quote, use this endpoint to process the actual payout to the recipient.

Endpoint

1POST /api/v1/disbursements/execute

Request Body

1{
2  "quote_id": "quote-uuid",
3  "idempotency_key": "unique-payout-123",
4  "recipient": {
5    "msisdn": "+237612345678"
6  }
7}

Request Parameters

Response

1{
2  "payout_id": "payout-uuid",
3  "status": "PROCESSING",
4  "gateway_reference": "MTN_REF_123456789",
5  "correlation_id": "corr-uuid"
6}

Get Payout Status

Check the status of a disbursement to see if it has been completed, failed, or is still processing.

Endpoint

1GET /api/v1/disbursements/:id

Path Parameters

Response

1{
2  "payout": {
3    "id": "payout-uuid",
4    "merchantId": "merchant-uuid",
5    "gateway": "MTN_MOMO",
6    "amount": "5000.00",
7    "currency": "XAF",
8    "status": "SUCCESS",
9    "recipient": {
10      "msisdn": "+237612345678"
11    },
12    "gatewayReference": "MTN_REF_123456789",
13    "gatewayFee": "50.00",
14    "platformFee": "100.00",
15    "createdAt": "2024-01-15T10:00:00.000Z",
16    "completedAt": "2024-01-15T10:01:00.000Z"
17  }
18}

List Payouts

Retrieve a list of all your payouts with optional filtering and pagination.

Endpoint

1GET /api/v1/disbursements

Query Parameters

Response

1{
2  "payouts": [
3    {
4      "id": "payout-uuid",
5      "amount": "5000.00",
6      "currency": "XAF",
7      "status": "SUCCESS",
8      "recipient": {
9        "msisdn": "+237612345678"
10      },
11      "createdAt": "2024-01-15T10:00:00.000Z"
12    }
13  ],
14  "total": 150,
15  "limit": 20,
16  "offset": 0
17}

Bulk Payouts

Process multiple payouts at once by uploading a CSV file. This is useful for payroll, vendor payments, or mass disbursements.

Step 1: Upload CSV File

First, upload your payout CSV file using the files API:

1POST /files/v1/payout-csv

CSV Format

Your CSV file should have the following format:

1phone,amount,gateway,reference
2+237612345678,10000,MTN_MOMO,Salary January
3+237690123456,15000,ORANGE_MONEY,Commission Q1
4+237670987654,5000,MTN_MOMO,Bonus

CSV Columns

Step 2: Process Bulk Payout

After uploading the CSV, process the bulk payout:

1POST /api/v1/disbursements/bulk

Request Body

1{
2  "file_id": "file-uuid",
3  "idempotency_key": "bulk-payout-2024-01-15"
4}

Response

1{
2  "batch_id": "batch-uuid",
3  "total_payouts": 100,
4  "status": "PROCESSING",
5  "created_at": "2024-01-15T10:00:00.000Z"
6}

Bulk Payout Status

Bulk payouts are processed asynchronously. You can check the status of individual payouts using the List Payouts endpoint with a batch filter, or set up webhooks to receive notifications for each payout.

Best Practices

• Validate CSV format before uploading
• Use unique references for each payout
• Monitor bulk payout status via webhooks
• Keep CSV files under 10MB (typically 10,000-50,000 rows)
• Test with a small batch first