Direct Debit Integration Guide- Mandate Setup (Variable)
Last updated May 8th, 2024
Step 2 (Option A): Variable bank mandate
Variable recurring mandate is an ideal option for businesses looking to collect a varied amount from their customers based on a set total debit for a period of time. For example, you authorise a mandate amount of ₦200,000 for 6 months which can debited in varied amounts and time.
Request Body Parameters
Using the customer ID (which is returned in the previous step) the next step is to create a mandate on an account belonging to this customer. To do this, a partner will need to provide the following information:
| Field | Description |
| amount (required) | This is the maximum amount to be debited from the user’s account throughout the mandate (i.e from start to end date). NGN 200 (20000 kobo) |
| type (required) | This expects a string value i.e recurring-debit |
| method (required) | This field expects a string value i.e mandate. |
| mandate_type (required) | This can either be signed or emandate or gsm. |
| debit_type (required) | This field expects the type of debit i.e variable |
| description (required) | This field expects a description of the set mandate. |
| reference (required) | This expects a unique reference ID for this particular reference. |
| start_date (required) | This expects the start date for this mandate to begin. e.g. 2024-12-15 |
| end_date (required) | This expects the end date for this mandate to end. e.g. 2024-05-25 |
| customer | This expects the the customer id as seen in the response here |
| meta (object) | This object used to include additional payment information. e.g meta |
cURL Sample Request: For Variable E-Mandate/Signed Mandate
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": "emandate", // or "signed" or "gsm"
"debit_type": "variable",
"description": "Repayment for samuel.olamide@mono.co",
"reference": "test-O2b9O9EF903-949493432",
"redirect_url": "https://mono.co",
"customer": {
"id":"65eb623b0000900009e5c1f21cd"
},
"start_date": "2024-03-29",
"end_date": "2024-08-04",
"meta": {}
}
Success Response
If the emandate or signed or gsm request has been initiated successfully, you will receive the following response:
Request
{
"status": "successful",
"message": "Payment Initiated Successfully",
"data": {
"mono_url": "https://authorise.mono.co/RD3044259",
"type": "recurring-debit",
"method": "mandate",
"mandate_type": "emandate", // or "signed" or "gsm"
"amount": 9190030,
"description": "Repayment for samuel.olamide@mono.co",
"reference": "test-O2b9O9EF903-949493432",
"customer": "65eb623b0000900009e5c1f21cd",
"redirect_url": "https://mono.co",
"created_at": "2024-03-12T14:17:31.548Z",
"updated_at": "2024-03-12T14:17:31.548Z",
"start_date": "2024-03-19",
"end_date": "2024-08-04"
}
}
Mandate Webhooks
Upon successful creation, rejection, or approval of a mandate, different webhooks are triggered based on the specific scenario. Explore this resource for more details on the diverse webhook workflows.
N.B On Mandate Creation
Please take note that for the successful creation of a direct debit mandate, it is essential that the Customer Name and Account Name match accurately.
Additional operations that can be performed on a direct debit mandate are:
- Cancelling a direct debit mandate 🔗
- Pausing a direct debit mandate 🔗
- Reinstating a direct debit mandate 🔗
- Retrieve a direct debit mandate 🔗
- Get all direct debit mandates 🔗
Re: Debits by Variable Mandate
Please take note that since there are no fixed schedule for debitting an account for Variable Mandates, each debit has to be triggered trigged via API following the instructions in Step 3: Debit an Account.