5. Security: pre-payment check
5.1 SHA-IN signature
To verify the data that is submitted to its system (in case of e-Commerce the hidden fields to the payment page), Ingenico ePayments requires the secure data verification method SHA. For each order, your server generates a unique character string (=digest), hashed with the SHA algorithm of your choice: SHA-1, SHA-256 or SHA-512. The SHA-IN is auto-populated by the system with a GUID. The default SHA algorithm of your PSPID is SHA-512. Please change this configuration if your system requires the SHA-1 or SHA-256 algorithm.
A similar calculation can be done after the transaction, to verify the parameters returned with the redirection URLs. We call this the SHA-OUT.
5.1.1 Creating the string
The string that will be hashed is constructed by concatenating the values of the fields sent with the order, sorted alphabetically, in the format ‘PARAMETER=value’. Each parameter with its value is followed by a passphrase. This passphrase is defined in the Technical information page of your Ingenico ePayments account, under the tab “Data and origin verification”, section “Checks for e-Commerce”. Please note that these values are all case sensitive when compiled to form the string before the hash!
- All parameters that you send (and that appear in the list in List of parameters to be included in SHA-IN calculation) will be included in the string-to-hash;
- All parameter names should be in UPPERCASE (to avoid any case confusion);
- All parameters have to be arranged alphabetically. In a SHA calculation, parameters with an ID *XX* (ID with an item number higher than 10) should be in natural sort order. For example: In a list such as ITEM 1, ITEM 2, ITEM 3...ITEM 8, ITEM 9, ITEM 10, ITEM 10, ITEM 11; ITEM 11 is placed after ITEM 10 in a natural sort order;
- Parameters that do not have a value should NOT be included in the string to hash;
- Some sorting algorithms place special characters in front of the first letter of the alphabet, while others place them at the end. If in doubt, please respect the order as displayed in the SHA-list;
- For extra safety, we request that you use different SHA passphrases in test and production.
When you hash the string composed with the SHA algorithm, a hexadecimal digest will be returned. The length of the SHA Digest is 40 characters for SHA-1, 64 for SHA-256 and 128 for SHA-512. This result should be sent to our system in your order request, using the “SHASIGN” field.
Our system will recompose the SHA string based on the received parameters and compare the merchant’s Digest with our generated Digest. If the result is not identical, the order will be declined. This check ensures the accuracy and integrity of the order data.
You can test your SHASIGN here, and you can make a test transaction with the SHA Digest calculated by our system here.
Example of a SHA-1-IN calculation (with only basic parameters)
Parameters (in alphabetical order):
AMOUNT=1500 (15.00 x100)
SHA-IN passphrase (in Technical information):
String to hash:
Resulting Digest (SHA-1):
If the SHASIGN sent in the hidden HTML fields of the transaction doesn't match the SHASIGN constructed at our end with the details of the order and the passphrase entered in the SHA-IN passphrase field (in the Technical information page), you will get the “unknown order/1/s" error message in the Error logs of your account (on the payment page a general error message will be displayed).
If nothing is sent in the "SHASIGN" field in the hidden HTML fields, while a passphrase is entered in the SHA-IN passphrase field (in the Technical information page) indicating you want to use an SHA signature with each transaction – you will receive the error message “unknown order/0/s".
Following is the hidden field used to transmit the SHA signature to our system:
||Unique character string for order data validation. A string hashed with the SHA-1 algorithm will always be 40 characters long.
In addition to the SHA check, you can configure the so called referrer check. With this setting, our system checks the origin of the transaction request, i.e. which URL the request comes from (= the referrer). The aim is that unauthorised URLs (that are not configured in your account) won't be able to call the payment page.
If you go to the "Data and origin verification" tab of your Technical information page, in the "Checks for e-Commerce" section you can enter one or more URLs that you want to enable to call the payment page: orderstandard.asp / orderstandard_utf8.asp.
Although the referrer allows our system to identify the origin of an order, it does not guarantee the integrity of the data. Therefore, our system requires the use of an SHA signature.
- The URL(s) must always start with http:// or https://
- You can enter the full URL or simply the domain name; the latter will result in all subdirectories and pages of that domain being accepted
- Should you have several domains, multiple URLs can be entered, e.g. http://www.mysite.com;http://www.mysite.net;https://www.secure.mysite.com. The URLs must be separated by a semicolon, with no spaces before or after the semicolon.
- If you perform a test transaction from our test page, please remember to enter our site’s URL as a referrer, otherwise you will receive an error.
Possible errors related to the referrer are "unknown order/1/r" and "unknown order/0/r". Go to Possible errors for more information about these errors.