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.
If you use a Webshop Module, postback notifications will be handled automatically. On a self built integration, however, you will need to handle the notifications yourself. The PHP and .NET API's have function to help in validating a postback notification. The postback page must return an HTTP 200 after successfully handling the notification. If the response is not 200, the ICEPAY systems will send a notification email to the emailaddress of the Technical Contact in your account and will also attempt to retry sending the postback at a later time.

Format

A postback is a server-to-server POST to the URL as defined in IC_Postback. You can set this URL 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 notification uses a checksum to allow you to verify the contents of the notification. The checksum is a digital signature that authenticates the sender of the message. This prevents others from tampering and sending payment requests in your name. It also assures you that any response or postback you receive actually comes from ICEPAY. You must always validate the checksum.

How to calculate the checksum

The checksum calculation for the SOAP API and postbacks use the individual fields in requests/responses by concatenating the values separated by the pipe (|) character.
Example: secret|12345|OK|Succes|100000007|1234567|My Payment 100000007||10000|EUR|0|143.45.127.31

Note that the order of the fields matters in these calculations. The exact order for a postback can be found here: Postback Checksum Fields.

Convert the string to bytes using UTF-8 encoding and calculate a SHA1 hash. Compare this with the checksum found in the postback notification (bytes are converted to hexadecimal format, e.g.: fec283744032990e5b461456340c1844be507a31).

Possible Statuses

The postback notification contains a parameter called Status. 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 Status that is returned by ICEPAY can only be one of the following codes:

StatusDescription
Open
The payment 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.
OK
The payment has been completed.
ERR
The payment was not completed successfully or expired. It cannot change into anything else.
REFUND
A payment has been successfully refunded.
CBACK
The consumer has filed a chargeback via their issuing bank. You will receive a different PaymentID parameter but all the other parameters remain the same.
VALIDATE
The payment is awaiting validation by the consumer by means of a validation code returned by ICEPAY. Currently, this status is only used by SMS payments. You can safely ignore postbacks with this status if you have integrated ICEPAY using the Checkout.aspx method.

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

StatusCode

The Postback Notification also contains a parameter called StatusCode. 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.

Examples of StatusCodes:

  • Acquirer Error
  • Completed with user hangup
  • Money received. Bank statement ID: 12345
  • Payment aborted by user
  • Success

Status Transitions

If your Postback Script synchronizes the information from Postback Notifications with your local data storage, then you must only do that according to the following diagram.

If your transaction is already flagged as OK, it will NEVER transition into ERR. Should you do get an incoming Postback Notification with that status, then you must simply ignore it.

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.