Notifications on Callback URL

The merchant will receive notifications on the Callback URL with the final payment response, which contains the transaction status and relevant details (e.g., qrStatus, payId, amount, etc).

Based on these notifications, the merchant must ensure the delivery of the service or product to the buyer.

A notification is considered successfully received if the merchant’s server responds with HTTP status code 200 OK.

---

Notification structure (Example)

{
  "result": {
    "qrId": "123e4567-e89b-12d3-a456-426614174000",
    "qrStatus": "Active",
    "orderId": "123",
    "payId": "6d24e4a5-c6bf-4d3e-bf7a-8d2123faf4e9",
    "amount": 10,
    "commission": 2.50,
    "currency": "MDL",
    "payerName": "John D.",
    "payerIban": "MD88AG000000011621810140",
    "executedAt": "2024-11-29T10:56:52.1380956+00:00",
    "signature": "592b6999-fdd0-4fd3-9708-5cb9df590dee"
  },
  "ok": true
}

Signature validation

To verify the integrity and authenticity of the received data, the Merchant must validate the signature field from the result object using the following algorithm:

1. Alphabetically sort all fields in the result object, excluding the signature field.

2. Ignore fields that have a null value or an empty string (""). These fields should be excluded entirely from the signature generation process, as if they do not exist.

3. Format amount fields (amount, commission) using exactly two decimal places (e.g., 0.50, 2.31) before concatenation.

4. Concatenate the remaining parameter values using a colon (:) as a separator, in the sorted order.

5. Append the Signature Key (available in the project settings in maibmerchants) to the end of the concatenated string.

6. Generate a SHA-256 hash in binary format from the resulting string.

7. Encode the binary hash using Base64 (or another format as specified in the official QR MIA documentation).

8. Compare the resulting encoded signature with the signature value received in the notification.

---

Signature validation example

<?php
$key = "signature-key-from-project-settings"; // Signature Key obtained from maibmerchants

// Get the JSON content received on the Callback URL
$json = file_get_contents('php://input');
$data = json_decode($json, true);

if (isset($data['result']['signature'])) {
    $signatureReceived = $data['result']['signature'];
    $dataResult = $data['result'];

    // Remove the signature from the data to be validated
    unset($dataResult['signature']);

    // Alphabetically sort the fields in the result object
    ksort($dataResult, SORT_STRING);

    // Recursive function to concatenate values with ':' separator
    function implodeRecursive($separator, $array) {
        $result = '';
        foreach ($array as $item) {
            if (is_array($item)) {
                $result .= implodeRecursive($separator, $item) . $separator;
            } else {
                $result .= (string)$item . $separator;
            }
        }
        return substr($result, 0, -1); // remove the last separator
    }

    // Build the signature string
    $signString = implodeRecursive(':', $dataResult) . ':' . $key;

    // Generate binary SHA256 hash
    $hash = hash('sha256', $signString, true);

    // Encode the hash in Base64
    $signatureCalculated = base64_encode($hash);

    // Compare the calculated signature with the received one
    if ($signatureCalculated === $signatureReceived) {
        http_response_code(200);
        echo "Signature is valid.";
        // Process the transaction data here
    } else {
        http_response_code(400);
        echo "Signature is invalid.";
    }
} else {
    http_response_code(400);
    echo "No signature provided.";
}

---

Recommendations

• Ensure that your server is accessible from maib IPs to receive the notifications.

• Respond with HTTP status 200 OK only after successfully verifying the signature.

• In case of errors or invalid signature, respond with a status code different from 200 to force the notification to be resent.