Using Hash with Hosted Payment Forms

A hash function is an algorithm that transforms (hashes) an arbitrary set of data elements, such as a text string or file, into a single fixed length value (the hash). The computed hash value is a means of protecting sensitive data. Bluefin has included this functionality in its APIs, and it uses a Secure Hash Algorithm (SHA-256) type of hash.

Sending the HASH

There are two pieces that are tied to sending a hash, the hash value and the “hash_key” value (string), although the “hash_key” is not always required. A description of each REQUIRED parameter in any HASH is included below.

It is possible in any transaction type to use the HASH method for more than just the required fields (listed above). This is strictly up to the vendor/merchant, but it is recommended by Bluefin to do so. If the merchant wishes to include other data values in the hash, they can be appended to the hash value, but another element must be sent, called the “hash_key”, which is explained below.

🚧

Important

There are a few important things to keep in mind regarding the HASH method:

1. All HASH parameters are case sensitive.
2. When using the transparent redirect method, the HASH method is REQUIRED.
3. The parameter api\_accesskey is NOT to be sent as a separate variable when using transparent redirect. Doing so compromises the integrity of the data, PCI compliance, and will result in a "security violation" error.

Basic HASH Usage

If the merchant wishes to send the minimum values of a hash, given the following values:

account_id :: 123456789012
api_accesskey :: e6f157d2-66cf-43d5-8a56-c4c57d5760d7
timestamp :: 1360870400

This would be the hash string:

123456789012,e6f157d2-66cf-43d5-8a56-c4c57d5760d7,1360870400

With a resulting hash value that is sent as something like:

b48171ba3c4ffbc1345093087d661d52a109d836462455d208f52bf7392cbf95

Using the HASH Key with Transaction Amount

Given the same minimum values, and a transaction_amount of $123.00, the hash string would look like:

123456789012,e6f157d2-66cf-43d5-8a56-c4c57d5760d7,1360870400,123.00

And the resulting hash value that is sent is something like:

c602825bed7fdc9b256ec6ce074b88e6befc18bd0eb295a9acb7af024708aedf

📘

Note

In this example, the QSAPI request would also require hash_key to be passed as a parameter. The key/value, in this case, would be hash_key = “transaction_amount”

Using the HASH Key with Transaction ID

Given the same minimum values, and a transaction_id retrieved from TSAPI, the hash string would look like:

123456789012,e6f157d2-66cf-43d5-8a56-c4c57d5760d7,1360870400,000000105521

📘

Note

For more information on getting a transaction_id value via TSAPI see our guide, Fetching Transaction Information.

And the resulting hash value that is sent is something like:

6b255ae6af73f02589876332d0be0cacc748d01c6a97db80fa4dcdf9c4d06594

📘

Note

In this example, the QSAPI request would also require hash_key to be passed as a parameter. The key/value, in this case, would be hash_key = “transaction_id”

Using Multiple Parameters in HASH Key with Transparent Redirect

Using HASH authentication is required on pages that utilize Transparent Redirect.

We recommend including multiple hash values to generate a more secure HASH value.

Transparent Redirect hashes require the following parameters (in order):

• account_id
• api_accesskey
• timestamp
• success_url

📘

Note

If a decline_url is used, it must be included in the string after the success_url.

This example will include all the parameters above in conjunction with transaction_id, transaction_amount, first_name, and last_name.

Given the required values, the addition of the transparent redirect requirements, and additional parameters, our hash string would look like this:

123456789012,e6f157d2-66cf-43d5-8a56-c4c57d5760d7,1360870400,mysuccessurl.me,mydeclineurl.me,000000105521,Blue,Fin

And the resulting hash value that is sent is something like:

2514f261572446124db513dff328fc020f592f7173e227b30b8816f75cdca3a3

The hash_key value that would need to be included in the request is hash_key = "transaction_id,transaction_amount,first_name,last_name"

Variables Index

When using a hash, the table below shows the variables that would be sent to QSAPI, along with the request format variables for the given transaction type.