mono-logo

Direct Debit Webhook Events

Last updated December 15th, 2023

Overview

Our Direct Debit webhook events are categorised based on the following :

  1. Mandate webhook events.
  2. Debit webhook events.

1. Mandate webhook events

These are webhooks that are triggered when some specific direct debit mandate actions have been taken. We have itemised them down below:

  • Mandate created event.
  • Mandate rejected event.
  • Mandate approved event.
  • Mandate paused event.
  • Mandate cancelled event.
  • Mandate reinstated event.
a. Mandate-created event:

This webhook is sent when a direct debit mandate has been successfully created on your end.

Request

1234567891011121314151617181920212223
{
  "event": "events.mandates.created",
  "data": {
    "id": "mmc_657addc35350566f3483be17",
    "mandate_type": "signed",
    "debit_type": "variable",
    "status": "successful",
    "message": "Mandate created successfully and it's pending bank approval.This takes
     between 24-48 hours. If it's taking longer, ask customer to contact their bank.",
    "approved": false,
    "reference": "BONO1340491138399",
    "account_name": "SAMUEL OLAMIDE",
    "account_number": "0123456789",
    "bank": "GUARANTY TRUST BANK PLC",
    "customer": "60cc8f95ba1772018c123456",
    "description": "Mono subscriptions",
    "start_date": "2023-12-17T00:00:00.000Z",
    "end_date": "2024-05-25T00:00:00.000Z",
    "date": "2023-12-14T10:49:39.230Z",
    "app": "60cc8f95ba1772018c123456",
    "business": "60cc8f95ba1772018c123456"
  }
}
b. Mandate rejected event:

This webhook is triggered when a created direct debit mandate has been rejected.

Request

12345678910111213141516171819202122
{
  "event": "events.mandates.rejected",
  "data": {
    "id": "mmc_65795ef187e8bc6f0c112345",
    "mandate_type": "emandate",
    "debit_type": "variable",
    "status": "rejected",
    "approved": false,
    "reference": "TPS-blablaba-03",
    "account_name": "SAMUEL OLAMIDE",
    "account_number": "0123456789",
    "bank": "ZENITH INTERNATIONAL BANK PLC",
    "customer": "60cc8f95ba1772018c123456",
    "description": "Mono subscriptions",
    "message": "Mandate was rejected by Bank",
    "start_date": "2023-12-13T00:00:00.000Z",
    "end_date": "2024-05-25T00:00:00.000Z",
    "date": "2023-12-13T08:36:17.114Z",
    "app": "60cc8f95ba1772018c123456",
    "business": "60cc8f95ba1772018c123456"
  }
}
c. Mandate approved event:

This webhook is triggered when a created direct debit mandate has been successfully approved.

Request

12345678910111213141516171819202122
{
  "event": "events.mandates.approved",
  "data": {
    "id": "mmc_65795ef187e8bc6f0c112345",
    "mandate_type": "emandate",
    "debit_type": "variable",
    "status": "approved",
    "approved": true,
    "reference": "TPS-blablaba-03",
    "account_name": "SAMUEL OLAMIDE",
    "account_number": "0123456789",
    "bank": "ZENITH INTERNATIONAL BANK PLC",
    "customer": "65795e4ccbb2025a8e123456",
    "description": "Mono subscriptions",
    "message": "Mandate was approved",
    "start_date": "2023-12-13T00:00:00.000Z",
    "end_date": "2024-05-25T00:00:00.000Z",
    "date": "2023-12-13T08:36:17.114Z",
    "app": "65785e0d245062d3bd123456",
    "business": "60cc8f95ba1772018c123456"
  }
}
d. Mandate paused event:

When a direct debit mandate has been paused, the webhook below is triggered.

Request

123456789101112131415
{
  "event": "events.mandate.action.pause",
  "data": {
    "mandate": "mmc_6571f4e55c7d1843d7d162e9",
    "status": "success",
    "response_code": "",
    "message": "This mandate is now paused and can't be used for debit 
    or balance inquiry, but you can reinstate it back.",
    "timestamps": "2023-12-14T10:40:47.713Z",
    "documentation": "https://mono.co/docs/error-codes/400",
    "data": null,
    "app": "60cc8f95ba1772018c123456",
    "business": "60cc8f95ba1772018c123456"
  }
}
e. Mandate cancelled event:

This webhook is triggered when a created/approved direct debit mandate has been cancelled.

Request

1234567891011121314
{
  "event": "events.mandate.action.cancel",
  "data": {
    "mandate": "mmc_6579495142cc7e8894f6e031",
    "status": "success",
    "response_code": "",
    "message": "This mandate is now cancelled and deleted, and can’t be used again",
    "timestamps": "2023-12-14T10:34:30.114Z",
    "documentation": "https://mono.co/docs/error-codes/400",
    "data": null,
    "app": "60cc8f95ba1772018c123456",
    "business": "60cc8f95ba1772018c123456"
  }
}
f. Mandate reinstated event:

When a direct debit mandate has been paused, we send the webhook below when this mandate has been reinstated.

Request

1234567891011121314
{
  "event": "events.mandate.action.reinstate",
  "data": {
    "mandate": "mmc_6571f4e55c7d1843d7d162e9",
    "status": "success",
    "response_code": "",
    "message": "The mandate has been reinstated successfully and is now active for debit and balance inquiry",
    "timestamps": "2023-12-14T10:40:19.322Z",
    "documentation": "https://mono.co/docs/error-codes/400",
    "data": null,
    "app": "60cc8f95ba1772018c123456",
    "business": "60cc8f95ba1772018c123456"
  }
}

2. Debit webhook events

When a direct debit action is taken, either of the two results below will be shared:

  • Successful direct debit event.
  • Failed direct debit event.
a. Successful direct debit event:

The webhook below is sent whenever an account has been debited successfully

Request

123456789101112131415161718192021222324252627
{
  "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"
  }
}
b. Failed direct debit event:

This webhook is sent whenever a direct debit process performed is failed.

Request

123456789101112131415161718192021222324252627
{
  "event": "events.mandates.debit.failed",
  "data": {
    "status": "failed",
    "message": "",
    "response_code": "96",
    "amount": 50000,
    "customer": "6570ee1115ddbc5528fea1c8",
    "mandate": "mmc_6571f4e55c7d1843d7d162e9",
    "reference_number": "Ah20141329b841841",
    "account_details": {
      "bank_code": "058",
      "account_name": "SAMUEL OLAMIDE",
      "account_number": "0123456789",
      "bank_name": "GUARANTY TRUST BANK PLC"
    },
    "beneficiary": {
      "bank_code": "000",
      "account_name": "SAMUEL OLAMIDE",
      "account_number": "P000000",
      "bank_name": "MONO SETTLEMENT WALLET"
    },
    "date": "2023-12-14T10:41:42.016Z",
    "app": "60cc8f95ba1772018c123456",
    "business": "60cc8f95ba1772018c123456"
  }
}

Did this page help you?