Callback S2S

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. The system performs up to 3 retry attempts with increasing intervals of 1 second, 2 seconds, and 4 seconds between each attempt.

If the issue persists beyond these retries—such as when your server consistently returns a non-2XX status code or is temporarily unavailable—we recommend periodically checking the payment status by retrieving it via API and handling it according to your business logic.

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:

1. During the checkout process, the user chooses Satispay as their payment method.
2. A Satispay QR code is presented to the user for scanning.
3. The user uses the Satispay app to scan the QR code, revealing the order amount and a "confirm" button.
4. If the user closes their web browser at this point, they can still confirm the payment via the Satispay app.
5. 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.

Callback authentication

Satispay callbacks may include an Authorization header containing a cryptographic signature that allows you to verify the request originated from Satispay.

When present, the signature is computed over a set of request headers — including the Digest and Date headers — using an asymmetric signing algorithm. You can use Satispay's public key to verify the authenticity of the request.

Regardless of whether the Authorization header is present, every callback includes a Digest header containing the SHA-256 hash of the request body, which you can use to verify payload integrity.