Global Standing Mandate Guide

Overview

Global standing mandate (GSM) or Multiple Account Direct Debit enables payments to be deducted from any linked accounts with sufficient balance. If the primary mandated account lacks adequate funds, the system automatically attempts to collect the repayment from those linked accounts.

Prerequisites

Before you continue, make sure to complete the following essential steps:

• Register on the Mono dashboard. You can find a detailed guide here.

• Create an application with the product specified as "DirectPay" and obtain the associated secret key. Refer to the guide here for assistance.

• Create a customer with the customer creation guide here, if you have'nt yet done so already.

How it works

Setting up a Global standing Mandate is achieved in the following outlined steps:

1. GSM Mandate Type Initiation: This is where you specifiy the type of the mandate when initiating the direct debit widget where mandate_type is set to gsm.

2. Customer Setup and Confirmation: At this stage, the customer sets up the direct debit on their bank account(s) by confirming their bank account, verifing their Bank Verification Number (BVN) with the date of birth.

3. Funds Collection: After successful confirmation, funds are deducted from the main mandated account where the agreed loan repayment amount is setup, with a sweep conducted on other accounts if the main account debit fails.

Step 1: GSM Mandate Type Initiation

In this step, you are to initiate the GSM mandate via the Initiate a Mandate API. While iniitating, ensure to set mandate_type to 'gsm'. Kindly note that a GSM mandate can be created for both variable and fixed bank mandate types.

1. Fixed Guide Setup for GSM: The fixed gsm mandate is an ideal option for businesses that wants Mono as an entity to deduct funds automatically from the primary mandated account as well as all linked accounts with sufficient balances, with consistent amounts from their customers for a set period. Visit here to learn how to initiate a fixed GSM mandate type.

2. For Variable Guide Setup for GSM: GSM setup for this type allows your business to deduct variable funds primarily via the Debit Account API across a set period of time based on your own schedule. For every API attempt made, a debit is made on the primary mandated account first, if funds are insufficient, the remaining linked accounts in the background that have sufficient balances will be debited in the background. Visit here to know more on how to initiate a variable GSM mandate for your customers.

GSM Mandate Type Configuration

It's important to set mandate_type to "gsm" alongsides the other required body params when setting up a fixed or variable mandate type.

Step 2: Customer Setup and Confirmation

After a fixed or variable mandate has been initiated, a mono URL is returned in the response in which your user can confirm and authorise mandate approval. A rundown of the actions taken by the user is shared below:

a. Customer Account Linking - Your customer selects their bank type then proceeds to provide their account number, after which they then choose their type of account, which determines the verification flow. For a company account, only signatures are used for authorization.

b. Customer Identity Verification - The customer enters their Bank Verification Number (BVN) and date of birth. If these details are verified, the process moves to the next step.

c. Access to Multiple Accounts - In this step, an OTP is sent to the customer's phone or email to confirm all bank accounts linked to their BVN. Mono then sets up a signed mandate using the customer signature from step 4 on all the accounts except the main one entered in step 1.

d. Customer Mandate Authorization - The customer confirms the loan terms (e.g., amount, validity) and provides their signature to authorize the recovery of the loan from all their accounts if the main account is not funded.

e. Customer Account Ownership - For personal and businesse accounts, your customer will be asked to send 50N to a NIBSS designated account to complete the mandate setup after which a webhook is sent to your webhook url.

The setup of the direct debit is instant for personal accounts, allowing immediate loan disbursement. For company accounts, the process waits for bank approval after the mandate is signed.

GSM Mandate Approval Timeline

Once the 50 NGN has been confirmed into the NIBSS designated account, note that the main mandate account approval typically occurs within 1-3 minutes since its an e-mandate. For the linked accounts, approval can be within (1hr - 72hrs) depending on the bank.

Step 3: Funds Collection

Before funds collection can be done, after a successful confirmation of the NIBSS transfer, the GSM mandate must be in a ready to debit state. This state can be confirmed when the ready-to-debit (events.mandates.ready) webhook event is sent. After which funds can then be deducted from the main mandated account on the agreed loan repayment amount, with a sweep conducted on other accounts if the main account debit fails.

The list of all linked accounts or mandates as well as the resepective ready-to-debit statuses can be confirmed via API. You can read on to know how to achieve this.

Fetching Linked Mandates

By retrieving all linked mandates, you can confirm the ready to debit statuses on each via the Retrieve a mandate API with the mandate id.

Each mandate and their statuses can also be view confirmed on the Mono dashboard via here.

cURL Request:

curl --request GET \
     --url https://api.withmono.com/v3/payments/mandates/id \
     --header 'accept: application/json' \
     --header 'mono-sec-key: live_sk_your_secret_key'

API Response:

{
    "status": "successful",
    "message": "request completed successfully",
    "data": {
        "id": "mmc_66b513c139a0229aa1234567",
        "status": "initiated",
        "reference": "Reference0000012345",
        "amount": 50600,
        "balance": 50600,
        "mandate_type": "gsm",
        "debit_type": "variable",
        "account_name": "SAMUEL OLAMIDE",
        "account_number": "2212345678",
        "live_mode": true,
        "approved": false,
        "ready_to_debit": false,
        "nibss_code": "RC012345/4321/098765432",
        "institution": {
            "bank_code": "033",
            "nip_code": "000004",
            "name": "UNITED BANK FOR AFRICA PLC"
        },
        "customer": "66b1ef9f1a0fe7906d35432a",
        "narration": "Repayment for samuel olamide",
        "redirect_url": "https://mono.co",
        "linked_mandates": [
            {
                "account_name": "SAMUEL OLAMIDE",
                "account_number": "2099999999",
                "bank": "ZENITH INTERNATIONAL BANK PLC",
                "ready_to_debit": false
            },
            {
                "account_name": "SAMUEL OLAMIDE",
                "account_number": "0788888888",
                "bank": "ACCESS BANK PLC",
                "ready_to_debit": false
            },
            {
                "account_name": "SAMUEL OLAMIDE",
                "account_number": "0801234567",
                "bank": "ACCESS BANK PLC",
                "ready_to_debit": false
            },
            {
                "account_name": "SAMUEL OLAMIDE",
                "account_number": "3044444444",
                "bank": "POLARIS BANK",
                "ready_to_debit": false
            },
            {
                "account_name": "SAMUEL OLAMIDE",
                "account_number": "2012132923",
                "bank": "Globus Bank",
                "ready_to_debit": false
            },
            {
                "account_name": "SAMUEL OLAMIDE",
                "account_number": "8292910291",
                "bank": "FIRST CITY MONUMENT BANK PLC",
                "ready_to_debit": false
            }
        ],
        "total_linked_mandates": 7,
        "start_date": "2024-08-09T00:00:00.000Z",
        "end_date": "2024-10-30T00:00:00.000Z",
        "date": "2024-08-08T18:51:45.770Z"
    }
}

Debit Action for GSM Fixed Debit Type

If the fixed debit type method was used in the earlier GSM mandate type initiation setup on step 1, note that Mono will automatically run debits on the primary mandated account as well as all linked accounts with sufficient balances, based of the specified schedule provided on the Initiate a Mandate API.

Each processed debit can be confirmed via the Retrieve all Debit API. This can also be confirmed on the mandates history tab on the Mono dashboard here.

Debit Action for GSM Variable Debit Type

For variable debit type mandates were you can debit linked accounts via the mandate id on your schedule, you can proceed to call the Debit Account API as explained in this guide here under the "Debiting the account" section.

Note on Debiting Linked Account

For every attempt made for both Fixed and Variable mandate, a debit is made on the primary mandated account first, if funds are insufficient, the remaining linked accounts in the background that have sufficient balances will be debited in the background.

Webhook Confirmation

Note that the events.mandates.debit.success webhook event will be sent on each successful debit attempt.

{
  "event": "events.mandates.debit.success",
  "data": {
    "status": "successful",
    "message": "Account debited successfully.",
    "response_code": "00",
    "amount": 50000,
    "customer": "6570ee1115ddbc5528fea1c8",
    "mandate": "mmc_6571f4e55c7d1843d7d162e9",
    "reference_number": "Ah20141329b841234",
    "account_details": {
      "bank_code": "058",
      "account_name": "SAMUEL OLAMIDE",
      "account_number": "0123456789",
      "bank_name": "GUARANTY TRUST BANK PLC"
    },
    "beneficiary": {
      "bank_code": "000",
      "account_name": "Mono",
      "account_number": "P000001",
      "bank_name": "MONO SETTLEMENT WALLET"
    },
    "date": "2023-12-14T10:41:42.016Z",
    "app": "60cc8f95ba1772018c123456",
    "business": "60cc8f95ba1772018c123456"
  }
}