Partial Sweep
Last updated August 5th, 2026
Overview
Partial Sweep enables you to recover outstanding payments across a customer's linked bank accounts. Instead of a single full-debit attempt that either succeeds or fails, Partial Sweep checks balances across all linked accounts and debits available funds from each account until the target amount is recovered.
How it works
- Balance inquiry: Mono performs balance checks across all active linked accounts.
- Prioritised debiting: Accounts are prioritised based on available balance and debited in order.
- Partial collection: Each account is debited up to its available balance.
- Aggregation: Debits continue across accounts until the total amount is collected or all accounts have been exhausted.
The process stops automatically when the full amount is recovered or no accounts remain to debit.
Pricing
| Component | Cost |
| Balance check | NGN 50 per account |
Debit fees follow the standard Mono Sweep pricing.
Balance inquiry charges
Balance inquiry fees are charged per case based on the number of available accounts. This cost applies regardless of recovery outcome, as long as a successful response is received from NIBSS.
Enabling Partial Sweep
Feature access
Partial Sweep needs to be separately enabled for your account. To request access, reach out to sales@mono.co.
Enabling at initiation
Set allow_partial_sweep to true when initiating a sweep mandate via the Initiate a Mandate API:
Request
curl --request POST \
--url https://api.withmono.com/v2/payments/initiate \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'mono-sec-key: string' \
--data '{
"amount": 9190030,
"type": "recurring-debit",
"method": "mandate",
"mandate_type": "sweep",
"debit_type": "variable",
"allow_partial_sweep": true,
"account_number": "12345678901",
"bank_code": "023",
"description": "Repayment for samuel@neem.com",
"reference": "testO2b9O9EF903949493432",
"redirect_url": "https://mono.co",
"customer": {
"id": "65eb623b0000900009e5c1f21cd"
},
"start_date": "2024-03-29",
"end_date": "2024-08-04",
"meta": {}
}'
Fixed mandate restriction
Partial Sweep is only available for variable debit mandates. Setting allow_partial_sweep to true on a fixed mandate will return an error.
Enabling on an existing mandate
You can enable or disable partial sweep for an existing Mono Sweep mandate via the Toggle Partial Sweep API:
Request
curl --request PATCH \
--url https://api.withmono.com/v3/payments/mandates/id/partial-sweep/toggle \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'mono-sec-key: string' \
--data '{
"allow_partial_sweep": true
}'
allow_partial_sweep: true— partial sweep is enabled and partial debits occur across the customer's linked accounts.allow_partial_sweep: false— full sweep is restored and a full debit is attempted.
Webhook events
When partial sweep is enabled, debits follow an asynchronous flow:
- Debit initiated: You call the Debit Account API. The API responds immediately with
statusset toprocessing. - Processing event:
events.mandates.debit.processingconfirms the sweep is underway. - Individual debits: Each successful debit attempt triggers
events.mandates.debit_attempt.successfulwithtypeset topartial. Failed individual attempts do not send a separate event. - Final outcome: You receive
events.mandates.debit.successful(withstatusset tosuccessfulorpartial-debit-successful) orevents.mandates.debit.failed.
See the webhook events reference for the full payloads of events.mandates.debit_attempt.successful and events.mandates.debit.failed.
Response fields
Partial sweep responses include the following fields:
| Field | Type | Description |
pending_amount | number | Remaining amount yet to be collected (0 when the full amount is recovered) |
collected_amount | number | Amount collected so far |
debit_references | array | Individual debit attempts made during the sweep, each with account details, response_code, and response_description |
Processing event
Request
{
"event": "events.mandates.debit.processing",
"data": {
"status": "processing",
"message": "Payment is currently in processing state, please wait for a final state webhook before giving value",
"response_code": "99",
"amount": 140000,
"mandate": "mmc_8f3b2a1c9d4e5f6a7b8c9d0e",
"reference_number": "CSL2012d2fd37df323",
"date": "2024-08-12T00:32:17.192Z",
"live_mode": true
}
}
Partial success
When a partial amount has been collected, the existing events.mandates.debit.successful event is sent with status set to partial-debit-successful:
Request
{
"event": "events.mandates.debit.successful",
"data": {
"success": true,
"status": "partial-debit-successful",
"message": "Partial debit was successful",
"event": "successful",
"response_code": "00",
"amount": 700000,
"mandate": "mmc_7d4e3f2a1b9c8d7e6f5a4b3c",
"reference_number": "v8ugvb8xj3qf0zk9twq4",
"date": "2026-06-26T14:52:15.689Z",
"live_mode": true,
"fee": 11289,
"fee_bearer": "business",
"narration": "Loan repayment",
"app": "67adadced23314578c206000",
"session_id": "999999260626155204455449671000",
"business": "67adaad3d23314578c293d04",
"customer": "69c6865bce174257400ee0sx",
"account_details": {
"bank_code": "044",
"account_name": "Jane Doe",
"account_number": "0123456789",
"bank_name": "Access Bank"
},
"beneficiary": {
"bank_code": "100004",
"account_name": "Jane Doe",
"account_number": "8123451855",
"bank_name": null
},
"pending_amount": 299858,
"collected_amount": 400142,
"debit_references": [
{
"success": true,
"reference": "xWnOhEvpkJdchtT",
"account_number": "0816658538",
"account_name": "Jane Doe",
"bank_code": "044",
"session_id": "999999260626155151170007273218",
"response_code": "00",
"response_description": null,
"bank_name": "Access Bank"
},
{
"success": true,
"reference": "aSqbHSDQAZIqTtA",
"account_number": "0759854965",
"account_name": "John Smith",
"bank_code": "044",
"session_id": "999999260626155157127000919137",
"response_code": "00",
"response_description": null,
"bank_name": "Access Bank"
},
{
"success": true,
"reference": "ZvGBcPLOdyIUJXC",
"account_number": "0087476375",
"account_name": "Jane Doe",
"bank_code": "044",
"session_id": "9990092606061245204455449671599",
"response_code": "00",
"response_description": null,
"bank_name": "Access Bank"
}
]
}
}
Interpreting the final event
The final events.mandates.debit.successful or events.mandates.debit.failed event tells you how the sweep ended:
- Full success:
statusissuccessfulandpending_amountis0. - Partial success:
statusispartial-debit-successfulandpending_amountreflects the amount still outstanding. - Failed:
statusisfailedanddebit_referencescontains the failed individual attempts with theirresponse_codeandresponse_description.