Notificări pe Callback URL

Merchant-ul va primi notificări pe Callback URL cu răspunsul final al plății, ce conține starea tranzacției și detalii relevante (ex. qrStatus, payId, amount, etc).

Pe baza acestor notificări, Merchant-ul trebuie să asigure livrarea serviciului sau produsului către Cumpărător.

Se consideră că notificarea a fost recepționată cu succes dacă serverul Merchant-ului răspunde cu codul HTTP 200 OK.

---

Structura notificării (Exemplu)

{
  "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
}

Validarea semnăturii

Pentru a verifica integritatea și autenticitatea datelor primite, semnătura (signature) din obiectul result trebuie validată utilizând următorul algoritm:

1. Se sortează alfabetic toate câmpurile din obiectul result, cu excepția câmpului signature.

2. Câmpurile care au valoarea null sau șirul gol ("") sunt complet ignorate în procesul de generare a semnăturii, ca și cum nu ar exista.

3. Câmpurile de tip sumă (amount, commission) se formatează cu exact două zecimale (ex: 0.50, 2.31) înainte de concatenare.

4. Valorile câmpurilor rămase se concatenează folosind caracterul două puncte (:) ca separator, în ordinea sortată.

5. La finalul șirului concatenat se adaugă cheia de semnătură (Signature Key), disponibilă în setările proiectului din platforma maibmerchants.

6. Din șirul rezultat se generează un hash în format binar folosind algoritmul SHA-256.

7. Hash-ul binar este apoi codificat în format Base64 (sau alt format specificat în documentația oficială QR MIA).

8. Semnătura generată se compară cu valoarea câmpului signature primit în notificare.

Dacă valorile coincid, semnătura este considerată validă, iar datele sunt autentice și intacte.

---

Exemplu pentru validarea semnăturii

phpCopyEdit<?php
$key = "signature-key-from-project-settings"; // Signature Key obținută din maibmerchants

// Preluăm conținutul JSON primit pe 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'];

    // Scoatem semnătura din datele de validat
    unset($dataResult['signature']);

    // Sortăm alfabetic câmpurile din obiectul result
    ksort($dataResult, SORT_STRING);

    // Funcție recursivă de concatenare a valorilor cu separatorul ':'
    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); // eliminăm ultimul separator
    }

    // Construim șirul de semnătură
    $signString = implodeRecursive(':', $dataResult) . ':' . $key;

    // Generăm hash SHA256 binar
    $hash = hash('sha256', $signString, true);

    // Codificăm hash-ul în Base64
    $signatureCalculated = base64_encode($hash);

    // Comparăm semnătura calculată cu cea primită
    if ($signatureCalculated === $signatureReceived) {
        http_response_code(200);
        echo "Signature is valid.";
        // Procesați datele tranzacției aici
    } else {
        http_response_code(400);
        echo "Signature is invalid.";
    }
} else {
    http_response_code(400);
    echo "No signature provided.";
}

---

Recomandări

• Asigurați-vă că serverul vostru este accesibil de pe IP-urile maib pentru a primi notificările.

• Răspundeți cu cod HTTP 200 OK doar după ce ați verificat cu succes semnătura.

• În caz de erori sau semnătură invalidă, răspundeți cu un cod diferit de 200 pentru a forța retrimiterea notificării.