Skip to content

Transaction Feedback

Merchants receive the following two types of feedback regarding the status of a payment:

Postback. A postback is an HTTP POST request from ICEPAY to the merchant for all urls defined in the UrlsNotify field of the Contract.Postback request. Redirect is executed after the consumer finishes the transaction. Upon a successful transaction the consumer is redirected to the url which is set in the UrlCompleted field of the Contract.Postback request. Upon cancellation, rejection or fail, the consumer is redirected to the url set in the UrlError field of Contract.Postback.

In some cases consumers complete paying for a transaction but close the browser which causes the redirect not to happen. In other cases consumers close the browser while on the payment page (but without paying). In all cases, ICEPAY will send a postback to the merchant informing them of the outcome of the transaction. Therefore, ICEPAY recommends merchants to rely on postback notifications for the primary result of the payment and not on the redirect.

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:

Status Description
COMPLETED The 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.
CANCELLED Transaction is cancelled. This is the latest event on the transaction.
FAILED Transaction is failed. This is the latest event on the transaction.
EXPIRED Transaction is expired. This is the latest event on the transaction.
SETTLED Transaction 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.

Postback fields and sample

Name Type Description Example value
FeedbackType string Is always “Transaction” or “Authorisation”
ContractprofileId Guid Your ContractProfileId
TransactionId/AuthorisationId Guid The unique value that identifies this transaction or authorisation
Reference string Your reference as passed with the transaction request
StatusCode string Transaction status
StatusDetails string Extra details from the payment provider (if applicable)
Amount long The paid amount in cents
CurrencyCode string The currency in which the amount is represented
PaymentMethodCode string The payment method that was used
PaymentDetails object Key value mapping. Some payment methods will return details.These values are not guaranteed to be returned and may vary with payment methods. Possible keys are listed below table?{"ConsumerName" : "name of the consumer","ConsumerIBAN" : "NL3487658347",}

Payment Details Keys

Name  
ConsumerName
ConsumerBIC
ConsumerIBAN
ConsumerBankCode
ConsumerAccountNumber
ConsumerBankName
TriggerURL
ConsumerBIN
ConsumerCardLast4Digits
ConsumerCardToken
PaymentDescriptor
ConsumerCountry
TransactionFlow

Postback Sample

{
    "FeedbackType": "Transaction",
    "ContractProfileId": "b148b93c-4045-45fa-9a67-56ca45729dc4",
    "TransactionId": "b35b85cc-5099-46db-81cf-a3dd3daf91cf",
    "Reference": "order12345",
    "StatusCode": "Completed",
    "StatusDetails": "iDeal Transaction Completed",
    "Amount": "100",
    "CurrencyCode": "Eur",
    "PaymentMethodCode": "iDeal"
}

Redirect

Merchants have to specify redirect urls in the transaction request under the Postback node. Urls have to be specified for two payment status outcomes of payment requests:

  • Successful payment
  • Failed payment

A Redirect is executed after consumers submit payment details. Consumers are then redirected to url corresponding with the payment status of the payment request. Upon a successful payment the consumer is redirected to the url which is set in the UrlCompleted field of the Contract.Postback request. Upon payment rejection or fail, the consumer is redirected to the url set in the UrlError field of Contract.Postback request.

Often consumers submit payment details, kick off payment processing, and close the browser which causes the redirect not to be triggered. The payment is processed, however the status of the payment is unclear for the merchant as the redirect did not take place. Therefore postback notifications are sent asynchronously in order to inform merchants of the payment status.

Format

The Redirect is an HTML GET, including values offering merchants more information regarding the payment. All values will be appended as GET parameters. The append process takes into account whether there already is a “?” or not in the UrlCompleted / UrlError page. Custom query string parameters can be used in UrlCompleted and UrlError fields. Please be aware that these parameters are publicly exposed and therefore should not contain any sensitive values. Do make sure to avoid name-clashes.

Security

The redirect uses a checksum to allow verification of the content of the data. 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 ensures that any received response or postback is sent by ICEPAY. Validation of the checksum is therefore crucial.

How to calculate the checksum

The checksum calculation for the redirect use the individual fields that are sent as GET query parameters by concatenating the values separated by the pipe (|) character in the following order: ContractProfileId|StatusCode|StatusDetails|Reference|TransactionId|ProviderTransactionId|PaymentMethod|Issuer|AmountInCents|CurrencyCode

Calculate the HMACSHA256-hash of this string and compare it with the checksum sent in the query parameters. The checksum is in HEX format.

Sample

Sample of a success URL:

http://www.mywebshop.com/success.aspx?ContractProfileId=8658b625-8dfd-4165-9c88-1e7bf2ae90e1&TransactionId=64295b8b-d56f-479b-a0b9-43cd013d8ec6&Reference=order12345&StatusCode=Completed&StatusDetails=Finished&PaymentMethod=iDeal&Issuer=ING&AmountInCents=100&CurrencyCode=EUR&ProviderTransactionId=03c165e8-d041-43f7-97a3-392830249c32&Checksum=40099d8c1841de6eeb77f4ce9036494379c01c49218bbe35fa446e70e9bf8574