Notifications on Callback Url

The Merchant will receive notifications on the Callback URL with the final response containing the status of the transaction.

Notifications are sent as HTTPS POST requests with data in JSON format.

Based on these notifications, the Merchant must provide the service/product to the Customer.

Callback URL is a mandatory setting for every project opened in maibmerchants, but it can also be sent in the request when initiating a payment (callbackUrl parameter).

To receive notifications responses from maib ecomm following server IP addresses must be allowed in the merchant server firewall: 91.250.245.70 / 91.250.245.71 / 91.250.245.142

The notification is considered to be processed successfully by the merchant if HTTP 200 OK status returned. Otherwise maib ecomm will repeat notification attempts with such time intervals: 10, 60, 300, 600, 3600, 43200, 86400 seconds.

Example of receiving notifications on Callback URL (PHP)

<?php
$json = file_get_contents('php://input');
$data = json_decode($json);

Callback signature

In the notification (final response) the signature parameter will be present to verify the integrity and authenticity of the data.

Signature algorithm:

signature = Base64(sha256(Implode(Sort(Params) + SignatureKey, ':'))));

The Signature Key is available after activating the Project in maibmerchants.

Signature validation:

Example of notification (final response) on Callback URL:

{
"result": {
"payId": "f16a9006-128a-46bc-8e2a-77a6ee99df75",
"orderId": "123",
"status": "OK",
"statusCode": "000",
"statusMessage": "Approved",
"threeDs": "AUTHENTICATED",
"rrn": "331711380059",
"approval": "327593",
"cardNumber": "510218******1124",
"amount": 10.25,
"currency": "MDL"
},
"signature": "5wHkZvm9lFeXxSeFF0ui2CnAp7pCEFSNmuHYFYJlC0s="
}

1. Sort the data in the result object according to the alphabetical order of the parameters. Example:

"amount" => 10.25,
"approval" => "327593",
"cardNumber" => "510218******1124",
"currency" => "MDL",
"orderId" => "123",
"payId" => "f16a9006-128a-46bc-8e2a-77a6ee99df75",
"rrn" => "331711380059",
"status" => "OK",
"statusCode" => "000",
"statusMessage" => "Approved",
"threeDs" => "AUTHENTICATED"

1. Concatenate parameter values using the ":" sign with the Signature Key appended to the end. Example:

10.25:327593:510218******1124:MDL:123:f16a9006-128a-46bc-8e2a-77a6ee99df75:331711380059:OK:000:Approved:AUTHENTICATED:8508706b-3454-4733-8295-56e617c4abcf

1. Generate the hash of this string using the SHA256 function (binary format). Example:

e701e466f9bd945797c52785174ba2d829c0a7ba4210548d9ae1d81582650b4b

1. Base64 encode the received hash. Example:

5wHkZvm9lFeXxSeFF0ui2CnAp7pCEFSNmuHYFYJlC0s=

1. Compare the generated signature with the value of the signature parameter in the notification and if they match the signature will be considered valid (the received data is authentic and intact).

Example of signature validation (PHP)

<?php
$key = "8508706b-3454-4733-8295-56e617c4abcf"; //Signature Key from Project settings

$json = file_get_contents('php://input');
$data = json_decode($json, true);

if (isset($data['signature'])) {
$data_result = $data['result']; // Data from "result" object

function sortByKeyRecursive(array $array) {
    ksort($array, SORT_STRING);
    foreach ($array as $key => $value) {
        if (is_array($value)) {
            $array[$key] = sortByKeyRecursive($value);
        }
    }
    return $array;
}

function implodeRecursive($separator, $array) {
    $result = '';
    foreach ($array as $item) {
        $result .= (is_array($item) ? implodeRecursive($separator, $item) : (string)$item) . $separator;
    }

    return substr($result, 0, -1);
}

$sortedDataByKeys = sortByKeyRecursive($data_result); //Sort an array by key recursively
$sortedDataByKeys[] = $key; //Add Signature Key to the end of data array
$signString = implodeRecursive(':', $sortedDataByKeys); // Implode array recursively
$sign = base64_encode(hash('sha256', $signString, true)); // Generate signature 

if ($sign === $data['signature']) // Compare the generated signature with the received signature on Callback URL
{
  echo "Signature is valid!"; // Signature is valid, process the data
} else {
  echo "Signature is invalid!"; // Signature is invalid, reject the request
}
}