7. Transaction feedback
After a transaction is processed, depending on the result, a response can be sent to your system and to the customer. Hereafter we explain how and when the transaction feedback can be sent, and what you need to set up and configure on your end to make each feedback process work.
Redirection with parameters on the accept-/exception-/cancel-/declineurl (Redirection with database update) with a deferred post-payment feedback request as a backup (Server-to-server feedback (post-payment)).
In your Ingenico ePayments account, go to "Configuration" > "Technical information" > "Transaction feedback". Configure the settings as described below:
HTTP redirection in the browser:
Direct HTTP server-to-server request: Always deferred:
7.1 Default reaction
By default, meaning if you haven't configured Transaction feedback settings, our system will display a standard message to the customer: "Your payment is authorised" or "The transaction has been denied".
In this page, we also add a link to your website and/or to your catalogue. Usually, these links are configured in your Ingenico ePayments account's Administrative details, which is where our system will fetch them. However, you can also override these URLs by submitting the HOMEURL and CATALOGURL fields with the other the hidden fields in the order form:
<input type="hidden" name="CATALOGURL" value="">
<input type="hidden" name="HOMEURL" value="">
||(Absolute) URL of your catalogue. When the transaction has been processed, your customer is requested to return to this URL via a button.
(Absolute) URL of your home page. When the transaction has been processed, your customer is requested to return to this URL via a button.
When you send the value “NONE”, the button leading back to the merchant’s site will be hidden.
7.2 Redirection depending on transaction result
There are four URLs which our system can redirect the customer to after a transaction, depending on the result. These are "ACCEPTURL", "EXCEPTIONURL", "CANCELURL" and "DECLINEURL".
The URLs can be configured or submitted as follows:
- Configuration in your Ingenico ePayments account: In the Transaction feedback tab of your Technical information page: "HTTP redirection in the browser"
- Submission of the URLs in the hidden fields of the order form:
<input type="hidden" name="ACCEPTURL" value="">
<input type="hidden" name="DECLINEURL" value="">
<input type="hidden" name="EXCEPTIONURL" value="">
<input type="hidden" name="CANCELURL" value="">
||URL of the web page to display to the customer when the payment has been authorised (status 5), stored (status 4), accepted (status 9) or is waiting to be accepted (pending status 41, 51 or 91).
||URL of the web page to show the customer when the acquirer declines the authorisation (status 2 or 93) more than the maximum permissible number of times.
||URL of the web page to display to the customer when the payment result is uncertain (status 52 or 92).
If this field is empty, the customer will be redirected to the ACCEPTURL instead.
||URL of the web page to display to the customer when he cancels the payment (status 1).
If this field is empty, the customer will be redirected to the DECLINEURL instead.
Browser alert notification: secure to non-secure environment
When a customer returns from our secure payment pages to the merchant's (your) website, he might get a browser alert warning him that he is entering a non-secure environment, as most likely he is moving from an https:// environment to an http:// environment.
When we detect a redirection to your website, we can display a message to notify the customer about the possibility of a risk, thereby avoiding any undue concern about a browser alert. You can activate this option in the Transaction feedback tab of your Technical information page, "HTTP redirection in the browser" section: “I want Ingenico ePayments to display a short text to the customer on the secure payment page if a redirection to my website is detected immediately after the payment process”.
7.3 Redirection with database update
You can use the redirection on the redirection URLs to trigger automatic back-office tasks such as database updates. When a transaction is executed, we can send the transaction parameters on your redirection URLs.
To use this functionality, you must activate this option in the Transaction feedback tab of your Technical information page, "HTTP redirection in the browser":
- “I would like to receive transaction feedback parameters on the redirection URLs”.
The redirection is done via the customer’s browser, which makes it visible. Therefore, you must use an SHA-OUT signature to verify the contents of the request and prevent customers tampering with the data in the URL field, which could result in fraudulent database updates.
If you don't configure a SHA-OUT signature, we won't send any parameters on your redirection URLs.
The string to hash is constructed by concatenating the values of the fields sent with the order (sorted alphabetically, in the format ‘parameter=value’), followed by a passphrase. The passphrase is defined in the Transaction feedback tab of your Technical information page, “All transaction Submission modes” section.
For the full list of parameters to include in the SHA Digest, please refer to the SHA-OUT Parameter list. Please note that these values are all case sensitive.
- All sent parameters (that appear in the SHA-OUT Parameter list), will be included in the string to hash.
- All parameters need to be sorted alphabetically
- Parameters that do not have a value should NOT be included in the string to hash
- Even though some parameters are (partially) returned in lower case by our system, for the SHA-OUT calculation each parameter must be put in upper case.
- When you choose to transfer your test account to production via the link in the back-office menu, a random SHA-OUT passphrase will be automatically configured in your production account.
- For extra safety, we request that you use different SHA passphrases for TEST and PROD. Please note that if they are found to be identical, your TEST passphrase will be changed by our system (you will of course be notified).
In the same way we recreate the Digest to validate the transaction input with the SHA-IN, you have to reconstruct the hash, this time using your SHA-OUT passphrase and the parameters received from our system.
If the outcome is not identical, the request’s parameters might have been tampered with. This check guarantees the accuracy and integrity of the parameter values sent in the request.
|Example of a basic SHA-1-OUT calculation
Parameters (in alphabetical order, as returned by Ingenico ePayments):
SHA-OUT passphrase (in Technical information):
String to hash (with all parameters in uppercase):
Resulting Digest (SHA-1):
7.4 Server-to-server feedback (post-payment)
After the transaction is processed, our system can send an http request transmitting the transaction data, to a URL you've specified. This process, which we often refer to as the "post-sale" request, allows you to update your database with the order status, etc. and trigger an “end of order” process (if this has not already been done after a redirection). It is also an alternative way of generating a personal response for the customer in case of specific needs (if this has not already been done via a redirection).
The set of feedback parameters is the same as that for the redirection. You can find them on the "Feedback parameters" page.
7.4.1 Post-payment URLs
You can define the URLs of two executable pages on your site in the "Transaction feedback" tab, "Direct HTTP server-to-server request" section (URL fields) of your Technical information page:
- The first field will ideally contain the URL to which the request parameters are sent if the payment’s status is accepted, pending or uncertain.
- The second field can be the URL to which the request parameters are sent when the transaction has been cancelled by the client or declined too many times by the acquirer (i.e. more than the maximum allowed number of payment attempts as set in the "Global transaction parameters" tab, "Payment retry" section of the Technical information page).
You can enter two different URLs, but you can also use twice the same. You may also enter a URL just in the first field but not for the second.
Do not specify any ports in your URL; we only accept port 443 and port 80.
Variable post-payment URLs for multiple shops
If you have a post-payment page configured in the Technical information page in your account, but you have several shops each connected to a specific directory for receiving the post-payment feedback, part of your post-payment URL can be variable.
This variable part can also be used to e.g. “adapt" the feedback request to include session information, passing it as a part of the URL rather than as an additional parameter. This is the case for Intershop platforms or Servlet systems.
The following hidden field should be used:
<input type="hidden" name="PARAMVAR" value="">
Post-payment URL in your Technical information page:
Extra hidden field sent in your order form:
<input type="hidden" name="PARAMVAR" value="shop1">
Resulting in the following Post-payment URL for the transaction:
Important: do not use any special characters in the PARAMVAR field, as they will be URL encoded, which could create invalid links.
7.4.2 Timing of the request
Where you configure the post-payment URLs, you must also choose the timing of the feedback request:
- No request
In this case, our system will not send any feedback request. This option allows you to disable your post-payment URLs in the event of maintenance or problems on your server.
- Always deferred (not immediately after the payment)
The feedback request will be sent shortly after the end of the payment process. The feedback request will be a background task and cannot be used to send a personalised feedback to the customer on your website.
If you don't use your post-payment page to personalise a response for your customers, you can receive the feedback request in the background and deferred.
- Always online (immediately after the payment, to allow customisation of the response seen by the customer)
The feedback request will be sent “online” sometime between our system’s receipt of the acquirer’s response and the time it notifies the customer of the payment result.
In this case, the payment process takes longer for the customer, but you can send a personalised response to the customer.
The disadvantage of the online post-payment feedback process is that your system might be detrimentally affected if there are too many requests to your post-payment page (e.g. high per-minute transaction volume) – this could result in long response times before customers receive on-screen feedback.
- Online but switch to a deferred request in intervals when the online requests fail
This option allows merchants who require online post-payment feedback (to tailor the response displayed to the customer) to have a fall-back option, should the online request on his post-payment page fail. In this case we will retry the feedback request every 10 minutes up to a maximum of four times (deferred). In this way, you don't miss out on the transaction feedback, should the online post-payment feedback request fail, e.g. as a result of temporary server problems at your end. The customer will be displayed the standard transaction feedback from our system (see Default reaction).
7.4.3 Response to the customer
We use a possible reply from your post-payment page to show a feedback (end of transaction page) to your customer.
If your post-payment page replies with: an HTML page (containing an <html> tag) or A redirection (HTTP 302 Object Moved), our system will send this HTML page “as is” to the client browser or perform the redirection, rather than redirecting your customer at the end of your post-payment feedback process to one of the four URLs you may have sent in the hidden fields (ACCEPTURL, EXCEPTIONURL, CANCELURL and DECLINEURL as described in the Redirection depending on transaction result chapter).
Alternatively, if you use none of the above as feedback to your customer, you can have your post-payment page respond with a few lines of text (no <html> tag) which we will include in our standard response, or our system will simply show the standard response (as described in: Default reaction)
The diagram below shows the process at the end of a transaction, should the payment be authorised or accepted, with an online post-payment request. (When the payment is cancelled, declined or uncertain the process is similar but the "CANCELURL", "DECLINEURL", "EXCEPTIONURL" and "cancellation/rejection" pages are used instead).
7.4.4 HTTP request for status changes
You can also receive an HTTP request in the case of a transaction status change. Therefore, you need to enter a URL in the "HTTP request for status changes" field in the "Transaction feedback" tab of your Technical information page (and select the timing for the request).
This is similar to the post-payment feedback, with the difference that it is only relevant for potential background processes.
You can use the same URL as the one set in the "Direct HTTP server-to-server request" section,
Note: This "status change" URL cannot be used to generate a personal response for the customer.
7.5 Feedback parameters
When a transaction is executed, we can send the following parameter list to your redirection URLs and/or post-payment feedback URLs.
Example (GET request)
||Acceptance code returned by the acquirer
||Order amount (not multiplied by 100)
||Card brand (our system derives this from the card number)
||Masked card number
||Your order reference
||Payment reference in our system
||SHA signature calculated by our system (if SHA-OUT configured)
||Transaction status (see Status overview)
|The list of feedback parameters can be longer if you have activated certain options in your account, such as the Fraud detection module. Please refer to the respective option documentation for more information on extra feedback parameters linked to the option.
7.5.1 Dynamic feedback parameters
You may also choose which parameters are returned.
To do this, go to the "Transaction feedback" tab of your Technical information page, where you will see a list of "Available" and "Selected" fields. Only the "Selected" fields will be part of the feedback request.
To add or remove parameters from the feedback request, click on the parameter name and click the appropriate arrow to add/remove it to/from the list.
|If you add/remove parameters from this list, do not forget to update your SHA-OUT signature accordingly. Parameters that are not selected here will NOT be contained in the SHA-OUT calculation.
7.5.2 Variable feedback parameters
You can send us two extra parameters in the hidden fields of the order form, in order to retrieve them as feedback parameter after the transaction. The following hidden fields are available:
<input type="hidden" name="COMPLUS" value="">
<input type="hidden" name="PARAMPLUS" value="">
|Field for submitting a value you would like to be returned in the feedback request.
Field for submitting some parameters and their values you would like to be returned in the feedback request.
The field PARAMPLUS is not included in the feedback parameters as such; instead, the parameters/values you submit in this field will be parsed and the resulting parameters added to the http request.
Extra hidden fields sent:
<input type="hidden" name="COMPLUS" value="123456789123456789123456789">
<input type="hidden" name="PARAMPLUS" value="SessionID=126548354&ShopperID=73541312">
resulting in a redirection with the feedback parameters:
7.6 Feedback reinitialization
In the event that a redirection/feedback request was not performed due to a blocking action by the customer on our secure payment pages (e.g. clicking the back button in the browser), we can reinitiate the post-payment request and/or redirection so your customer will be redirected to the page you want to display and your databases can be updated.
To enable this feature in your account, go to Configuration > Technical information > Transaction feedback > General, and tick the box "I would like Ingenico ePayments to re-launch the "end of transaction" (post-payment request/redirection) process if required."
It is possible, however, that you will receive multiple post-payment requests for the same Order ID, since the redirection/feedback request will be resubmitted if the customer returns to our secure payment pages using the back button after having been redirected to your website.
Please ensure you configure your Post URL script to handle these "exceptions". For example, you could configure your Post URL script to create a row in your database for each transaction status posted back, and/or generate an email to inform the merchant of an "exception" to the "expected" steps in the transaction process.
It is recommended that you do not overwrite the first transaction status message you receive with any subsequent messages you receive for the same Order ID - ideally you would store all responses for any order, and invoke a process whereby these can be investigated and dealt with appropriately.
If you do not enable this feature, when the customer clicks the back button to return to the secure payment pages, he will see a message indicating that the payment has already been processed.
7.7 Confirmation emails
7.7.1 Email to the merchant
Our system can send you a payment confirmation email for each transaction. You can configure this in the "E-mails to the merchant" section of the "Transaction e-mails" tab in your Technical information page.
In the same section, you can also choose to receive emails to be notified of transaction status changes.
7.7.2 Email to the customer
Our system can send an automatic email to your customer notifying him of the transaction registration. This is a standard email whose contents cannot be changed. The sender (“From”) address used when sending the email, is the address you entered in the “E-mail address(es) for transaction-related e-mails” field. If you entered more than one email address in this field, the first one in the row will be used.
You can activate this option in the "Transaction e-mails" tab, "E-mails to the customer" section of the Technical Information page.
You can also choose to send emails to the customer when the transaction is confirmed (data capture) and when a transaction is refunded, by ticking the corresponding boxes. As the sender ("From") email address for these emails, you can configure the "Support E-mail address to include in transaction-related e-mails". If you don't enter an email address here, we will use the first one entered in the "Support E-mail address to include in transaction-related e-mails" in the "E-mails to the merchant" section.
To be able to send confirmation emails to your customers, you must include the customer's email address in the hidden field:
<input type="hidden" name="EMAIL" value="">
||Customer’s email address