Validating Payout Notification

As security best practice, there are several ways to ensure that the notification you are receiving is authentically coming from Midtrans Iris (not some external party impersonator).

Signature Key

For each HTTP notification, Midtrans is sending a “signature key”, which merchant 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.

Here’s the formula to validate the notification:

// `stringFromHttpNotificationBody` is HTTP body of the received Notification.
// `merchantKey` is merchant account's Iris Merchant Key, which merchant can retrieve from logging-in to Midtrans Dashboard.
Iris-Signature = SHA512( stringFromHttpNotificationBody + merchantKey )

// Note: `+` means "append" the two String, then input it into a SHA512 function.

Sample code to generate Iris-Signature key in some languages:

signature = OpenSSL::Digest::SHA512.new(string_from_notification_body + merchant_key).to_s

const crypto = require('crypto');
let stringFromHttpNotificationBody = '...'; 
let merchantKey = 'IRIS-merchant-xxx';
let irisSignature = crypto.createHash('sha512')
  .update(stringFromHttpNotificationBody + merchantKey).digest('hex');

console.log(irisSignature);
// You can also try this example by visiting: https://stackblitz.com/edit/node-azmunb?file=index.js

Example:

Let's suppose:

Merchant is receiving the following HTTP Notification request:

// HTTP header
Iris-Signature: 8b8a8ce380887acf162a17cc4bed7b7ff1c94fc637201ebed7ab1a7f32596810cbd9fc78d2db051ef851f97c05cd5f840d10ee34d58021c18d6ef69a793b7116

// HTTP Body
{"reference_no":"TLtXjaG7LxcbEhgo7S","amount":"12333.0","status":"processed","updated_at":"2023-03-31T10:12:28Z"}

The merchant’s Iris Merchant Key is IRIS-merchant-d8709d85-19d6-39c4-7ff5-8eaf81ec31cd

Let's calculate:

So the input string would be, Notification’s HTTP Body + Merchant Key:

{"reference_no":"TLtXjaG7LxcbEhgo7S","amount":"12333.0","status":"processed","updated_at":"2023-03-31T10:12:28Z"}IRIS-merchant-d8709d85-19d6-39c4-7ff5-8eaf81ec31cd

Then input that string into a SHA-512 function to get the calculated signature key:

8b8a8ce380887acf162a17cc4bed7b7ff1c94fc637201ebed7ab1a7f32596810cbd9fc78d2db051ef851f97c05cd5f840d10ee34d58021c18d6ef69a793b7116

Finally, compare the calculated signature with the Notification’s Iris-Signature HTTP headers. As the calculated signature key & Iris-Signature is the same, it means that the notification is authentic.

Challenge the Notification

An additional mechanism we provide to verify the content and the origin of the notification is to “challenge” the notification, which is to enquire back to Midtrans to ensure the actual status of a Payout. As the response will be coming directly from Midtrans, it ensure the authenticity. This can be achieved by calling the GET Payout Details API.