Key Processes

Monnify Direct Debit enables merchants to set up recurring payments by creating and activating mandates for customers. The process involves mandate creation, customer authorization, and mandate activation/debiting.

Mandate Management Workflow

A mandate is the agreement between a customer and a merchant that authorizes recurring debits.

Below are all possible mandate statuses:

Ways To Use

Depending on your business needs, mandates can be configured in four ways:

1. Open Flexible: Varying amounts, no end date. Example: utility company debiting based on usage.

2. Open Fixed: Fixed amount, no end date. Example: streaming subscription until cancelled.

3. Closed Flexible: Varying amounts with an end date. Example: car instalment plan over 12 months.

4. Closed Fixed: Fixed amount with an end date. Example: insurance premiums of ₦10,000 monthly for 12 months.

Mandate Creation & Activation Flow

Monnify routes mandates to the right provider depending on bank configuration:

• TeamApt: Used if the customer’s bank is enabled for the merchant on TeamApt. Mandates require customer authorization via the provided URL.

• NIBSS: Used if the bank is not enabled on TeamApt. NIBSS mandates are also authorized via URL for better experience. For testing, static instructions can be mocked.

The process has three steps: (1) create mandate, (2) customer authorizes mandate via authorization link, and (3) once activated, merchant can debit the account.

API Integration Workflow

Setting up a direct debit with Monnify follows a 5-step workflow. Each step corresponds to an API call or customer action in the mandate lifecycle.

1. Initiate Mandate Creation:
   Merchants send a request to the Create Mandate API with customer and mandate details.

2. Mandate Routing:
   Monnify automatically routes the mandate to the appropriate provider:

   • TeamApt → if the customer’s bank is enabled for the merchant on TeamApt.

   • NIBSS → if the bank is not enabled on TeamApt.

3. Mandate Creation:
   A unique mandateReference and authorization link are generated. The mandate status is set to PENDING_AUTHORIZATION. This link is valid for 30 days.

4. Customer Authorization:
   Merchants must share the authorization link with customers (via app, email, or SMS). The customer uses the link to provide consent and authorize the mandate.

5. Mandate Activation:

   • TeamApt mandates → Activated once the customer completes authorization via the URL.

     

   • NIBSS mandates → Preferably activated via the authorization URL for a smoother experience. Static instructions can be mocked for testing.

     

Sample API Response

1{
2"requestSuccessful": true,
3"responseMessage": "success",
4"responseCode": "0",
5"responseBody": [
6  {
7    "mandateCode": "MTDD|01K4PV33AMJ9GT1EF7XATZTWJB",
8    "mandateReference": "test_oogunboyejo_prod_32",
9    "startDate": "2025-09-09T01:46:30.000+00:00",
10    "endDate": "2025-11-25T09:15:30.000+00:00",
11    "mandateStatus": "PENDING_AUTHORIZATION",
12    "mandateAmount": 1000.00,
13    "autoRenew": true,
14    "customerPhoneNumber": "2348161116307",
15    "customerEmailAddress": "[email protected]",
16    "customerAddress": "12 Wole Ariyo",
17    "customerName": "123-_iop",
18    "customerAccountName": "OPEYEMI LUKMON ANIMASHAUN",
19    "customerAccountNumber": "0707206840",
20    "customerAccountBankCode": "044",
21    "mandateDescription": "Subscription Fee",
22    "debitAmount": null,
23    "authorizationMessage": "Please use activation link to authenticate the mandate.",
24    "authorizationLink": "https://mandate-verification.teamapt.com?sessionId=cdbc8961209b49f39d7eb2d4ae7170e3",
25    "responseMessage": "Mandate is awaiting customer authorization - https://mandate-verification.teamapt.com?sessionId=cdbc8961209b49f39d7eb2d4ae7170e3"
26  }
27]
28}

Key Notes for Merchants

• Bank Availability: Each merchant account is configured with specific banks enabled on either TeamApt or NIBSS. Confirm your setup.

• Authorization Links: Always share links with customers promptly so mandates are not delayed or expired.

• Testing with NIBSS: You can mock NIBSS mandates since the instructions are static.

• Essential APIs: Use the Create Mandate and Get Mandate Status APIs for integration.

Mandate APIs

1. Create Mandate:

   Create a mandate on the customer's bank account.

2. Get Mandate Status:

   Check the status of an existing mandate.

3. Debit Mandate:

   Debit the account linked to an activated mandate.

4. Get Debit Status:

   Check the debit status on a mandate.

5. Update Mandate:

   Cancel or update a mandate.

Sample Error Messages