Direct Debit Integration Guide- Debit Account
Last updated Jan 22nd, 2025
Step 3: Debit bank account
In this step, it is advisable to first confirm if the desired balance on the account is available before proceeding to debit an account.
Re: Debits by Variable Mandate
- After the mandate is created and approved, a "ready-to-debit" webhook event will be sent approximately 3 hours later to notify you that the account is ready for debiting. For more details about webhook events, see here.
- Please note that the Debit Account Step is only required for Variable Mandates. Since Variable Mandates don't have a preset debit timeline, each debit and amount must be triggered manually via the API.
A. Confirming the Balance:
There are two ways to achieve this:
i. Checking if the user has sufficient funds for debit. This service is complimentary. To confirm if an account has the desired amount, send a GET request to the following endpoint:
Request
GET https://api.withmono.com/v3/payments/mandates/{mandate_id}/balance-inquiry?amount={amount}
Request Path Parameters
- mandate_id (required): The field expects the mandate ID returned in the created mandate response above. It typically begins with a mmc.
Request Query Parameters
- amount (required): The field expects the kobo amount that you need to check.
cURL Sample Request
Request
curl --request GET \
--url 'https://api.withmono.com/v3/payments/mandates/id/balance-inquiry?amount=200000' \
--header 'accept: application/json' \
--header 'mono-sec-key: string'
'
Success response
If the request is successful, you will receive the following response:
Request
{
"status": "successful",
"message": "Successfully enquired balance.",
"data": {
"id": "mmc_6578609e0000057f95da1588",
"has_sufficient_balance": false,
"account_details": {
"bank_code": "044",
"account_name": "SAMUEL OLAMIDE",
"account_number": "0123456789",
"bank_name": "ACCESS BANK PLC"
}
}
}
ii. Balance inquiry that provides the user's current balance i.e. checked the amount in the users account. (This service incurs a fee 50N). Here you don't need to pass amount as parameter.
Request
GET https://api.withmono.com/v3/payments/mandates/{mandate_id}/balance-inquiry
Request Path Parameters
- mandate_id (required): The field expects the mandate ID returned in the created mandate response above. It typically begins with a mmc.
cURL Sample Request
Request
curl --request GET \
--url 'https://api.withmono.com/v3/payments/mandates/id/balance-inquiry' \
--header 'accept: application/json' \
--header 'mono-sec-key: string'
'
Success response
If the request is successful, you will receive the following response:
Request
{
"status": "successful",
"message": "Sufficient balance available",
"data": {
"id": "mmc_65888b0000000043533aadd14",
"has_sufficient_balance": true,
"account_balance": 506000551.04,
"account_details": {
"bank_code": "101",
"account_name": "SAMUEL OLAMIDE",
"account_number": "6500746916",
"bank_name": "PROVIDUS"
}
}
}
B. Debiting the account
Subsequently, initiate a debit on the user's account by supplying required fields such as the amount (in Kobo), a unique reference, and the narration. It's important to be aware of the two direct debit structures available:
Direct to Payout: This debit type deducts the user's account and settles into your designated settlement account on your Mono dashboard on a T+1 basis.
Direct to Beneficiary: In this case, the user's account is debited, and the deducted amount is processed into the beneficiary details provided in the payload (i.e., the user's NUBAN/bank account and NIP code). (Note: To utilize this feature, please contact us, as access is granted on a case-by-case basis.)
N.B Direct Debit
- Debits are automatically added to payouts and settled on a T+1 basis by default.
- If the debit account request includes the beneficiary, the amount will be promptly processed to the beneficiary account. Please note that the beneficiary settings for debits are available only upon request.
To debit the bank account that already has a mandate set, send a POST request to the following endpoint:
Request
POST https://api.withmono.com/v3/payments/mandates/{mandate_id}/debit
Request Path Parameters
- mandate_id (required): The field expects the mandate ID returned in the created mandate response above. It typically begins with a mmc.
Request Body Parameters
| Field | Description |
| amount (required) | The field expects the amount you want to debit the user in Kobo |
| reference (required) | The field expects a unique reference for each direct debit. |
| narration (required) | This expects the narration indicating the purpose/description for this said account. |
| beneficiary | In this object field, there is both a NUBAN field and a NIP code field. The debited amount will be promptly settled into this account in real time. |
| beneficiary.nuban | This string field expects the nuban/bank account number. |
| beneficiary.nip_code | This string field expects the nip code of the destination bank account. You can visit here to get the nip code of the user's financial institution. |
cURL Sample Request
Direct to Payout
Request
curl --request POST \
--url https://api.withmono.com/v3/payments/mandates/mmc_657880a9928a8446a5212345/debit \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'mono-sec-key: live_sk_qwertyuiop' \
--data '
{
"amount": 150000,
"reference": "btD0319991D118",
"narration": "Netflix dec Debit",
}
'
Direct to beneficiary
Request
curl --request POST \
--url https://api.withmono.com/v3/payments/mandates/mmc_657880a9928a8446a5212345/debit \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'mono-sec-key: live_sk_qwertyuiop' \
--data '
{
"amount": 150000,
"reference": "btD0319991D118",
"narration": "Netflix dec Debit",
"beneficiary": {
"nuban": "0123456789",
"nip_code": "000013",
}
}
'
Success Response
If the request is successful, you will receive the following response:
Request
{
"status": "successful",
"message": "Account debited successfully.",
"response_code": "00",
"data": {
"status": "successful",
"amount": 1000,
"customer": "65785ef7cbb2025a8ef74123",
"mandate": "mmc_65785f380118257f95da1547",
"reference_number": "TPSDD319991D118-02",
"account_debited": {
"bank_code": "058",
"account_name": "SAMUEL OLAMIDE",
"account_number": "0123456789",
"bank_name": "GUARANTY TRUST BANK PLC"
},
"beneficiary": {
"bank_code": "000",
"account_name": "Mono",
"account_number": "P000001",
"bank_name": "MONO SETTLEMENT WALLET"
},
"date": "2023-12-13T10:30:34.009Z"
}
}
Here are additional API actions available for managing debit information:
Mandate Webhooks
This processing webhook (events.mandates.debit.processing) is sent to indicate a debit transaction is pending confirmation. When the transaction is finally confirmed as successful or failed, a webhook is sent and the status will be updated.
When direct debits are either successful or unsuccessful, distinct webhooks are activated depending on the specific outcome. For additional information on the varied payment webhook workflows, please refer to this resource.