Explanation of Postback Notifications

The postback is a notification sent to merchants by ICEPAY. The postback is used to inform merchants of the status of transactions. This section provides guidelines on how to handle incoming postback notifications.

It is essential that postback notifications are handled in your integration. Without these notifications the status of a transaction could left uncertain. In case postback notifications are not handled, and the consumer closes their browser directly after paying, the ‘Redirect on Success’, as described in the Payment process, can not take place, and the status of the payment will be unclear. However, ICEPAY ensures that you will always receive a postback notification.

Format

A postback is a server-to-server POST of a JSON message to the URLs as defined in UrlsNotify. You must set these URLs with every payment request. 

See Postback Fields for a list of all fields in the postback notification

Postback retries

The postback page must return an HTTP 200 after successfully handling the notification. If a postback call doesn’t return the success status code (HTTP status code 2xx), ICEPAY will retry 10 times with a delay of fibonacci numbers until the services returns a success status code. After 10 times retries will be stopped.

Security

The postback is sent with the same header checksum calculations as the API requests and responses. It is important to note that the ContractProfileID used in the checksum calculation of the postback may have a different casing (upper-case vs lower-case) than what is used when doing requests. Always use the literal ContractProfileID provided in the USERID header for the checksum calculation.

Possible Statuses

The postback notification contains a parameter called StatusCode. ICEPAY recommends that this parameter is used to update the status of payments in merchant’s local database. Merchants are required to update the status of transactions in their own database.

Postback notification status codes

The StatusCode returned by ICEPAY can be one of the following codes:

StatusDescription
COMPLETEDThe transaction is successfully processed and is cleared by the payments system. There could be SETTLED notification sent after this one. However funds have not (yet) been received by ICEPAY. It’s the customers own risk to deliver products and/or services based on this status.
CANCELLEDTransaction is cancelled. This is the latest event on the transaction.
FAILEDTransaction is failed. This is the latest event on the transaction.
EXPIREDTransaction is expired. This is the latest event on the transaction.
SETTLEDTransaction was settled to ICEPAY, funds were received by ICEPAY and the transaction was fully reconciled in the payments system. Transaction will be credited to the balance of the merchant and is available for payout.

StatusDetails

The Postback Notification also contains a parameter called StatusDetails. This is an additional parameter which gives you a more detailed description regarding the status of a payment. Your Postback Script should NOT rely on the content of this parameter to decide what to do as it may change from time to time. It is purely informational. Instead, you should always use the status parameter as described above.

Logging

You should log all incoming Postback Notifications. Support tickets regarding bugs or the status of transactions cannot be handled without this information from the backend of the website.