On completion of certain actions on your integration, a notification would be sent to your system informing you of the action and expecting to trigger corresponding activities on your system as deemed fit.

You can specify urls for certain activities on your integration and events will be sent to that url with an event type property indicating what action has taken place and event data containing the details of the event.

It’s highly recommended you check our Best Practices when processing webhooks

A typical structure of the payload is as indicated below:

{
  "eventType": "type_of_event",
  "eventData": {
    "prop1": "value1",
    "prop2": "value2"
  }
}

Supported Event Types

  1. Successful Collection: A successful payment was made on your account. This could be card, account transfer or cash payments.

  2. Successful Disbursement: This is sent when a disbursement transaction has a successful definite status.

  3. Failed Disbursement: This is sent when a disbursement transaction fails.

  4. Successful Refund: This is sent when an initiated refund has been processed successfully.

  5. Failed Refund: This is sent when an initiated refund fails.

  6. Settlement Completion: This is sent when settlement to your bank account or wallet is processed successfully.

Click on each event type below to reveal request structure.

{
  "eventType": "SUCCESSFUL_TRANSACTION",
  "eventData": {
    "product": {
      "reference": "1636106097661",
      "type": "RESERVED_ACCOUNT"
    },
    "transactionReference": "MNFY|04|20211117112842|000170",
    "paymentReference": "MNFY|04|20211117112842|000170",
    "paidOn": "2021-11-17 11:28:42.615",
    "paymentDescription": "Adm",
    "metaData": {},
    "paymentSourceInformation": [
      {
        "bankCode": "",
        "amountPaid": 3000,
        "accountName": "Monnify Limited",
        "sessionId": "e6cV1smlpkwG38Cg6d5F9B2PRnIq5FqA",
        "accountNumber": "0065432190"
      }
    ],
    "destinationAccountInformation": {
      "bankCode": "232",
      "bankName": "Sterling bank",
      "accountNumber": "6000140770"
    },
    "amountPaid": 3000,
    "totalPayable": 3000,
    "cardDetails": {},
    "paymentMethod": "ACCOUNT_TRANSFER",
    "currency": "NGN",
    "settlementAmount": "2990.00",
    "paymentStatus": "PAID",
    "customer": {
      "name": "John Doe",
      "email": "test@tester.com"
    }
  }
}
{
  "eventData": {
    "product": {
      "reference": "596048268",
      "type": "WEB_SDK"
    },
    "transactionReference": "MNFY|23|20211117124920|042042",
    "paymentReference": "596048268",
    "paidOn": "2021-11-17 12:50:19.269",
    "paymentDescription": "Pay With Monnify",
    "metaData": {
      "name": "Damilare",
      "age": "45"
    },
    "paymentSourceInformation": [],
    "destinationAccountInformation": {},
    "amountPaid": 100,
    "totalPayable": 100,
    "cardDetails": {
      "last4": "2718",
      "expMonth": "10",
      "expYear": "22",
      "bin": "506102",
      "reusable": false
    },
    "paymentMethod": "CARD",
    "currency": "NGN",
    "settlementAmount": "98.71",
    "paymentStatus": "PAID",
    "customer": {
      "name": "",
      "email": "ore2@monnify.com"
    }
  },
  "eventType": "SUCCESSFUL_TRANSACTION"
}
{
  "eventType": "SUCCESSFUL_DISBURSEMENT",
  "eventData": {
    "amount": 10,
    "transactionReference": "MFDS|20210317032332|002431",
    "fee": 8,
    "transactionDescription": "Approved or completed successfully",
    "destinationAccountNumber": "0068687503",
    "sessionId": "090405210317032336726272971260",
    "createdOn": "17/03/2021 3:23:32 AM",
    "destinationAccountName": "DAMILARE SAMUEL OGUNNAIKE",
    "reference": "ref1615947809303",
    "destinationBankCode": "232",
    "completedOn": "17/03/2021 3:23:38 AM",
    "narration": "This is a quite long narration",
    "currency": "NGN",
    "destinationBankName": "Sterling bank",
    "status": "SUCCESS"
  }
}
{
  "eventType": "FAILED_DISBURSEMENT",
  "eventData": {
    "amount": 1001,
    "transactionReference": "MFDS|20210317032705|002433",
    "fee": 8,
    "destinationAccountNumber": "0068687503",
    "sessionId": "",
    "createdOn": "17/03/2021 3:27:05 AM",
    "destinationAccountName": "DAMILARE SAMUEL OGUNNAIKE",
    "reference": "ref1615948022891",
    "destinationBankCode": "232",
    "completedOn": "17/03/2021 3:32:09 AM",
    "narration": "This is a quite long narration",
    "currency": "NGN",
    "destinationBankName": "Sterling bank",
    "status": "FAILED"
  }
}
{
  "eventType" : "REVERSED_DISBURSEMENT",
  "eventData" : {
    "transactionReference" : "MFDS20210629125410AAAADP",
    "reference" : "ref1624967649578",
    "narration" : "911 Transaction",
    "currency" : "NGN",
    "amount" : 10.00,
    "status" : "REVERSED",
    "fee" : 1.00,
    "destinationAccountNumber" : "0700306714",
    "destinationAccountName" : "MEKILIUWA SMART CHINONSO",
    "destinationBankCode" : "101",
    "sessionId" : "ATL210629AABGPF",
    "createdOn" : "29/06/2021 12:54:10 PM",
    "completedOn" : "29/06/2021 12:54:12 PM"
  }
}
{
  "eventType": "SUCCESSFUL_REFUND",
  "eventData": {
    "merchantReason":"defective goods",
    "transactionReference":"MNFY|20190816083102|000021",
    "completedOn":"14/04/2021 4:24:05 PM",
    "refundStatus":"COMPLETED",
    "customerNote":"defects",
    "createdOn":"14/04/2021 4:23:37 PM",
    "refundReference":"ref001",
    "refundAmount":10:00
  }
}
{
  "eventType": "FAILED_REFUND",
  "eventData": {
    "merchantReason":"defective goods",
    "transactionReference":"MNFY|20190816083102|000021",
    "completedOn":"14/04/2021 4:24:05 PM",
    "refundStatus":"FAILED",
    "customerNote":"defects",
    "createdOn":"14/04/2021 4:23:37 PM",
    "refundReference":"ref001",
    "refundAmount":10:00
  }
}
{
  "eventData": {
    "amount": "1199.00",
    "settlementTime": "11/11/2021 02:29:00 PM",
    "settlementReference": "LB8HG1PNZT4ATJGZXQBY",
    "destinationAccountNumber": "6000000249",
    "destinationBankName": "Fidelity Bank",
    "destinationAccountName": "Teamapt Limited234",
    "transactionsCount": 1,
    "transactions": [
      {
        "product": {
          "reference": "2134565wda",
          "type": "2134565wda"
        },
        "transactionReference": "MNFY|26|20211111142601|000001",
        "paymentReference": "MNFY|26|20211111142601|000001",
        "paidOn": "11/11/2021 02:26:02 PM",
        "paymentDescription": "Seg",
        "accountPayments": [
          {
            "bankCode": "000014",
            "amountPaid": "1234.00",
            "accountName": "Okeke Chimezie",
            "accountNumber": "******1070"
          }
        ],
        "amountPaid": "1234.00",
        "totalPayable": "1234.00",
        "accountDetails": {
          "bankCode": "000014",
          "amountPaid": "1234.00",
          "accountName": "Okeke Chimezie",
          "accountNumber": "******1070"
        },
        "cardDetails": {},
        "paymentMethod": "ACCOUNT_TRANSFER",
        "currency": "NGN",
        "paymentStatus": "PAID",
        "customer": {
          "name": "Segun Adeponle",
          "email": "segunadeponle@gmail.com"
        }
      }
    ]
  },
  "eventType": "SETTLEMENT"
}
{
  "eventData": {
    "product": {
      "reference": "MNF-Tl9Noo0G48000890",
      "type": "OFFLINE_PAYMENT_AGENT"
    },
    "transactionReference": "MNFY|76|20230830171357|000252",
    "invoiceReference": "MNF-Tl9Noo0G48000890",
    "paymentReference": "MNF-Tl9Noo0G48000890",
    "paidOn": "30/08/2023 5:13:57 PM",
    "paymentDescription": "adron",
    "metaData":{
      "phoneNumber":"08088523241",
      "name":"Khalid"
    },
    "destinationAccountInformation": {},
    "paymentSourceInformation": {},
    "amountPaid": 15000,
    "totalPayable": 15000,
    "offlineProductInformation": {
      "amount": 15000,
      "code": "56417",
      "type": "INVOICE"
    },
    "cardDetails": {},
    "paymentMethod": "CASH",
    "currency": "NGN",
    "settlementAmount": 14990,
    "paymentStatus": "PAID",
    "customer": {
      "name": "David Customer",
      "email": "mayluv55@hotmail.co.uk"
    }
  },
  "eventType": "SUCCESSFUL_TRANSACTION"
}

The "rejectionReason" parameter contains the reason for rejection which can be any of the following;

UNDER_PAYMENT,OVER_PAYMENT and ACCOUNT_NOT_IN_USE

{
  "eventData": {
    "metaData": "{"name":"Marvelous","age":"90"}",
    "product": {
      "reference": "MNFY|PAYREF|GENERATED|1687798434397393735",
      "type": "WEB_SDK"
    },
    "amount": 100,
    "paymentSourceInformation": {
      "bankCode": "50515",
      "amountPaid": 40,
      "accountName": "MARVELOUS BENJI",
      "sessionId": "090405230626180003067844645188",
      "accountNumber": "5141901487"
    },
    "transactionReference": "MNFY|85|20230626175354|041855",
    "created_on": "2023-06-26 17:53:55.0",
    "paymentReference": "MNFY|PAYREF|GENERATED|1687798434397393735",
    "paymentRejectionInformation": {
      "bankCode": "035",
      "destinationAccountNumber": "7023576853",
      "bankName": "Wema bank",
      "rejectionReason": "UNDER_PAYMENT",
      "expectedAmount": 100
    },
    "paymentDescription": "lets pay",
    "customer": {
      "name": "Marvelous Benji",
      "email": "benji71@gmail.com"
    }
  },
  "eventType": "REJECTED_PAYMENT"
}