Callback Notifications

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)

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

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.

  2. Verify that the computed signature equals the received X-Signature. (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

Name
Type
Description

result

object

Response result object.

result.checkoutId

string (UUID)

Unique identifier of the checkout.

result.paymentIntentId

string (UUID)

Identifier of the payment intent that triggered the checkout.

result.merchantId

string (UUID)

Merchant identifier.

result.terminalId

string

Merchant terminal identifier.

result.amount

number

Total checkout amount.

result.currency

string (ISO 4217)

Checkout currency.

result.completedAt

string (date-time)

Timestamp when checkout was completed (ISO 8601-1:2019).

result.payerName

string

Payer’s short name.

result.payerEmail

string

Payer’s email address.

result.payerPhone

string

Payer’s phone number (MSISDN).

result.payerIp

string

Payer’s IP address (IPv4/IPv6).

result.orderId

string

Merchant’s order identifier.

result.orderDescription

string

Merchant order description.

result.orderDeliveryAmount

number

Delivery amount, if specified.

result.orderDeliveryCurrency

string

Delivery currency (ISO 4217).

result.paymentId

string (UUID)

Unique identifier of the payment.

result.paymentAmount

number

Payment amount.

result.paymentCurrency

string

Payment currency (ISO 4217).

result.paymentStatus

string

Payment status (Succeeded, Authorized, Failed, Cancelled, Refunded).

result.paymentExecutedAt

string (date-time)

Payment execution timestamp (ISO 8601-1:2019).

result.providerType

string

Payment provider type (e.g., IPS, Card, ApplePay).

result.senderIban

string

Payer’s IBAN (for A2A payments).

result.senderName

string

Payer’s full name or card/account holder.

result.senderCardNumber

string

Masked card number (e.g. 411111******1111).

result.retrievalReferenceNumber

string

Retrieval Reference Number (RRN/ARN).

result.metadata

object

JSON metadata attached to the checkout for correlation.

signature

string

Notification validation signature.

Example Notification

{
  "result": {
    "checkoutId": "b1c0a664-0f3c-4e7c-8cf6-6f7b2d8e2f10",
    "paymentIntentId": "6f91d9a3-d5e6-4f68-9d0f-7a66b9efc2a1",
    "merchantId": "a7ab1f2b-6b0b-4c01-9e2b-3c6b2e4d1a55",
    "terminalId": "TERM-001",
    "amount": 123.45,
    "currency": "MDL",
    "completedAt": "2029-10-22T10:32:29+03:00",
    "payerName": "John D.",
    "payerEmail": "[email protected]",
    "payerPhone": "+37360000000",
    "payerIp": "203.0.113.42",
    "orderId": "ORD-2025-000123",
    "orderDescription": "Order #123 / 2x T-shirt",
    "orderDeliveryAmount": 50.00,
    "orderDeliveryCurrency": "MDL",
    "paymentId": "0b3f8d2a-9e23-4a4d-9fbe-9b1a0f0f2d33",
    "paymentAmount": 123.45,
    "paymentCurrency": "MDL",
    "paymentStatus": "Succeeded",
    "paymentExecutedAt": "2029-10-22T10:32:28+03:00",
    "providerType": "IPS",
    "senderIban": "MD24AG000225100014156789",
    "senderName": "John Doe",
    "senderCardNumber": null,
    "retrievalReferenceNumber": "123456789012",
    "metadata": {
      "correlationId": "c1e8f5a2-9f7b-4f8c-9f9e-1a2b3c4d5e6f",
      "cartId": "CART-10001",
      "customerSegment": "standard",
      "utm": {
        "source": "newsletter",
        "medium": "email",
        "campaign": "autumn-2025"
      },
      "notes": "Deliver after 6 PM",
      "attributes": {
        "loyaltyTier": "silver",
        "couponCode": "WELCOME10"
      }
    }
  },
  "signature": "r4KwwIUXQGHhcEM7C4um8o9rSrGEriTRcYQuBbmjEec="
}
PreviousSandbox (Simulation Environment)NextExamples

Last updated