Direct Debit Integration Guide- Debit Account
Last updated May 8th, 2024
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 is sent ~1 hour later to let you know that the account is ready for debitting. See here for more detail about webhook events.
- Please take note that the Debit Account Step is only necessary for Variable Mandates. Variable mandate do not have a preset debit timeline so each debit and amount must be trigged via 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.