Learn how to use the PayConex secure iFrame

The purpose of the Payment iFrame is to allow a merchant to embed an iFrame on their checkout page that will encrypt the payment data entered by the users and return an "eToken" to the merchant. The merchant can then pass that eToken from their webpage to their web server and process payments through Bluefin's API using that eToken. The Payment iFrame and the accompanying client library allow the merchant to perform card or check transactions in a PCI compliant manner while also affording them greater programmatic control over the look and feel of the embedded input form.

PCI Scope

The Payment iFrame reduces the PCI scope for the merchant by enabling them to outsource the capture of sensitive credit and debit card or check payment data to Bluefin. We control the capture of the data, send it to our server for encryption and release an encrypted token (eToken) to the merchant which they can use with Bluefin's API for further payment processing (SALE, AUTH, STORE in the case of credit card transactions and SALE, STORE for check transactions). With our solution, the merchant never handles card or check payment data directly; instead, they deal with eTokens and a number of JavaScript APIs.

The Payment iFrame Flow

This diagram outlines a typical flow of a Payment iFrame transaction.This diagram outlines a typical flow of a Payment iFrame transaction.

This diagram outlines a typical flow of a Payment iFrame transaction.

Environments Impacted by PCI Scope

The figure above outlines the typical flow of a Payment iFrame transaction. The colors represent the different environments impacted by PCI scope:

  • The iFrame Controllers deal directly with the card or check data and are exclusively controlled by Bluefin.
  • The Merchant Server handles eTokens and non-sensitive card data which include the expiration date as well as the first one digit and last four digits of the card number. This part is controlled by the merchant.
  • The User's Browser is the end users' environment which is out of the control of both the merchant and Bluefin.

Typical Flow

A typical transaction will include the following steps:

  1. Cardholder enters the card or check data in the iFrame and pushes the ‘Submit’ button on eCommerce site, the button calls the Payment iFrame's encrypt() function from the JavaScript library. The JavaScript library then passes a command to the iFrame to encrypt the card or check data.
  2. The iFrame performs client-side validation, if the data is valid then it performs an AJAX call to the Bluefin server with the card or check data.
  3. The Bluefin server then performs additional security checks. If the checks pass, it then encrypts the card or check data and generates an eToken. Finally, it returns the eToken to the iFrame page.
  4. The iFrame then passes the eToken to the parent page. On the parent page, the merchant’s JavaScript Controller receives the eToken through a callback function (attached to the encrypt function earlier).
  5. The merchant’s controller passes the eToken along with other data to the merchant’s server.
  6. The merchant’s server performs an authenticated QSAPI call to the Bluefin server with the eToken and any other transaction-relevant data. The Bluefin server validates the eToken and processes the transaction based on the content of the eToken.
  7. The Bluefin server then sends the transaction approval/decline response to the merchant's server.
  8. The merchant’s server then passes the response back to the JavaScript controller on their checkout page to finalize the process.


The Payment iFrame comes with its own javascript library and will work without any other javascript library. This allows the Payment iFrame to be compatible with any other javascript library that may be used or not used on the merchant's website.

There is however one exception to the previous statement which is the matchLabelStyle & matchInputStyle feature that depends on jQuery. This feature is optional but if used, the merchant's website must include the jQuery library, this can be any version of jQuery but must use the standard $ object for jQuery. If that feature is not used, it eliminates the need for JQuery.

The Payment iFrame requires that it would be run on a browser that supports it. Compatible browsers include the following:

  • Internet Explorer 8+
  • Edge 13+
  • Firefox 46+
  • Chrome 29+
  • Safari 9.1+
  • Opera 38+

The Merchant's system must process the captured payment data before the resulting eToken expires, which has a lifetime of a few minutes. In most cases this is not an issue as the payment data is usually captured once the payment is ready to be processed, but if a significant delay is required between the capture of the payment data and the actual payment, the merchant should consider processing an authorisation on the card at the time the data is captured and later process the payment based on the authorisation rather than the eToken returned by the Payment iFrame.

PayConex Setup

The following setting must be configured when integrating with the Bluefin Payment iFrame.

Account Id

When the iFrame is loaded, the merchant's account id (embedded in src URL) is used to lookup the whitelist of domains. If an incorrect id is used, then the iFrame will not load. The same account id is embedded into the eToken data before encryption. QSAPI will reject transaction requests if the account_id in the request does not match the value embedded in the eToken. This means that eTokens are locked to a merchant account and also means that they cannot be used without the matching api_accesskey on QSAPI.

Domain Whitelist

A whitelist of allowed domains is maintained in the merchant's PayConex settings page.
The list is consulted before the iFrame is loaded and when AJAX requests are received from the iFrame.

Before a merchant can use the iFrame, they have to add their domain to the IFRAME OPTIONS section on their settings page https://secure.payconex.net/admin-site.php. The input supports a comma-separated list of domains, subdomains, and wildcard subdomains. Entries must exclude the protocol.

google.com, bluefin.com, www.bluefin.com, *.example.com

If the iFrame is loaded from a domain not included in this list then a security error message is presented.

Allow Checks/Allow Cards

Depending on which type of iFrame is being rendered (card or check), the iFrame determines if the account settings allow for this particular transaction to take place on that specified account. The account settings in question need to have that payment method enabled to allow the appropriate iFrame to render.

These options are set on the accounts' settings page in Payconex.

iFrame User Interface Configuration

The Payment iFrame supports two ways of controlling its look and feel. A Preset UI option, which allows you to select from a number of preset layouts, styles, and languages options and a Custom Style UI option, which allows you to specify CSS and text to pass into the iFrame. The preset UI options are great for developers who want to know that their iFrame will look the same on across browsers. Whereas, the Custom Style UI is designed for developers who want more control over the iFrame's look and feel.

With the Preset UI, a bootstrap styled iFrame will appear. The appearance of this can be tweaked and tailored within certain boundaries to vary the appearance of the iFrame using the following parameters - expy, number_label, expy_label, cvv_label, layout, input_width, label_width, show_placeholders, input_style, label_font_size, label_font_family, label_font_color, input_font_size, input_font_family, input_font_color.

However, the use of three other parameters - css , text , font - switches the iFrame to the Custom Style UI. It can be styled exactly as the form it is being embedded into, the text can be customized to the developer's wishes and custom fonts can be included in the styling options. Directions and examples on how to implement the iFrame parameters are listed in subsequent sections of this document.

iFrame Security Considerations

The following security measures and restrictions must be taken into consideration when integrating with the Bluefin Payment iFrame.


An eToken from one Bluefin environment cannot be used in another; if a crossover is attempted then the QSAPI request will fail. In Bluefin, certification (http://cert.payconex.net) and production (http://secure.payconex.net) are the considered different environment.

Time to live

All eTokens have a timestamp embedded within them; this timestamp is used to restrict their lifespan to 5 minutes on QSAPI. If a transaction is attempted with an eToken that is older than 5 minutes then it will be rejected.

iFrame Timeout

As the Payment iFrame contains sensitive payment data it is treated with higher security standards. Part of that increased security includes a process whereby the HTML page will timeout after 10 minutes of inactivity. The reasoning behind this feature is to protect end users who may enter their payment data on an open page and then walk away leaving their computer unattended without submitting the page. By automatically redirecting the iFrame we protect their payment data from other users on the same computer.

If a user enters data on the form or if the submit, clear or setMasked functions are called in the API then the timeout is extended another 10 minutes. The default timeout can be overridden with a startup parameter; values between 1 and 60 minutes are allowed.

What’s Next

Now that you've gotten an overview of what the iFrame can do, feel free to start getting setup using our implementation guides.

Did this page help you?