Skip to main content

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).

Reference

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.

Callback URL requirements

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 --request POST -sL \
--url "https://gateway.ixopay.com/api/v3/transaction/${API_KEY}/debit" \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header "Authorization: Basic $(echo -n "$USERNAME:$PASSWORD" | base64)" \
--data-raw '{
"merchantTransactionId": "your-unique-identifier",
"description": "Purchase description shown on credit card statement.",
"amount": "9.99",
"currency": "EUR",
"successUrl": "https://shop.example.org/checkout/success",
"cancelUrl": "https://shop.example.org/checkout/cancelled",
"errorUrl": "https://shop.example.org/checkout/error",
"callbackUrl": "https://api.example.org/callback"
}'

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.

HTTP response

Once the callback has been handled by your system, IXOPAY platform expects a HTTP response with status code 200 and a response body of OK. If you fail to respond this way, IXOPAY platform will 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:

POST /callback
Host: api.example.org
Content-Type: application/json
Date: Thu, 23 Mar 2023 10:34:47 GMT
X-Signature: vbWnLPF+bxvv7c6PId/FXWGlV8HqrtzaC8uqJDbNQBLH1I6V9yF8ePQIsEFsfTJXvQGO1B7hzkPIrwF7J47QVw==

{
"result": "OK",
"uuid": "d94c0d72f3a36e21f16e",
"merchantTransactionId": "auto-d94c0d72f3a36e21f16e",
"purchaseId": "20241126-d94c0d72f3a36e21f16e",
"transactionType": "DEBIT",
"paymentMethod": "Creditcard",
"amount": "9.99",
"currency": "EUR",
"returnData": {
"cardData": {
"type": "visa",
"cardHolder": "Alex Smith",
"expiryMonth": 11,
"expiryYear": 2029,
"binDigits": "41111111",
"firstSixDigits": "411111",
"lastFourDigits": "1111",
"fingerprint": "46f7adfeb0a123fb8fcbfasdf6171asd6b3dfas44834c",
"threeDSecure": "OFF",
"binBrand": "US",
"binBank": "Global Trust Bank",
"binCountry": "US"
}
}
}
HTTP/1.1 200 OK
Content-Type: text/plain

OK

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.

# See other languages

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 …