Disburse Integration Guide
Last updated Sep 18th, 2025
Overview
This guide walks you through integrating the Disburse API into your application. With it, you can link funding accounts, initiate instant or scheduled disbursements, and manage bulk transfers securely. By following this guide, you can implement a seamless payment experience with Mono Disburse.
Prerequisites
To get started, you need to:
- Sign up on the Partner Dashboard.
- Create an app with the
disbursescope and retrieve the secret key. - Configure a webhook URL in your dashboard to receive webhook event notifications.
How it works
After creating a Disburse App via the dashboard:
Setup a source account: This involves creating and approving a mandate, which is linked to an approved mandate. this is the source of funds for the disbursement.
You initiate a disbursement: Specifying the
type(instant or scheduled),source(wallet or mandate), along with areference,total amount, and a detailedlist of recipients.Mono processes the disbursement: This involves debiting the specified mandate source (Account) and sending the money to the recipients.
Real-time updates: Mono tracks batch and individual transaction statuses, sends webhooks for batch and distribution-level events, and allows statuses to be retrieved via API.
Disburse Workflow Status
initiated: The disbursement (transfer batch) is created.ready: The disbursement is prepared and ready to be processed.processing: The disbursement has been picked up for execution.securing: The funds are being debited from the source (e.g., wallet or account).secured: The funds have been successfully debited from the source and verified.transferring: The fund transfer to the beneficiaries is about to start as a batch.transferred: The batch transfer request has been successfully created.successful: All transactions in the batch were successful.failed: All transactions in the batch failed.completed: The batch contains a mix of successful and failed transactions.
Request Headers
Include the following header in your request for authentication. This is important for all endpoints.
mono-sec-key(required): live_sk_xxxxxxxxxxxxxxxxxxxx
This also determines the environment you're using. For example, if you're using the sandbox environment, your key will be prefixed with test_sk and live_sk for the live (production) environment.
NOTE: Disburse is currently only available on the live environment.
API Integration Steps
With the above prerequisite steps already taken, please note that there are four stages for completing the integration process:
Step 1: Create a Business Source Account
Step 2: Initiate a Disbursement
Step 3: Manage Scheduled Disbursements (if you created a scheduled disbursement)
Step 4: Track Status & Webhooks
Step 1: Create a Business Source Account
Before initiating disbursements, you need a funding source. Create a source account that will be linked to your app. This source account is connected to a mandate, which is the official debit instruction for funds.
Request
curl -X POST https://api.withmono.com/v3/payments/disburse/source-accounts \
-H "mono-sec-key: test_sk_xxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"app": "62229d670c34e0c3b9139f44",
"account_number": "1122334455",
"bank_code": "044",
"email": "olamide@neem.co"
}'
Body Request Descriptions
| Field | Type | Description |
| app | String | A unique identifier for the application you're configuring the disbursement in. (You will get this from the dashboard). |
| account_number | String | The NUBAN of the bank account to be linked. |
| bank_code | String | The NIP code of the bank account to be linked. You can find the codes here. |
| String | An email address associated with the app. Can be the business owner or app creator. |
Response
Request
{
"status": "successful",
"message": "Business account created successfully",
"timestamp": "2025-08-20T14:11:00.489Z",
"data": {
"id": "68a4ac5200dcc73621111111",
"mandate_activation_url": "https://authorise.mono.co/RD4605211111"
}
}
A successful request will return a mandate_activation_url and an ID. To enable payouts using this account, you must navigate to the provided URL and approve the mandate which authorizes Mono to debit the account.
Step 2: Initiate a Disbursement
Once the mandate is ready for debit, i.e ( after the ready to debit event is received), you can initiate either an instant or scheduled disbursement.
Instant Disbursement: Executes immediately.
Scheduled Disbursement: Created first, then triggered later.
Instant Disbursement
Request
// Instant Disbursement
curl -X POST https://api.withmono.com/v3/payments/disburse/disbursements \
-H "mono-sec-key: YOUR_MONO_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"reference": "disburse704592203061269674432",
"source": "mandate",
"account": "688a0b672f88111f11d11ab2",
"type": "instant",
"total_amount": 20000,
"description": "testing distribution",
"distribution": [
{
"reference": "tran0sfdfer123",
"recipient_email": "olamide@neem.com",
"account": {
"account_number": "0011223344",
"bank_code": "044"
},
"amount": 20000,
"narration": "transfer narration"
}
]
}'
You’ll get a response confirming that the batch has been created with status pending.
Response
Request
{
"status": "successful",
"message": "Disbursement request received",
"timestamp": "2025-08-01T09:42:59.668Z",
"data": {
"id": "688a0b672f88000f23d11ab2f",
"reference": "disburse704592203061269674432",
"status": "pending"
}
}
Scheduled Disbursement
Request
// Scheduled Disbursement
curl -X POST https://api.withmono.com/v3/payments/disburse/disbursements \
-H "mono-sec-key: YOUR_MONO_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"reference": "Disburse422233249d9324402926004",
"source": "mandate",
"account": "688a0b672f88111f11d11ab2",
"type": "scheduled",
"total_amount": 50000,
"description": "testing distribution scheduled 3"
}'
Scheduled Disbursements
At the point of creation, a scheduled disbursement will have no distributions (recipients). You will need to add these later using the Add Distributions API.
Response
Request
{
"status": "successful",
"message": "Scheduled disbursement created",
"timestamp": "2025-08-01T09:42:59.668Z",
"data": {
"id": "688a0b672f88000f23d11ab2f",
"reference": "disburse704592203061269674432",
"status": "created"
}
}
Step 3: Manage Scheduled Disbursements (Optional)
If you created a scheduled disbursement, you can either:
Add distributions (more recipients)
Update distributions (modify details)
Trigger or cancel the batch
Add Distributions to a Scheduled Disbursement
Request
// Add Distributions to batch
curl -X POST https://api.withmono.com/v3/payments/disburse/disbursements/{id}/distributions \
-H "mono-sec-key: YOUR_MONO_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"distribution": [
{
"recipient_email": "mary@example.com",
"bank_code": "033",
"narration": "july salary",
"account_number": "1029381212",
"amount": 250000
}
]
}'
Response
Request
{
"status": "successful",
"message": "Distribution added successfully",
"timestamp": "2025-08-01T09:49:59.766Z",
"data": {
"status": "successful",
"summary": {
"valid": 1,
"invalid": 0
},
"valid_accounts": [
{
"id": "TmAdOoEpQWeGVhIDtqiI",
"bank_code": "044",
"account_number": "1234567890",
"account_name": "Mono isioma account",
"beneficiary_id": "6759a0a9708ee02f9f21b6b4",
"email": "mary@example.com",
"reference": "Testidngref6"
}
],
"invalid_accounts": []
}
}
Trigger or Cancel a Scheduled Disbursement
Request
// Trigger
curl -X POST https://api.withmono.com/v3/payments/disburse/disbursements/{id}/transition \
-H "mono-sec-key: YOUR_MONO_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"action": "trigger"
}'
This moves the batch into processing or cancelled depending on the action.
Response
Request
{
"status": "successful",
"message": "Disbursement updated successfully",
"timestamp": "2025-08-01T10:52:51.386Z",
"data": {
"status": "processing",
"id": "688c94d5b947fac1455fa502"
}
}
Update a Distribution details
Request
curl -X PUT https://api.withmono.com/v3/payments/disburse/disbursements/{id}/distributions/{distribution_id}/update \
-H "mono-sec-key: YOUR_MONO_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"distribution": [
{
"recipient_email": "mary@example.com",
"bank_code": "033",
"narration": "july salary"
"account_number": "1029384756",
"amount": 250000
}
]
}'
This updates the details of distributions in a batch of a scheduled disbursement.
Response
Request
{
"status": "successful",
"message": "Distribution updated successfully",
"timestamp": "2025-08-01T10:51:40.394Z",
"data": {
"success": true,
"message": "Distribution updated successfully"
}
}
Step 4: Track Status & Webhooks
Mono manages the disbursement workflow through states
initiated → ready → processing → securing → transferred → successful/failed.
You can monitor these in two ways:
1. Fetch a Disbursement via API:
Request
GET https://api.withmono.com/v3/payments/disburse/disbursements/{id} \
-H "mono-sec-key: YOUR_MONO_SECRET_KEY"
Response
Request
{
"status": "successful",
"message": "Disbursement fetched successfully",
"timestamp": "2025-08-01T10:52:28.775Z",
"data": {
"id": "622d11d3b711fac1455fa502",
"reference": "Disburse4222332499324402926004",
"status": "initiated",
"description": "testing distribution scheduled 3",
"type": "scheduled",
"total_amount": 20000,
"distributions_count": 1,
"approved_by": "Samuel Olamide",
"approval_date": "2025-08-01T10:20:05.274Z",
"total_records_count": 1,
"total_successful_amount": "0",
"successful_transactions_count": 0,
"total_failed_amount": "0",
"failed_transactions_count": 0,
"created_at": "2025-08-01T10:20:05.279Z"
}
}
2. Listen to Webhooks
events.disbursement.processing
events.disbursement.completed
events.disbursement.transaction.successful
events.disbursement.transaction.failed
Example webhook payload
Request
{
"event": "events.disbursement.completed",
"data": {
"reference": "disburse704592203061269674432",
"processing_summary": {
"count": 1,
"amount": 20000
},
"successful_summary": {
"count": 1,
"amount": 20000
},
"failed_summary": {
"count": 0,
"amount": 0
},
"app": "62229d670c34e0c3b9139f44",
"business": "62dd7f95ba1000019c5c6b1d"
}
}