Mandate Tokenisation Guide
Last updated Jul 30th, 2024
Overview
The Direct Debit API provides a new feature called the mandate authorization with OTP (One-Time Password). This feature simplifies the mandate creation process for users who already have an approved mandate in the Mono Network. Instead of going through the entire authorization process again, users can authorize a new mandate with an OTP sent to their registered email or phone number.
How It Works
The process for how this works is summarised in the below pointers:
- Your business initiates mandate creation with an account number.
- If the account number exists in our network, the customer will receive an OTP on the email or phone number used during the initial mandate creation.
- If the account number does not exist in our network, the user will need to go through the transfer authorization method.
- Once the OTP is validated, a mandate will be created with the new business.
- The mandate will then be ready for immediate debiting.
Mandate Tokenisation
When authorizing new mandates with OTP via the Create a Mandate API, the request body remains unchanged.
However, an otp_destinations field is included in the response, allowing the user to choose their preferred authorization method.
The OTP verification process is then managed in the Verify Mandate OTP API.
NOTE: The OTP generated expires after 1 minute.
Integration Steps
1. Create Mandate
Initiates the creation of a mandate. If the account number exists in the Mono Network, an OTP will be sent for authorization.
cURL Request:
Request
curl -X POST https://api.withmono.com/v3/payments/mandates \
-H "Content-Type: application/json" \
-H "mono-sec-key: live_sk_your_key" \
-d '{
"customer": "667bdd924e0563ff8d555741",
"mandate_type": "emandate",
"debit_type": "variable",
"amount": 1000000,
"account_number": "0260553842",
"bank_code": "058",
"description": "Mono subscriptions",
"start_date": "2025-01-17",
"end_date": "2025-12-21",
"reference": "9MONoDDw111MO2224P4"
}'
API Response:
Request
{
"status": "successful",
"message": "To complete this mandate setup, please authorise by entering the otp sent to 070****9833 or l**********8@gmail.com",
"data": {
"id": "mmc_6698c9efb68276eb67474ef5",
"status": "initiated",
"mandate_type": "emandate",
"debit_type": "variable",
"amount": 6001951100,
"ready_to_debit": false,
"nibss_code": "RC227914/1580/0003326447",
"approved": false,
"reference": "135050973876543220x1",
"account_name": "HASSAN ABDULHAMID TOMIWA",
"account_number": "0131863463",
"bank": "GUARANTY TRUST BANK PLC",
"bank_code": "058",
"customer": "6645e1f14ff0a494495c7b7f",
"description": "Zenith bank test",
"live_mode": true,
"start_date": "2024-07-18T00:00:00.000Z",
"end_date": "2024-09-25T00:00:00.000Z",
"date": "2024-07-18T07:53:19.204Z",
"otp_destinations": {
"session": "48f18dd1-a20a-453a-b10c-5d8b58ce7f02",
"methods": [
{
"type": "phone_number",
"value": "070****9833"
},
{
"type": "email",
"value": "l****8@gmail.com"
}
]
}
}
}
2. Verify OTP
This endpoint verifies the OTP sent to the customer's phone or email. This step completes the mandate creation process.
Step a: Set Preferred OTP Method
cURL Request:
Request
curl -X POST https://api.withmono.com/v3/payments/mandates/verify/otp \
-H "Content-Type: application/json" \
-H "mono-sec-key: live_sk_your_key" \
-d '{
"session": "48f18dd1-a20a-453a-b10c-5d8b58ce7f02",
"method": "phone_number"
}'
API Response:
Request
{
"status": "successful",
"message": "An otp has been sent to your phone number",
"data": {
"phone_number": "070****9833",
"action": "input_otp",
"session": "cda2d994-43e6-4d5a-ad72-0906fa3f3480"
}
}
Step b: Verify OTP
cURL Request:
Request
curl -X POST https://api.withmono.com/v3/payments/mandates/verify/otp \
-H "Content-Type: application/json" \
-H "mono-sec-key: live_sk_your_key" \
-d '{
"session": "e440aed2-640c-4626-a024-a8529a30a244",
"otp": "156750"
}'
API Response:
Request
{
"status": "successful",
"message": "Mandate is now successfully created and approved.",
"data": {
"id": "mmc_668f8fe21622ea990acd77e6",
"status": "approved",
"mandate_type": "emandate",
"debit_type": "variable",
"ready_to_debit": true,
"nibss_code": "RC227914/1580/0003171012",
"approved": true,
"reference": "9MONoDDw111MO2224P4",
"account_name": "DISI PRINCE BOSINDE",
"account_number": "0260553842",
"bank": "GUARANTY TRUST BANK PLC",
"bank_code": "058",
"customer": "667bdd924e0563ff8d555741",
"description": "Mono subscriptions",
"live_mode": true,
"start_date": "2025-01-17T00:00:00.000Z",
"end_date": "2025-12-21T00:00:00.000Z",
"date": "2024-07-11T07:55:14.257Z",
"amount": 1000000
}
}
Tokenised Mandate Approval
As soon as the OTP has been verified successfuly, note that the mandate approved webhook (events.mandates.approved) is sent immediately to confirm approval of the tokenised mandate