Skip to main content

Callback

View as Markdown
note

Callback events in Sandbox are simulated. Always implement robust callback handling and verify signature validation logic, even when testing in Sandbox.

A callback is an asynchronous, server-to-server notification sent from the online payment system to your designated callback URL. Its purpose is to reliably inform your system about the final status of a transaction.

Unlike synchronous API calls where your application requests information and waits for an immediate response, the callback process works in the background. The payment system will automatically send a POST request to your callback URL once a transaction is complete, whether successful or unsuccessful, including the initial payment or related actions such as partial/full refunds, preauthorization approvals, and split payments.

The logic for receiving and processing this callback must be implemented on the business side, including the validation for callback signature. Proper handling of the callback is a crucial step to confirm the payment status and securely update the order in your system.

Payment details are sent to the callback URL, provided when the order was requested, using the POST method. To confirm successful receipt of the callback, the business should return HTTP CODE 200. If callback was not received successfully, business must use the Get Payment Details method to verify the payment status and correctly update the order status in its system.

note
Callback and Redirect URL serve distinct purposes:

Redirect URL - Redirects the customer from the online payment page back to the business’s website after payment, enhancing the user experience. However, it does not guarantee the final payment status, as redirection may fail due to user actions or other circumstances, making it essential to verify payment completion through a server-to-server callback.

Callbacks - Ensure payment status confirmation and the secure delivery of payment information from the online payment system’s server to the business’s server. Unlike Redirect URLs, callbacks are independent of user actions and serve as a reliable source for verifying payment status.

Request

Header Parameters​

Callback-Signatureoptionalstring

Signature generated by encrypting callback's request body with a private key using SHA256withRSA algorithm. In order to ensure integrity of callback data, business should verify signature using request body and public key. It is essential to execute this verification before the deserialization of the request body, ensuring that the order of fields remains unchanged.

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAqczfAuhtxw2iF68kS0Hy
bGSv0ZlDAjsXh6VC8avDl3Vxa9qCn6Pzl37Tl2Z21WodiISLeXdhCtOMTeLNUBeb
CYD31y2/MwnhLYqlCk2bOh29fyPc1iT5Eu/k/1IaNRrK9/UVZaTkhOMeEm+aL4y8
5XsE4UjqftEmwrAdbO2G4cCpuoMC9ZXG9gAdr2BFN6i2Vt9eCen5Poj7E1ik7s8T
GyzploVV0NflhwBGeWnvQANUQGr87gsP5k2JG1z5EwnMybJQ7i3XT726rJMaV6QW
sY5hP72Mtv1I1zL2d9FXm9FWOzbpcXCyxuEBXvqqOHzogri8C7KRRYKyk97Ri7D6
8wIDAQAB
-----END PUBLIC KEY-----

Body Parameters​

eventstring

Callback type. The meaning is always order_payment.

zoned_request_timestring

Date of sending a callback in Coordinated Universal Time (UTC). It follows the format "YYYY-MM-DDTHH:MM:SS.ssssssZ".

bodyobject

Order data. Involves the payment detail containing fields.

{
    "event": "order_payment",
    "zoned_request_time": "2022-11-23T18:06:37.240559Z",
    "body": {
        "order_id": "a767a276-cddd-43ec-9db3-9f9b39eee02d",
        "industry": "ecommerce",
        ...
    }
}