mono-logo

Direct Debit Webhook Events

Last updated May 20th, 2024

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 ready-to-debit 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

1234567891011121314151617181920212223242526272829
{
  "event": "events.mandates.created",
  "data": {
    "id": "mmc_664b428e362a3",
    "status": "initiated",
    "mandate_type": "emandate",
    "debit_type": "variable",
    "status": "successful",
    "ready_to_debit": false,
    "nibss_code": "RC/5008/4942090",
    "approved": false,
    "reference": "ZONO240520",
    "account_name": "Samuel Olamide",
    "account_number": "0100013078",
    "bank": "GTB TESTING",
    "customer": "664769512f321a8c",
    "description": "Mono TEST",
    "live_mode": false,
    "message": "The mandate has been successfully initiated and is awaiting
     customer approval. Once approved, you can begin debiting customers 
     based on the agreed terms",
    "start_date": "2024-09-12T00:00:00.000Z",
    "end_date": "2024-12-25T00:00:00.000Z",
    "date": "2024-05-20T12:31:10.481Z",
    "amount": 200020,
    "app": "662fd4468d1db5",
    "business": "60cc8f95bac5c6b1d"
  }
}
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

1234567891011121314151617181920212223242526
{
  "event": "events.mandates.approved",
  "data": {
    "id": "mmc_664b428362a3",
    "status": "approved",
    "mandate_type": "emandate",
    "debit_type": "variable",
    "ready_to_debit": false,
    "nibss_code": "RC/5008/4942090",
    "approved": true,
    "reference": "ZONO240520",
    "account_name": "Samuel Olamide",
    "account_number": "0100013078",
    "bank": "GTB TESTING",
    "customer": "664769512f321a8c",
    "description": "Mono TPS TEST",
    "live_mode": false,
    "message": "Mandate approved",
    "start_date": "2024-09-12T00:00:00.000Z",
    "end_date": "2024-12-25T00:00:00.000Z",
    "date": "2024-05-20T12:31:10.481Z",
    "amount": 200020,
    "app": "662fd49468d1db5",
    "business": "60cc8f95c5c6b1d"
  }
}
d. Mandate ready-to-debit event:

This webhook is triggered when a mandate has been approved and the account is ready to be debitted.

Request

123456789101112131415161718192021222324
{
  "event": "events.mandates.ready",
  "data": {
    "id": "mmc_66476972650cb58",
    "status": "approved",
    "mandate_type": "emandate",
    "debit_type": "variable",
    "ready_to_debit": true,
    "nibss_code": "RC000014/1000/00026",
    "approved": true,
    "reference": "ZONO2349416",
    "account_name": "SAMUEL OLAMIDE",
    "account_number": "0100013078",
    "bank": "GUARANTY TRUST BANK PLC",
    "description": "Mono TEST",
    "message": "Mandate is now ready for debiting",
    "start_date": "2024-08-12T00:00:00.000Z",
    "end_date": "2024-12-25T00:00:00.000Z",
    "date": "2024-05-17T14:28:09.034Z",
    "amount": 200000,
    "app": "662fd49d68d1db5",
    "business": "60cc8fc5c6b1d"
  }
}
e. 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"
  }
}
f. 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"
  }
}
g. Mandate reinstated event:

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

Request

123456789101112131415
{
  "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:

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

This processing webhook is sent to indicate a debit transaction is pending confirmation. When the transaction is finally confirmed as successful or failed, a webhook is sent and the status will be updated.

Request

12345678910111213141516171819202122232425262728
{
  "event": "events.mandates.debit.processing",
  "data": {
    "status": "processing",
    "message": "Payment is currently in processing state, please wait for a final state webhook before giving value",
    "event": "processing",
    "response_code": "99",
    "amount": 140000,
    "mandate": "mmc_66b724f8be2c101e38151234",
    "reference_number": "LBA3B086406D4851234A",
    "account_details": {
      "bank_code": "058",
      "account_name": "HASSAN ABDULHAMID TOMIWA",
      "account_number": "0123456789",
      "bank_name": "GUARANTY TRUST BANK PLC"
    },
    "beneficiary": {
      "bank_code": "000",
      "account_number": "P000001",
      "bank_name": "MONO SETTLEMENT WALLET"
    },
    "date": "2024-08-12T00:32:17.192Z",
    "live_mode": true,
    "app": "661fb072e5fcc75328866c9a",
    "business": "630c84e6059cbfc70fdaag15",
    "customer": "66b724f51a0fe7906d05d617"
  }
}
b. 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"
  }
}
c. 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?