Webhooks and status updates
We use webhooks to notify you the moment a transaction changes its status.
Before you enable webhooks
- Create a webhook endpoint on your server (HTTP endpoint)
- Make sure it accepts POST requests with a JSON payload
Configure Webhooks
To start receiving webhook notifications, you can specify a webhook URL when sending the API request for creation of a checkout. Here's a sample request:
{
"storeId": "12345678",
"transactionType": "SALE",
"transactionAmount": {
"total": 25,
"currency": "EUR"
},
"checkoutSettings": {
"webHooksUrl":"https://webhook.site/50d0a452-2785-45fb-ab7a-468cf21d4f36"
}
}
Here's what a webhook event will look like when received on the specified request URL:
{
"retryNumber": 0,
"storeId": "12345678",
"checkoutId": "5qnq1E",
"orderId": "91e95c4d-9949-438e-8650-1457188ef016",
"transactionType": "SALE",
"approvedAmount": {
"total": 25,
"currency": "EUR",
"components": {
"subtotal": 20,
"vatAmount": 2,
"shipping": 3
}
},
"transactionStatus": "APPROVED",
"paymentMethodUsed": {
"cards": {
"cardNumber": "123456******7890",
"expiryDate": {
"month": "12",
"year": "2024"
},
"brand": "VISA"
}
},
"ipgTransactionDetails": {
"ipgTransactionId": "84632773344",
"transactionStatus": "APPROVED",
"approvalCode": "Y:758396:4632773344:YYYM:032018"
}
}
Handling of edge cases
In certain instances, the webhook may not function as intended. We highly recommend implementing a transaction inquiry via the Retrieve checkout details endpoint if the status remains 'WAITING' for more than 5 minutes, with retries scheduled every few minutes up to a maximum of 30 minutes. You can use the checkoutId from the initial response to Create a new checkout endpoint. This approach guarantees that the final status of the transaction is retrieved without requiring additional back-office operations
Example:
GET .../checkouts/{checkoutId}
(no body)
Updated about 19 hours ago
