HTTP(s) Notification is sent to your server when there is an update on the payout status or when a top up happens. These notifications help you to receive real time notifications about Payouts related information (payout, top up, etc). Partner can use the merchant’s IRIS merchant server key to verify the signature.
HTTP Notification
There are 2 types of HTTP notifications that Midtrans sends: payout notification and top up notification. Some sample HTTP notifications for a successful top up and different payout status are given below.
| Key | Type |
|---|---|
| Kind | HTTP Request |
| Request Method | POST |
| Request Header | Content-Type: application/json |
| Request Body | String of JSON |
Sample HTTP Notification for Successful Top Up
| Field | Type | Description |
|---|---|---|
| transaction_id | String | Unique id generated by Midtrans for top up to Bank |
| order_id | String | Unique id generated by Payouts |
| gross_amount | String | Amount topped up |
| status | String | This value will always be “topup” |
| transaction_time | String | Transaction time in ISO8601 format |
Sample HTTP Notification for Completed Payout
| Field | Type | Description |
|---|---|---|
| reference_no | String | Unique reference number of a payout |
| amount | String | Amount of the processed payout |
| status | String | Status of the payout, please refer to here as reference. |
| updated_at | String | Payout status update time in ISO8601 format |
| error_code | String | In case payout is failed we will send an error code related to the failed payout |
| error_message | String | In case payout is failed we will send an error message related to the failed payout |
Payout Status Definition table
| Payout Status | Description |
|---|---|
| approved | Payout request is approved by approver user |
| rejected | Payout rejected due to error on validation |
| processed | Payout request is sent to the bank and currently being processed by the bank. There are 2 kind of processed status: If it's a payout using SKN/RTGS, processed means we have sent the request to the respected bank, and it's currently being processed on the bank side and will be updated to be either completed or failed on the same working day before midnight. If the disbursement request has issues on the bank side, the merchant will also receive processed status, whereby we need to do reconciliation and the status will be updated to either completed or failed on D+1 working day. |
| completed | Payout request is sent to the bank and received by beneficiary account. |
| failed | Payout didn't go through |
Verifying Signature Key
For each HTTP notification, Midtrans is sending a “signature key”, which merchants can retrieve from the notification’s HTTP headers of Iris-Signature. The purpose of this signature key is to validate whether the notification originated from Midtrans or not. If the notification is validated to be not authentic, merchants can disregard the notification.
The logic to generate or calculate signature_key is explained below:
Iris Merchant Key:
SHA512(stringFromHttpNotificationBody+IrisMerchantKey)It basically means append the value of the HTTP body of the received Notification and IrisMerchantKey into one string, then use it as input to the SHA512 hash function. Then the output should match with signature_key from notification.
Example Payout Callback
| POST https://merchant.com/iris-merchant-callback Content-Type: application/json { "reference_no": "TLtXjaG7LxcbEhgo7S", "amount": "12333.0", "status": "processed", "updated_at": "2023-03-31T10:12:28Z" } |
|---|