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 API’s, and it uses a Secure Hash Algorithm (SHA-256) type of hash.

📘

Note

The HASH function is new in version 3.8 of the API. Prior versions do not contain this feature.

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.

ParameterReq'dDescription
account_idYesThis is the merchant account ID. For any hash, this MUST be included and be the first parameter.
api_accesskeyYesThis is the merchant’s unique “key”. It should NEVER be given out to anyone. For any hash, this MUST be included and be the second parameter. If it is ever sent in the hash, and outside the hash (it is sent twice), you will receive a “Security Violation” error.
timestampYesThis is a 10-digit UNIX timestamp representing the number of seconds since Epoch (00:00:00 on January 1, 1970) and should represent the time this transaction occurs. For any hash, this MUST be included and be the third parameter.

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.

ParameterReq'dDescription
hash_keyNoA string containing a comma delimited list of parameters used to build the hash. This list should NOT include the three parameters above, or other parameters that are used in transparent redirect (see the Transparent Redirect section for more information).

🚧

Important

When using the transparent redirect method, the HASH method is REQUIRED.

Example #1:
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

Example #2:
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 that in the above example #2 that the merchant would also have to send the following, which would indicate the optional “hash_key” parameter is included in the hash:

hash_key = “transaction_amount”

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.

📘

Note

All HASH parameters are case sensitive.

ParameterReq'dDescription
account_idYesThis is the merchant account ID.
timestampYesThis is a 10-digit UNIX timestamp representing the number of seconds since Epoch (00:00:00 on January 1, 1970) and should represent the time this transaction occurs.
hashYesThe hash value (NOT the hash string)
hash_keyNoOnly required if additional (optional) parameters were included in the hash string
NOTE: 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 compliancy, and will result in a "security violation" error.

Did this page help you?