Callback Notifications
Browser redirect
After checkout completes (with success or fail) user is redirected back to the merchant page with following query parameters:
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
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 + timestamp from header, separated by
.({body}.{timestamp}) .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.
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
Last updated