> For the complete documentation index, see [llms.txt](https://docs.maibmerchants.md/checkout/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maibmerchants.md/checkout/api-reference/callback-notifications.md).

# Callback Notifications

### Browser redirect

After checkout completes (with success or fail) user is redirected back to the merchant page with following query parameters:

| Parameter name | Type   | Description                                                |
| -------------- | ------ | ---------------------------------------------------------- |
| checkoutId     | string | Id of the checkout session                                 |
| checkoutStatus | string | Status of checkout - Completed or Failed                   |
| orderId        | string | Merchant provider order Id for associated checkout session |

### Back channel callbacks

After a successful payment, checkout completion status and payment data are sent to the merchant’s **Callback URL**.

The notification includes a `signature` parameter to ensure the integrity and authenticity of the received data.

***

#### Signing Algorithm

Compute:

```
signature = HMAC_SHA256(secretKey, rawBody.timestamp)
```

**Where:**

* **secretKey** — merchant’s shared key;
* **rawBody** — exact bytes of the JSON body as transmitted (UTF-8 encoded, compact format, no indentation);
* **timestamp** - callback timestamp from **X-Signature-Timestamp** header.

Encode the resulting binary hash as lowercase hex or Base64.\
All parties must use a consistent encoding format.

***

#### Signature Example

```json
message:
{"checkoutId": "5a4d27a4-79f5-426b-9403-cccdeee81747","terminalId": "T1234567","amount": 1234.56,"currency": "MDL","completedAt": "2024-11-23T19:35:00.6772285+02:00","payerName": "John","payerEmail": "Smith","payerPhone": "37368473653","payerIp": "192.175.12.22","orderId": "ORDER-2025-0001","orderDescription": "Online purchase of electronics","orderDeliveryAmount": 50.00,"orderDeliveryCurrency": "MDL","paymentId": "379b31a3-8283-43d4-8a7b-eef8c0736a32","paymentAmount": 1234.56,"paymentCurrency": "MDL","paymentStatus": "Executed","paymentExecutedAt": "2025-05-05T23:38:07.2760698+03:00","senderIban": "NL43RABO1438227787","senderName": "Steven","senderCardNumber": "444433******1111","retrievalReferenceNumber": "ABC324353245","processingStatus": "OK","processingStatusCode": "00","approvalCode": "123456","threeDsResult": "Y","threeDsReason": null,"paymentMethod": "Card"}.1761032516817
 
key:
67be8e54-ac28-485d-9369-27f6d3c55a27
 
signature
mtFkCMxfwj9t2wvY/7JASHLw+K/du4mY8azf1lV0ttg=
```

***

#### HTTP Headers

| Header                    | Description                                     |
| ------------------------- | ----------------------------------------------- |
| **X-Signature**           | `sha256=<signature>` — computed HMAC signature. |
| **X-Signature-Timestamp** | Unix epoch timestamp (milliseconds).            |

***

> #### Verification (merchant side)

1. Compute HMAC using the shared secret over the raw received body + timestamp from header, separated by `.` ( `{body}.{timestamp}` ) .
2. Verify that the computed signature equals the received `X-Signature`.\
   \&#xNAN;*(Comparison must be done in constant time to prevent timing attacks.)*
3. Ensure that the absolute difference between the current time and `X-Signature-Timestamp` is less than **N minutes** to prevent replay attacks.

***

> #### Canonicalization Rules

* JSON is serialized compactly (no pretty-printing or spaces).
* Keys and values appear **exactly as transmitted**.
* Optionally, RFC 8785 — JSON Canonicalization Scheme may be adopted in the future to improve interoperability between different implementations.

***

#### Notification Parameters

| **checkoutId**               | string (UUID)             | Unique identifier of the checkout.                           |
| ---------------------------- | ------------------------- | ------------------------------------------------------------ |
| **terminalId**               | string \| null            | Merchant terminal identifier.                                |
| **amount**                   | number                    | Total checkout amount.                                       |
| **currency**                 | string (ISO 4217)         | Checkout currency.                                           |
| **completedAt**              | string (date-time)        | Timestamp when the checkout was completed (ISO 8601-1:2019). |
| **payerName**                | string \| null            | Payer’s name.                                                |
| **payerEmail**               | string \| null            | Payer’s email address.                                       |
| **payerPhone**               | string \| null            | Payer’s phone number (MSISDN).                               |
| **payerIp**                  | string \| null            | Payer’s IP address (IPv4/IPv6).                              |
| **orderId**                  | string \| null            | Merchant’s order identifier.                                 |
| **orderDescription**         | string \| null            | Description of the purchased goods or services.              |
| **orderDeliveryAmount**      | number \| null            | Delivery amount, if specified.                               |
| **orderDeliveryCurrency**    | string (ISO 4217) \| null | Delivery currency.                                           |
| **paymentId**                | string (UUID)             | Unique identifier of the payment.                            |
| **paymentAmount**            | number                    | Payment amount.                                              |
| **paymentCurrency**          | string (ISO 4217)         | Payment currency.                                            |
| **paymentStatus**            | string                    | Payment status (e.g., Executed, Failed).                     |
| **paymentExecutedAt**        | string (date-time)        | Timestamp when the payment was executed (ISO 8601-1:2019).   |
| **senderIban**               | string \| null            | Sender’s IBAN (for A2A payments).                            |
| **senderName**               | string                    | Name of the sender (cardholder/account holder).              |
| **senderCardNumber**         | string \| null            | Masked card number used in the transaction.                  |
| **retrievalReferenceNumber** | string                    | Retrieval Reference Number (RRN/ARN).                        |
| **processingStatus**         | string \| null            | Internal payment processing status.                          |
| **processingStatusCode**     | string \| null            | Provider/internal status code (e.g., “00”).                  |
| **approvalCode**             | string \| null            | Provider approval code.                                      |
| **threeDsResult**            | string \| null            | 3-D Secure authentication result (Y, N, U, etc.).            |
| **threeDsReason**            | string \| null            | Additional information on the 3DS result, if available.      |
| **paymentMethod**            | string \| null            | Payment method used (e.g., Card, MiaQr).                     |

***

#### Examplu de notificare

```json
{
    "checkoutId": "5a4d27a4-79f5-426b-9403-cccdeee81747",
    "terminalId": "T1234567",
    "amount": 1234.56,
    "currency": "MDL",
    "completedAt": "2024-11-23T19:35:00.6772285+02:00",
    "payerName": "John",
    "payerEmail": "Smith",
    "payerPhone": "37368473653",
    "payerIp": "192.175.12.22",
    "orderId": "ORDER-2025-0001",
    "orderDescription": "Online purchase of electronics",
    "orderDeliveryAmount": 50.00,
    "orderDeliveryCurrency": "MDL",
    "paymentId": "379b31a3-8283-43d4-8a7b-eef8c0736a32",
    "paymentAmount": 1234.56,
    "paymentCurrency": "MDL",
    "paymentStatus": "Executed",
    "paymentExecutedAt": "2025-05-05T23:38:07.2760698+03:00",
    "senderIban": "NL43RABO1438227787",
    "senderName": "Steven",
    "senderCardNumber": "444433******1111",
    "retrievalReferenceNumber": "ABC324353245",
    "processingStatus": "OK",
    "processingStatusCode": "00",
    "approvalCode": "123456",
    "threeDsResult": "Y",
    "threeDsReason": null,
    "paymentMethod": "Card"
  }

```