Direct Debit Integration Guide: Mandate Setup
Last updated Jan 22nd, 2025
Step 2: Setup bank mandate
As a partner, you can set up a mandate on either personal accounts or business accounts using the two authorisation types: E-mandate and Signed mandate. Select your preferred method for initiating mandates from the available endpoints.
Mandate Initiation Endpoints
- Create mandate endpoint: This allows you to customise the initial mandate setup experience for your users.
- Initiate mandate link endpoint: This generates a link to widget for your users to complete the mandate setup process.
More information on Mandates Authorisation Types :
i. E-mandate: In this type of mandate, the payer is provided with two account numbers (i.e Fidelity and Paystack-Titan accounts) as authorization transfer accounts when creating Direct Debit e-mandates, which requires funding of N50 to complete the approval process. The N50 charged for this process can't be modified, this fee goes to NIBSS.
Banks charging minimum of N100 for mandate approval
Certain bank apps have a minimum transfer amount of N100, hence, users will not be able to transfer N50 for authorization for the following banks:
- Unity Bank
- Union Bank
- Standard Chartered Bank
E-Mandate Flow
- Mandate is created → Awaiting Authorization
- User opens the link and starts the authorization process → Initiated
- Mandate authorization transfer has been successfully completed → Approved
- Mandate authorization transfer failed or there was a downtime affecting approvals → Cancelled
ii. Signed mandate: On the other hand, for a signature mandate, the user must provide a signature for approval, and the payer's bank typically contacts the payer to confirm the mandate's approval.
Physical Signed Mandate Flow
- Mandate form is uploaded → Initiated
- Mandate has been sent to the bank for processing → Authorized
- Mandate has been approved by the bank → Approved
- Mandate has been rejected by the bank → Rejected
Digital Signed Mandate Flow
- Mandate is created → Awaiting Authorization
- User opens the link and starts the authorization process → Initiated
- Mandate has been sent to the bank for processing → Authorized
- Mandate has been approved by the bank → Approved
- Mandate has been rejected by the bank → Rejected
Re: E-mandates
- It's important to note that the account the E-mandate is being set up on MUST be used for the ₦50 funding. This funding acts as the customer's approval of the mandate. If the user fails to send the ₦50 the mandate will be inactive and unapproved
- Your customer can choose either Fidelity or Paystack-Titan accounts as the authorization transfer accounts when creating Direct Debit e-mandates. This bank accounts are returned in the transfer_destinations field under the data objects.
- Note that the ₦50 transfer must come from the bank account that requires mandate setup.
- The user must send the ₦50 money within 1 hour, else the mandate will be cancelled and they have to create another mandate again.
- When such mandate is cancelled, the mandate cancelled event (events.mandate.action.cancel) is sent with the reason for cancellation included in the response.
Re: Ready To Debit Status
Please note that after sending an NGN 50 amount to a NIBSS-provided account, the mandated account will enter a "ready-to-debit" status within approximately 3 hours for an E-Mandate. This ensures faster transaction processing, significantly reducing waiting times. A ready-to-debit webhook event will be sent to confirm when the account is ready for debiting.
For example, if a mandate is created and approved at 4:00 PM, the account will be ready for debiting by 7:00 PM.
Re: Debit Types & Amount
variable: When debit type is
variabletheamountis the total debit/money a business plans to retrieve from a customer over the set period. Debits can be variedfixed: When debit type is
fixedtheamountis that which the business wants to retrieve per debit and then the total debit is automatically calculated based on that amount. Note that once the fixed amount is set on mandate authorisation, it is immutable.
NIBSS Code
Every mandate returns a NIBSS code is generated by NIBSS. This can be used to track mandates in cases that require further investigation
To set up a mandate on the customer's bank account, send a POST request to the following endpoint:
Request
POST https://api.withmono.com/v2/payments/initiate