Webhook Events and Request Structure

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

Successful Collection: A successful payment was made on your account. This could be card, account transfer or cash payments.
Successful Disbursement: This is sent when a disbursement transaction has a successful definite status.
Failed Disbursement: This is sent when a disbursement transaction fails.
Successful Refund: This is sent when an initiated refund has been processed successfully.
Failed Refund: This is sent when an initiated refund fails.
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.

Account Transfer Payment Received

{
  "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"
    }
  }
}

Card Transaction Completion

{
  "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"
}

Successful Disbursement

{
  "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"
  }
}

Failed Disbursement

{
  "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"
  }
}

Reversed Disbursement

{
  "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"
  }
}

Successful Refund

{
  "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
  }
}

Failed Refund

{
  "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
  }
}

Settlement

{
  "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"
}

Offline Payment

{
  "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"
}{
    "eventData": {
        "product": {
            "reference": "TEST0011",
            "type": "OFFLINE_PAYMENT_AGENT"
        },
        "transactionReference": "MNFY|57|20220207092215|000002",
        "paymentReference": "OP_DEP|MP|AGENT|83889DF8E79F2498D1D41C956E919A62|1490601789912645632",
        "paidOn": "07/02/2022 9:22:15 AM",
        "paymentDescription": "SEUN TESTER-LKJ001TEST",
        "metaData": {},
        "destinationAccountInformation": {},
        "paymentSourceInformation": {},
        "amountPaid": 100,
        "totalPayable": 100,
        "offlineProductInformation": {
            "amount": 100,
            "code": "53249",
            "type": "FIXED"
        },
        "cardDetails": {},
        "paymentMethod": "CASH",
        "currency": "NGN",
        "settlementAmount": 96,
        "paymentStatus": "PAID",
        "customer": {
            "name": "SEUN TESTER-LKJ001TEST",
            "email": "TEST0011@YKCKCCNJUJGP.monnify"
        }
    },
    "eventType": "SUCCESSFUL_TRANSACTION"

Rejected Payment

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"
}