Уведомления по Callback URL

Мерчант будет получать уведомления на Callback URL с окончательным ответом по платежу, который содержит статус транзакции и соответствующие детали (например, qrStatus, payId, amount, etc).

На основании этих уведомлений мерчант должен обеспечить доставку услуги или товара покупателю.

Уведомление считается успешно полученным, если сервер мерчанта отвечает кодом HTTP 200 OK.

---

Структура уведомления (Пример)

{
  "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) из объекта result, используя следующий алгоритм:

1. Все поля объекта result, за исключением поля signature, сортируются в алфавитном порядке.

2. Поля со значением null или пустой строкой ("") полностью игнорируются при формировании подписи, как будто они отсутствуют.

3. Поля, содержащие суммы (amount, commission), форматируются с точностью до двух знаков после запятой (например: 0.50, 2.31) до объединения.

4. Значения оставшихся параметров объединяются в строку, используя двоеточие (:) в качестве разделителя, в отсортированном порядке.

5. В конец полученной строки добавляется ключ подписи (Signature Key), доступный в настройках проекта в платформе maibmerchants.

6. Из полученной строки формируется бинарный хеш по алгоритму SHA-256.

7. Полученный хеш кодируется в формате Base64 (или другом, указанном в официальной документации QR MIA).

8. Сгенерированная подпись сравнивается со значением поля signature, полученного в уведомлении.

Если значения совпадают, подпись считается действительной, а данные — подлинными и неизменёнными.

---

Пример проверки подписи

<?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.";
}

---

Рекомендации

• Убедитесь, что ваш сервер доступен с IP-адресов maib для получения уведомлений.

• Отвечайте кодом HTTP 200 OK только после успешной проверки подписи.

• В случае ошибок или недействительной подписи отвечайте кодом, отличным от 200, чтобы инициировать повторную отправку уведомления.