Disbursements Overview

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.

How Disbursements Work

The disbursement process involves several steps:

Create a Quote: Get pricing information for the payout
Execute Disbursement: Process the payout to the recipient
Check Status: Monitor the payout status
List Payouts: View all your payouts with filters
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

You initiate a payout on your platform
Your application creates a quote via POST /api/v1/disbursements/quote
Quote includes fees, the recipient amount, and the merchant wallet deduction
Your application executes disbursement via POST /api/v1/disbursements/execute
ZoPay processes payout with the mobile money provider
Webhook notification sent when payout completes
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 you pay (payout amount + fees)

Idempotency

Always include an idempotency_key when executing disbursements. This ensures that if a request is retried due to network issues, the same payout won't be processed twice.

💡

Quote Expiry: Quotes are valid for 15 minutes. After expiry, you must create a new quote as fees may have changed. Always use the quote ID from the most recent quote when executing a disbursement.

Next Steps

Learn how to Create a Quote
See how to Execute a Disbursement
Understand Payout Status
View List Payouts documentation
Learn about Bulk Payouts

PreviousHosted Checkout

NextCreate Quote

How Disbursements Work

The disbursement process involves several steps:

Create a Quote: Get pricing information for the payout

Execute Disbursement: Process the payout to the recipient

Check Status: Monitor the payout status

List Payouts: View all your payouts with filters

Bulk Payouts: Process multiple payouts from a CSV file

Disbursement Flow

You initiate a payout on your platform

Your application creates a quote via POST /api/v1/disbursements/quote

Quote includes fees, the recipient amount, and the merchant wallet deduction

Your application executes disbursement via POST /api/v1/disbursements/execute

ZoPay processes payout with the mobile money provider

Webhook notification sent when payout completes

Check payout status via GET /api/v1/disbursements/:id

Idempotency

Always include an idempotency_key when executing disbursements. This ensures that if a request is retried due to network issues, the same payout won't be processed twice.

💡