Direct Debit Integration Guide: Mandate Setup(Fixed)
Last updated May 8th, 2024
Step 2 (Option B): Fixed bank mandate
The fixed recurring mandate is an ideal option for businesses looking to collect a consistent amount from their customers for a set period. The fixed debit type handles recurring debits using our internal schedulers. For example, you authorise a mandate amount of ₦10,000 to debited monthly for twelve months which will automatically totalled and calculated by our systems as ₦120,000.
Re: Debits by Fixed Mandate
Please take note that the debits for fixed mandates are scheduled when creating the mandate and automatically debitted from the customer's account on the set date.
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 fixed 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 fixed |
| 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 |
| frequency (required) | This expects the frequency of the debit daily , weekly , monthly and yearly. For custom -frequencies use days, weeks, months and provide an whole number value in the interval field |
| interval | This expects any whole number (e.g. 1, 5) as it's only required when days, weeks, months are set as the frequency |
| retrial_frequency (required) | This expects the number of retries on a particular debit date [ Minimum is 1 & Maximum is 6 ]. For example, a customer’s debit date is 2023-03-04, but the initial debit failed, the retrial_frequency keeps retrying the transaction for the number of times specified at mandate creation. |
| initial_debit_date (required) | This expects the first day/date to debit the mandate account. Must be greater than start_date |
| initial_debit_amount | This expects the initial amount to debit on the initial_debit_date |
| grace_period (required) | This expects the number of days to continue debiting an account before setting the next debit date to next frequency date |
| minimum_due (required) | This expects an amount in a case of failed debits due to insufficient funds, the minimum_due is attempted i.e anything you can find, give debit |
| customer | This expects 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 Fixed E-Mandate or 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 {
"type": "recurring-debit",
"debit_type": "fixed",
"customer": {
"id": "6629259fe903b1"
},
"mandate_type": "emandate", // or "signed" or "gsm"
"amount": 200000,
"reference": "nomo-test-24-04-24-02",
"description": "nomo Mandate Test",
"start_date": "2024-04-29",
"end_date": "2024-05-30",
"redirect_url": "https://mono.co",
"retrial_frequency": 1,
"frequency": "weekly", // monthly, weekly, daily
"initial_debit_date": "2024-04-30",
"grace_period": 6,
"minimum_due": 20000, // if we are unable to debit the main amount, this minimum due is what we can collect from the account
"initial_debit_amount": 30000 // After the approval of the mandate, this is the first debit (OPTIONAL)
"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/RD9152019674",
"type": "recurring-debit",
"mandate_type": "emandate", // or "signed" or "gsm"
"amount": 200000,
"description": "nomo Mandate Test",
"reference": "nomo-test-24-04-24-02",
"customer": "6629259fe903b1",
"redirect_url": "https://mono.co",
"created_at": "2024-04-24T17:44:17.833Z",
"updated_at": "2024-04-24T17:44:17.833Z",
"start_date": "2024-04-29",
"end_date": "2024-05-30"
}
}
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.
Custom Frequencies
If you need to configure custom frequencies for a fixed mandate beyond the standard daily, weekly, bi-weekly, monthly, and yearly options, you can use days, weeks, or months as the frequency.
You can then set any whole number (e.g., 1, 5) in the interval field to specify the frequency.
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: