Transparent Redirect

Transparent redirect is built on the principle of keeping sensitive PCI data off of a merchant’s web server. Payment forms utilizing transparent redirect submit their data directly to Bluefin from the customer’s browser so that the sensitive PCI data never touches the merchant’s servers. Bluefin captures the transaction details, and then relays the response back to the merchant’s website where it can be recorded and gives control of the post-transaction user experience back to the merchant.

In addition to transparent redirect, Bluefin provides a support function that allows the merchant to receive a post back to their servers with the transaction details. This additional feature ensures that the merchant gets a copy of the transaction response details. The post back happens independently from the response sent through the customer’s browser.

Configuration

This version of the API is built around allowing the merchant to have the greatest level of control over the transparent redirect process by passing the URLs in each transaction. It also allows the merchant the option to selectively not send URLs if they don’t wish to. So transparent redirect can be used, or not used, at any time, with any transaction.

Transparent redirect REQUIRES the use of a hash, and the parameters required to create the hash are indicated below:

Parameter Req'd Description
account_id Yes This is the merchant account ID. This MUST be the first parameter.
api_accesskey Yes This is the merchant’s unique “key”. It should NEVER be given out to anyone. This MUST 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.
timestamp Yes This 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.
success_url Yes A string containing a valid URL that the merchant wishes to be used for successful transactions. * It needs to be the 4th parameter in the hash.
decline_url No A string containing a valid URL that the merchant wishes to be used for declined transactions. * If used, it needs to be the 5th parameter in the hash.

📘

Note

These are not the only parameters allowed within a transparent redirect hash. You can use the hash_key parameter to include other API parameters for increased security, like using a transaction_id retrieved from TSAPI.

Please see our article on Using Hashed Authentication for more information on utilizing the hash_key parameter.

Example 1

If the merchant wishes to use and send transparent redirect, given the following values: account_id :: 123456789012 api_accesskey :: e6f157d2-66cf-43d5-8a56-c4c57d5760d7 timestamp :: 1360870400 success_url:: https://www.example.com/success.aspx decline_url:: https://www.example.com/decline.aspx

This would be the hash string: 123456789012,e6f157d2-66cf-43d5-8a56-c4c57d5760d7,1360870400,https://www.example.com/success.aspx, https://www.example.com/decline.aspx

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

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,https://www.example.com/success.aspx, https://www.example.com/decline.aspx,123.00

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

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”

When QSAPI receives a request, it will:

  • Detect the hash parameter in the POST.
  • Validate timestamp has not expired (currently 30-minute life).
  • Look for “success_url” in the POST data.
  • Look for “declines_url” in the POST data.
  • If found, and the URLs validate, the response data will be sent back to the client with an HTTP/1.1 303 response header, causing the client’s browser to redirect to the success or decline URL, as applicable.  

Configuration (PayConex)

Transparent Redirect can also be configured inside of PayConex (Settings – Manage Settings) if desired, but it isn’t as flexible as the above configuration method. Using this method allows the Merchant to enter URLs for a success and decline, at a global level. This allows the Merchant to leave the URLs out of each transaction request because the global setting will apply to all transactions.

See the following for an example of the “API Response Handling” section containing the appropriate fields for the redirect for success and decline URL’s:

624

w

📘

Note

If you have URLs entered in the PayConex configuration screen (above) for “global” success and decline, sending URLs for either with a transaction WILL override the configuration settings. Each merchant account needs to decide if it is best to send transparent redirect URLs in each transaction request or to use global. An errant or unauthorized change to the globally configured URLs could have a negative impact on getting transaction responses.

Variables Index

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

Parameter Req'd Description
account_id Yes This is the merchant account ID.
timestamp Yes This 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.
success_url Yes A string containing a valid URL that the merchant wishes to be used for successful transactions.
decline_url No A string containing a valid URL that the merchant wishes to be used for declined transactions.
hash Yes The hash value (NOT the hash string)
hash_key No Only required if additional (optional) parameters were included in the hash string

❗️

Importnat

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.