Global Standing Mandate Guide

Overview

The Global Standing Mandate (GSM) lets you recover funds from any BVN-linked account that has enough balance. If the primary mandated account does not have sufficient funds, the system automatically attempts collection from other linked accounts. The order in which the linked accounts are attempted is not guaranteed.

Prerequisites

To get started, you need to:

• Sign up on the Mono Dashboard and complete KYC.
• Create an app with the payments scope and retrieve the secret key.
• Configure a webhook URL in your dashboard to receive webhook event notifications. This guide will help you set up a webhook properly.

How it works

Setting up a GSM involves four key stages:

1. Mandate initiation: Specify the mandate type when you launch the Direct Debit widget by setting mandate_type to gsm.

2. Customer setup and confirmation: The customer confirms their bank account and verifies their BVN with date of birth. The customer also uploads their signature and sends NGN 50 to a NIBSS-designated account to complete the mandate setup.

3. Monitor mandate status: Check when linked accounts are approved and ready to debit.

4. Funds collection: Debit funds from the primary account or linked accounts based on your mandate type (fixed or variable).

Step 1: Mandate initiation

Initiate the Global Standing Mandate via the Initiate a Mandate API. Ensure the mandate_type is set to gsm.

GSM supports both fixed and variable debit types:

1. Fixed GSM: This is best when you want Mono to automatically debit the primary account and linked accounts with sufficient balances on a consistent schedule. Learn how to initiate a fixed GSM mandate here.

2. Variable GSM: This is used when you want to trigger debits on your schedule via the Debit Account API. Learn how to initiate a variable GSM here.

The API response includes a mono_url which you will use to redirect the user to the Mono mandate widget, where they can add additional details to complete the process.

{
    "status": "successful",
    "message": "Payment Initiated Successfully",
    "data": {
        "mono_url": "https://authorise.mono.co/RD9152019674",
        "mandate_id": "mmc_682b977203c0b7360787b460",
        "type": "recurring-debit",
        "mandate_type": "gsm",
        "amount": 200000,
        "description": "GSM 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"
    }
}

Step 2: Customer setup and confirmation

After initiating the mandate, a mono_url is returned in the response. Your customer uses this URL to confirm and authorize the mandate. Here's the flow the customer would take to complete the process:

• Account linking: Choose bank, enter account number, and select account type (Personal or Business).

• Identity verification: Enter BVN, then input the OTP sent to their phone to verify it. The Date of birth associated with the BVN is required to complete verification.

• Confirm mandate terms: Confirm and agree to the mandates terms such as amount, duration, etc.

• Signature upload: Upload or scan a signature to authorize the direct debit and approve other BVN-linked accounts.

• Ownership validation: Send NGN 50 to the NIBSS-designated account displayed on screen. A webhook is sent to your URL after confirmation, which approves the primary account.

Mandate approval timeline

Once the NGN 50 payment is confirmed, primary account approval typically completes within 1–3 minutes (e-mandate). Linked account approvals usually complete within 1–72 hours depending on the bank.

Step 3: Monitor mandate status

Before you can collect funds, the GSM must be ready to debit. This is indicated by the events.mandates.ready webhook event, which is sent after a 24-hour waiting period.

You can also check which accounts have been linked to the mandate and their ready_to_debit statuses via API.

Fetch linked mandates

Use the Retrieve a Mandate API with the mandate ID to see linked mandates and statuses. You can also view them on the Mono dashboard.

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'

Sample 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": "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": 5,
    "start_date": "2024-08-09T00:00:00.000Z",
    "end_date": "2024-10-30T00:00:00.000Z",
    "date": "2024-08-08T18:51:45.770Z"
  }
}

Step 4: Funds collection

Once the mandate is ready to debit (confirmed via the events.mandates.ready webhook), you can begin collecting funds. Mono debits the agreed amount from the primary account first. If the account doesn't have sufficient balance, the system automatically attempts the debit on an approved linked account.

Debit actions

• Fixed GSM: Mono automatically runs debits on the primary and linked accounts based on the schedule you provided when you initiated the mandate. Track processed debits via the Retrieve all Debits API or on the Mandates History tab in the dashboard here.

• Variable GSM: You trigger debits on your schedule by calling the Debit Account API as described here under Debiting the account.

Debiting linked accounts

Mono attempts the primary account first. If the balance is insufficient, GSM checks for an approved linked account with adequate balance and debits it.

Webhook confirmation

On each successful debit, you will receive the events.mandates.debit.successful webhook.

{
  "event": "events.mandates.debit.successful",
  "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",
    "fee_bearer": "business",
    "business": "60cc8f95ba1772018c123456"
  }
}