Handling the Postback

The postback is a notification sent to you by ICEPAY, informing you of any status changes in your transactions. This section provides you with guidelines on how your postback script should handle incoming postback notifications.

It is essential that you handle postback notifications in your integration. Without these notifications you can never be certain of the status of a transaction. It is important to realize that the 'Redirect on Success', as described in the Payment process, is not guaranteed. If the consumer closes their browser after paying the redirect will not happen. However, ICEPAY ensures that you will always receive a postback notification.
The postback page must return an HTTP 200 after successfully handling the notification. 

Format

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

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

Security

The postback is sent with the same header checksum calculations as the API requests and responses.

Possible Statuses

The postback notification contains a parameter called StatusCode. You will most likely want to use this parameter to update the status of your payment in your local database. If you do NOT choose to update the status of your submitted transactions in your own database, this will negatively affect your support options in the instance of refunds, chargebacks or open/not yet validated transaction requests. This must be configured in your account PER WEBSITE at icepay.com. These settings can be found by clicking on the “Advanced” button. The StatusCode that is returned by ICEPAY can only be one of the following codes:

StatusCodeDescription
STARTED
The transaction is not yet completed. After some time you will receive a Postback Notification which contains the OK or ERR status. The time varies depending on the payment method that was used.
FAILED
The transaction was not completed successfully. It cannot change into anything else.
EXPIRED
The transaction has expired.
CANCELLED
The transaction has been cancelled.
COMPLETEDThe transaction was successfully processed and was cleared by the payments system. Funds have not (yet) been received by ICEPAY. It's the customers own risk to deliver products and/or services based on this status.
SETTLEDThe transaction was settled to ICEPAY, funds were received by ICEPAY and the transaction was fully reconciled in the payments system. The transaction will be credited to the balance of the merchant and is available for payout.

You should ignore all other statuses. If a new status is introduced, you will be notified by your account manager.

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.

Sample

You can find a sample of data pushed to your postback page in Postback sample.

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.

Testing your Postback scripts

You can easily test your Postback script when you log into your ICEPAY account. Please navigate to the Tools page where you will see a list of test transactions. These test transactions are created using any version of the Checkout web methods while your Merchant API key is still in Test Mode. Click on a test transaction to change the status. A Postback notification will be sent to your Postback script.