Callbacks
The IXOPAY platform provides a callback mechanism that allows you to receive real-time updates on the status of your payment transactions. This is useful for keeping your own system in sync with the status of your payments, and for triggering other actions based on the status of a payment (e.g. sending a confirmation email to your customer).
For more details on callbacks, check out the in-depth article on callbacks in the reference.
To use callbacks, follow these simple steps:
Step 1: Setting a callback URL
When you initiate a payment transaction using one of the transaction methods (debit, preauthorize etc.), you can provide a callbackUrl parameter in your request payload. This parameter specifies the URL of your system’s endpoint that will receive the callback notifications.
For detailed information on the restrictions that apply to the callbackUrl field, please refer to the comprehensive article on Response handling in the reference section.
Here is an example request to create a debit transaction with a callback URL:
- curl
- Python
- PHP
- Java
Step 2: Setting up a callback endpoint
To receive callback notifications from IXOPAY platform, you need to set up an endpoint in your system that can receive and process incoming POST requests.
The callback data is sent as a JSON payload in the body of the POST request. The payload contains information about the transaction, including its current state and any relevant details.
Once the callback has been handled by your system, IXOPAY platform expects a HTTP response with status code 200 and a response body of exactly OK (trimmed). Any other response — a non-200 status code or a body that is not OK — is treated as a failed postback and will cause IXOPAY platform to retry sending the callback using an exponential backoff algorithm — see Reference: Callbacks - Response handling.
Here is an example of how you can set up a callback endpoint in your store’s backend system:
- HTTP
- Python: Flask
- PHP: Laravel
- Java: Spring Boot
Step 3: Update internal state
Once the authenticity of the callback data has been verified (see Additional security), your system can update its internal state to reflect the new state of the transaction. This could involve updating a database record, triggering a notification to a user, or performing some other action based on the current state of the transaction.
- HTTP
- Python: Flask
- PHP: Laravel
- Java: Spring Boot
It is important to note that callbacks are not guaranteed to be delivered in real-time and may experience delays or even failures.
If your initial request could not be processed, no transaction will be created; this is indicated by an initial transaction response with success set to false. If no transaction is created, IXOPAY platform will not send any callbacks.
Conclusion
In summary, using callbacks to update a payment transaction’s state in the background can provide real-time updates on the status of the transaction without the need to constantly query the IXOPAY platform API. Follow the steps above to configure the callback URL, process the callback data, and update your internal state based on the current state of the transaction.
Next steps
Now that you have integrated IXOPAY platform’s callbacks, you can look into …
- … implementing additional security by validating the callback signature.
- … recurring payments to generate recurring revenue.
- … testing your setup to make sure you’ve set up everything correctly.
- … exploring the callback reference for detailed information on callback structure and usage.