Within our API, you have the capability to use the callback_url body parameter in the create payment and create-authorization APIs.
For Payments
When you're dealing with payments, the callback_url is needed to stay updated on the payment status.
You will receive a GET HTTP request whenever there's a change in the payment status.
We recommend using it, as not doing so could lead to missed payments or mishandling of payment information.
For Authorizations
When you're working with authorizations, the callback_url helps you keep an eye on any changes in the authorization status.
For example, it can notify you when a user cancels their authorization.
This feature is essential for maintaining control and responding appropriately to authorization changes.
Proper usage
To properly use the callback_url parameter, keep in mind that you can utilize the {uuid} placeholder string to dynamically replace it with the actual Satispay payment id or authorization id.
Your callback_url parameter might look something like this:
https://example.com/satispay-callback?payment_id={uuid}
https://example.com/satispay-callback?authorization_id={uuid}
With this specified callback_url, you will receive a GET HTTP request from the Satispay server at that endpoint.
Upon receiving the HTTP call, in case of payments, you can read the payment_id query parameter and use it to retrieve the status of the corresponding payment.
In case of authorizations you can read the authorization_id query parameter and use it to retrieve the status of the corresponding authorization.
Beware
Please note that our notifications only inform you of a change in the payment status and do not include the actual payment status (e.g., accepted, canceled, pending, etc.).
The same happens with authorizations.
To obtain the current payment status, refer to the get payment details API.
To obtain the current authorization status, refer to the get authorization API.
Throttling
Ensure that you implement appropriate and sufficient throttling measures on your callback_url endpoint, as depending on your setup, you may experience a high volume of concurrent HTTP callback calls.
The volume of concurrent HTTP callback calls can vary based on your implementation and the number of concurrent payments you're managing.
Retry policy
We have a retry policy in place when your server responds to the callback with a non-2XX HTTP status code, making up to 3 retry attempts with a 2-minute interval between each.
However, if the issue persists beyond these retries, especially if your server consistently returns a non-2XX HTTP status code or is offline, we recommend you to periodically check the payment status by retrieving it and adjusting your logics accordingly.
Payment loss
As previously mentioned, every payment should be handled by callback.
If the callback is not properly handled, it can lead to potential payment losses, especially in e-commerces.
Relying only on the Satispay app's redirection to your website for payment confirmation is not recommended.
To illustrate this further, consider the following scenario:
- During the checkout process, the user chooses Satispay as their payment method.
- A Satispay QR code is presented to the user for scanning.
- The user uses the Satispay app to scan the QR code, revealing the order amount and a "confirm" button.
- If the user closes their web browser at this point, they can still confirm the payment via the Satispay app.
- In this scenario, while Satispay effectively processes the transaction, failure to appropriately manage callbacks on the e-commerce side can lead to the incorrect generation of an order.