Transaction Completion Webhook

Once you have successfully reserved an account, it’s important you implement a webhook URL. This is how we notify you when a transfer is done to that account. To implement a webhook, you simply need to create an endpoint that accepts post requests and can calculate a HASH value for security. Here is what we send to your webhook URL:

For information on how to calculate the transactionHash click here. Test your webhook here by doing a test transfer to an active monnify account number. 

Here is what a sample post to your webhook URL will look like:

Webhook Notification Data - Account Transfer

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 { "transactionReference": "MNFY|20200900003149|000000", "paymentReference": "MNFY|20200900003149|000000", "amountPaid": "180000.00", "totalPayable": "180000.00", "settlementAmount": "179989.25", "paidOn": "09/09/2020 11:31:56 AM", "paymentStatus": "PAID", "paymentDescription": "Ojinaka Daniel", "transactionHash": "a294a0bfxxxxxxxxxxxxxxxxxxxx0b399cf077e30cf2ad54a7da9e17583deb5130286e6bb5dxxxx353f027725b83fcafac02d2e181f53edd5f", "currency": "NGN", "paymentMethod": "ACCOUNT_TRANSFER", "product": { "type": "RESERVED_ACCOUNT", "reference": "7b3xxxx072a44axxxxxxx2b6c2374458" }, "cardDetails": null, "accountDetails": { "accountName": "John Ciroma Abuh", "accountNumber": "******4872", "bankCode": "000015", "amountPaid": "180000.00" }, "accountPayments": [{ "accountName": "John Ciroma Abuh", "accountNumber": "******4872", "bankCode": "000015", "amountPaid": "180000.00" }], "customer": { "email": "dojinaka@monnify.com", "name": "Daniel Ojinaka" }, "metaData": {} }

Webhook Notification Data - Card Payment

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 { "transactionReference":"MNFY|20190920113413|000224", "paymentReference":"1568979249981", "amountPaid":"100.00", "totalPayable":"100.00", "settlementAmount" : "99.25", "paidOn":"20/09/2019 11:35:21 AM", "paymentStatus":"PAID", "paymentDescription":"Is it working", "transactionHash":"5a91ef93b91a0bfda95a19c18da4504506ba20f79d6c0fb9ec3907b56635e7b01360e2a9ffcb5bc1e1208df68688a6d0ce064bec968099d7466818b6826cfd66", "currency":"NGN", "paymentMethod":"CARD", "product":{ "type":"WEB_SDK", "reference":"1568979249981" }, "cardDetails":{ "cardType":null, "authorizationCode":null, "last4":"6871", "expMonth":"08", "expYear":"22", "bin":"539941", "reusable":false }, "accountDetails": null, "accountPayments": null, "customer":{ "email":"stephen@ikhane.com", "name":"Stephen Ikhane" }    "metaData" : { }  }

Get Transaction Status

We recommend that you make a get transaction status call using the transactionReference or paymentReference before persisting the transaction status on your database. For information on how to get the status of a transaction, click here.

Transaction Uniqueness

Please make sure that you only handle notifications once for every payment reference or transaction reference. Payment references and transaction references are unique so if you receive multiple notifications for a single transaction please do not honor it. This could be a  glitch or someone trying to game your endpoint.

Deprecated Notifications

For documentation on the old deprecated webhook notifications click here.

Field Reference

(M) indicates fields that are mandatory in the request body. (m) Indicates fields that are mandatory only if the parent object is not empty.

Field

Description

Field

Description

totalPayable (M)

The amount to be paid by the customer

amountPaid

The exact amount paid by the customer

paymentStatus

Payment Status. Should always be `PAID` for reserved accounts. 

settlementAmount

The amount settled to the merchant. This is the amount paid minus the merchants' fee. 

paymentDescription

Defaults to the account name

transactionHash

Hash calculated and sent by Monnify with each notification request. Merchant is expected to calculate the Hash using the request body. If the hash values don’t match, please do not honor the notification request. 

currencyCode (M)

The currency of the transaction being initialized. "NGN"

paymentMethod

The method used by the customer to process the transaction `ACCOUNT_TRANSFER` of `CARD`

product

The object containing information specific to the product being used.

product.type

The monnify product in use for this payment e.g. Web_SDK, Reserved_Account, Invoice, etc.

product.reference

The unique reference applicable to the product e.g. Account_Reference, Invoice Reference, payment reference, etc.

cardDetails

The object containing information specific to the card used for payment. Will only be populated if the payment method was a card. else it will be null

cardDetails.cardType

Card type (VISA, MASTER, VERVE)

cardDetails.authorizationCode

Transaction authorization code

cardDetails.last4

Last 4 digits of the card

cardDetails.expMonth

Expiry month of the card following DATE convention i.e. January is 00 and December is 11.

cardDetails.expYear

Expiry year of the card in YYYY format

cardDetails.bin

First 6 digits of the card

cardDetails.reusable

Boolean to specify if the authorizationCode is reusable

accountDetails

The object containing information specific to the sender's bank information. Will only be populated if the payment method was ACCOUNT_TRANSFER. else it will be null

accountDetails.accountNumber

Source account number for that transaction. This is the account number the customer transferred from during payment.

accountDetails.accountName

Source account name for that transaction. This is the account name of the account the customer transferred from during payment.

accountDetails.bankCode

Bank code of the source bank where the customer transferred from. 

accountPayments

An array of accountDetails objects. Useful when multiple transfers were made for one transaction.

customer

The object containing the customer information

customer.customerName

Full name of the customer

customer.customerEmail

The email address of the customer