Handling the Postback
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
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|22.214.171.124
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).
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:
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.
The payment has been completed.
The payment was not completed successfully or expired. It cannot change into anything else.
A payment has been successfully refunded.
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.
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.
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
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.
You can find a sample of data pushed to your postback page in Postback sample.
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.