The hash value is a number generated from a string of text that is smaller than the text itself. Hash Values are used to make sure the transmitted message is not tampered with.
Benefits of Hash Validation
There are two benefits to using hash validation with your payment form: preventing someone from modifying the data in your payment form link and preventing unauthorized transaction attempts against your merchant account.
In the address bar of your browser, the Payment form link shows the data variables you are using to pre-populate the form. If you do not use Hash Validation, the customer can modify these variables. For example, if they change the Amount from $200.00 to $2.00 in the URL in the browser address bar, the transaction will still go through as approved. If the order is filled, the customer will only pay a fraction of the cost.
Hash Validation prevents this, and any data variables you encrypt within your Hash Value cannot be modified, and the transaction will be approved. When you Hash encrypt variables, you can be confident that the encrypted information cannot be modified.
The Hosted Payment Form, like any other way of connecting your website to Bambora’s payment gateway, uses our API (API) to transmit payment information to us. The information needed to integrate with our APIs are publicly available (including these payment form instructions) so that merchants and partner developers can easily integrate with our system.
The main problem is, that if someone guesses your merchant ID or sees it in your payment form link, they can use it to submit unauthorized transaction requests against your account. This can cause all sorts of negative complications.
Hash validation prevents this. When Hash Validation is enabled, any transaction requests sent through the API that do not include a valid Hash Value (or API Access Passcode) will be rejected by the system. They won’t show in your transaction report because the system blocks it completely.
Note: If you plan to enable Hash Validation on a site that is already processing live transactions, you should test the Hash settings on a test account first. If you do not already have a test account, you can create one. If you enable Hash Validation on a live site and it doesn’t work, transactions will fail and it will affect your customers.
Create a Hashed Validation String for your Hosted Payment form
- Log into your account.
- On the menu, click administration> account settings> order settings.
- Scroll down, and in the Payment Gateway section, under Security/Authentication, select the check box Require hash validation on all Payment Gateway transaction requests.
- Enter a Hash Key. It must be at least 8 characters, it doesn't matter what those characters are.
- Select (and make a note of) the type of Hash algorithm you are using (MD5 or SHA-1).
- At the bottom of the page, click Update.
- A confirmation box opens at the top of the browser window. Click OK.
After Hash Validation is enabled, you need to include a Hash Value in your Hosted Payment form redirect link. If you don't, you will get a Transaction Declined error when someone uses your Hosted Payment form.
If you are using a programming language (like PHP) to create your redirect link, it may already have a hash function built into it—use this to Hash the input variables instead of the manual Hash generator. You can skip Step 4 above, but you should complete the remaining steps.
To demonstrate how to create the Hash Value, we first create a fake redirect link. If you have a test account and want to test this, set the Hash Value in your test account to TestingHash (see previous section, Step 4). Then substitute your test account merchant ID for the fake merchant ID (123456789). This allows you to create a link similar to these instructions.
This link won't work because the merchant_id is fake. It will if you put in your test account Merchant ID.
Encryption only needs to be run on variable value pairs (trnOrderNumber=Test1234), so the Service URL can be removed from the encryption string (for now):
If there are variables in the string that don't you care if a customer modifies, remove them at this point—you will add them back later. For this example we will not encrypt the amount, although you might not do this in reality.
For this example, we want to make sure the Order Number cannot be changed, so we will hash encrypt this string.
Nothing should be used to separate the hash key from the rest of the string. Note: You can substitute the string TestingHash with what you use as a hash key on your account. However, it is best to use a custom Hash Key on a Live account.
For this example we are using http://www.sha1-online.com/, but you can use any Hash Generator you want. This site has options for both MD5 and SHA-1 hash algorithms.
- Copy and paste your string from Step 3 into the open field.
- From the list, select the hash algorithm—make sure to select the algorithm you set up in the Order Settings on your account (see the previous section: Enable the Hash Validation Setting, #5). This example uses the SHA-1 algorithm.
- Click hash. The Hash Value result is returned. Keep in mind that your own test account merchant ID will get a different value.
The hashed variable in the redirect string is trnOrderNumber
At the end of the string, you add the hashed value variable (&hashValue=) and the string from the generator.
Step 6: Add the variable/value pairs you did not encrypt back to the string after the hashValue variable/value
In Step 2, we didn't encrypt the amount, so now it has to be added back to the string.
Note: It is very important that any variables that are NOT hashed be added after the encrypted Hash Value. Also, the order of the hashed variable is the same, or the string will not work.
Note: This link will not actually work, but if you substitute the fake Merchant ID that was used with the Merchant ID from your test account and then follow these instructions, the link you create should work.