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.
Signature Example
message:
{"checkoutId":"5a4d27a4-79f5-426b-9403-cccdeee81747","paymentIntentId":"baa2a48d-b3ba-48b8-917e-07607d447c4f","merchantId":"37e48a96-37d7-49b3-8373-2e7e69ef8c2e","terminalId":"23456543","amount":193.54,"currency":"MDL","completedAt":"2024-11-23T19:35:00.6772285+02:00","payerName":"John","payerEmail":"Smith","payerPhone":"37368473653","payerIp":"192.175.12.22","orderId":"1142353","orderDescription":"OrderDescriptiondda760d7-a318-451b-8e47-f3377c06dcf5","orderDeliveryAmount":92.65,"orderDeliveryCurrency":8,"paymentId":"379b31a3-8283-43d4-8a7b-eef8c0736a32","paymentAmount":64.76,"paymentCurrency":"MDL","paymentStatus":"Executed","paymentExecutedAt":"2025-05-05T23:38:07.2760698+03:00","providerType":"Ips","senderIban":"NL43RABO1438227787","senderName":"Steven","senderCardNumber":"444433******1111","retrievalReferenceNumber":"ABC324353245"}.1761032516817
key:
67be8e54-ac28-485d-9369-27f6d3c55a27
signature
h7/NNr0+SVwqfc1seJNl/m4M4/wzBiZwKHjE1gbmMKA=HTTP Headers
X-Signature
sha256=<signature> — computed HMAC signature.
X-Signature-Timestamp
Unix epoch timestamp (milliseconds).
Verification (merchant side)
Compute HMAC using the shared secret over the raw received body.
Verify that the computed signature equals the received
X-Signature. (Comparison must be done in constant time to prevent timing attacks.)Ensure that the absolute difference between the current time and
X-Signature-Timestampis 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.
paymentIntentId
string (UUID)
Identifier of the payment intent associated with the checkout.
merchantId
string (UUID)
Merchant identifier.
terminalId
string
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
Payer’s name.
payerEmail
string
Payer’s email address.
payerPhone
string
Payer’s phone number (MSISDN).
payerIp
string
Payer’s IP address (IPv4/IPv6).
orderId
string
Merchant’s order identifier.
orderDescription
string
Description of the purchased goods or services.
orderDeliveryAmount
number
Delivery amount, if specified.
orderDeliveryCurrency
string (ISO 4217)
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).
providerType
string
Payment provider type (e.g., MMC).
senderIban
string
Sender’s IBAN (for A2A payments).
senderName
string
Name of the sender (cardholder/account holder).
senderCardNumber
string
Masked card number used in the transaction.
retrievalReferenceNumber
string
Retrieval Reference Number (RRN/ARN).
processingStatus
string
Internal payment processing status.
processingStatusCode
string
Provider/internal status code (e.g., “00”).
approvalCode
string
Provider approval code.
threeDsResult
string
3-D Secure authentication result (Y, N, U, etc.).
threeDsReason
string | null
Additional information on the 3DS result, if available.
paymentMethod
string
Payment method used (e.g., Card).
providerExternalStatus
string
External status returned by the payment provider.
Example Notification
Last updated