To understand how your payments progress in their lifecycle, you can set up notifications to track changes. To do this, you can use our Webhooks endpoint.
A webhook
(also called a web callback) allows your system to receive an event
from a different app immediately after it happens. You can set up webhooks for different events and your system will receive a notification to a specified URL whenever each of these events happen.
You can use our Merchant API to setup a webhook URL and specify the events
in the request body that you would like to receive.
You need a URL to receive the events. This needs to be an endpoint on your server to which our internal systems can send POST
requests whenever the events happen.
Once the events you have subscribed to occur, we will send a callback to the URL you have provided. It is now up to you to handle the information that your system receives.
Example structure of the events our system sends:
{
"event": "ORDER_COMPLETED",
"order_id": "9fc01989-3f61-4484-a5d9-ffe768531be9",
"merchant_order_ext_ref": "Test #3928"
}
We cannot guarantee the delivery order of the events. You might receive the events in an unexpected order. Make sure your server does not rely on the temporal order of events.
Now that you can use webhooks to track the payment lifecycle more effectively, there are two scenarios where we recommend using webhooks:
onSuccess
callback that is executed from the widget, set up a webhook URL for receiving ORDER_COMPLETED
events. This is a much more robust approach to moving your own orders to a "successful" state and giving your product or service to your customers.ORDER_PAYMENT_FAILED
and the ORDER_PAYMENT_DECLINED
events. This will allow your backend to track when a payment for an order fails. You can use this together with the failure_reason
parameter in the payment object. You can retrieve the failure_reason
by retrieving the corresponding order for the payment.