JavaScript Reference

How to implement the constructor and call methods, and how to handle exceptions using the Payment iFrame JavaScript Library.

The iFrame JavaScript library is the keystone of the iFrame solution, as it is this library that allows the client's website to communicate with Bluefin's Payment iFrame while securing the user's payment data and keeping the client's website out of scope of PCI compliance.

The iFrame library is found on Bluefin's server at https://secure.payconex.net/iframe/iframe-lib-1.0.0.js.

You can copy this library to your web server or reference it directly from Bluefin's server; either way, the web page containing the Bluefin Payment iFrame must include this library in order to allow the Payment iFrame to work.

The main component of this library is the PaymentiFrame class. This is the class that you will need to instantiate and call in order for your web page to communicate with the Payment iFrame.

Constructor

Creates an instance of the PaymentiFrame client library.

new PaymentiFrame([settings]);

Parameters

An object that contains settings required to initialize the JavaScript library.

create
Boolean

If create is set to false then the JavaScript library assumes that an iFrame element already exists on the page and it initializes the code with the provided iframeId. If create is set to true then the JavaScript library will build the HTML for the iFrame tag and output it to the page before initializing.

iframeId
String

The ID of the iFrame HTML tag on the page, e.g., payment_iframe

settings
Object

Configuration settings used to configure and construct the iFrame.
This object is only required if the create parameter above is set to true. It sets the look and feel of the iFrame that the PaymentiFrame object will create.
The properties this settings object can have are listed in the tables below.

Settings Object

The different properties of the settings object are grouped by categories in the tables below to make them more readable, but these are all properties of the same object.
Most properties here are the same settings as their equivalent URL parameter settings described in the iFrame Configuration section.

Required Properties

The following two properties are the only required properties for the PaymentiFrame library to create the iFrame, all other properties are optional.

Property name Type Description
account String The merchant's account ID.
parentId String The ID of the HTML element to embed the iFrame element into.

<iframe/> Tag Properties

The following properties will define the HTML attributes of the created <iframe/> tag.

Property name Type Description
devServer String The base URL to load the iFrame from an environment other than production, e.g., "https://cert.payconex.net"
style String Value of the CSS to set on the iFrame tag. Can be used to set the background color for the whole iFrame element, set rounded corners, etc., e.g., "background:tan;"
width String Sets the width of the iFrame element, e.g., "400px"
height String Sets the height of the iFrame element, e.g., "200px"
showFrame Boolean Boolean that sets the frame of the iFrame to visible or not visible.
Default : false

General Properties

The following properties apply for both basic and advanced style customization.

Property name Type Description
lang
(url. lang)
String The language pack to use.
Options : en, es, de, it, fr
Default : en
See iFrame Configuration Language Options section.
payment_method
(url. payment_method)
String The type of transaction (credit card or ACH/check) for which to render the input controls when the iFrame is created.
Options : cc, ach
Default : cc
cvv
(url. cvv)
String Configure if CVV is required, optional or omitted.
Options : required, optional, omit
Default : required
See iFrame Configuration CVV Options section.
expy
(url. expy)
String Sets the type of expiry HTML element(s) to use on the page.
Options : single_input, double_input, single_dropdown, double_dropdown
Default : single_input
See iFrame Configuration Expiry Options section for more details.
timeout
(url. timeout)
String Payment iFrame timeout in minutes. If idle for longer than this period, it redirects to a timeout page.
Options : {1-60}
Default : 10
onload Function A function that is called when the Payment iFrame page has finished loading, e.g., function () {console.log('iFrame loaded');}
masked Object An object containing masked data and eToken that will be placed in the iFrame once it has loaded. The object has two properties eToken and formData, e.g., {formData: {number:"5xxxxxxxxxxx5454", cvv:"xxx", expy: "1234"}, eToken: "xRyzz2-9eRE...jdwPSzA3dbw_TvY"}
See the setting masked data section for more details and sample code.

Basic Customization Properties

The following properties are the basic customization properties. Most of these have URL property equivalents which are described on the iFrame Configuration page.

🚧

Caution

These properties will be overwritten by the advanced style customization properties (shown further below) if the advanced properties are set.

Property name Type Description
layout
(url. layout)
String Sets the general layout for the iFrame.
Options : layout_1 or 1, layout_2 or 2, layout_3 or 3, layout_4 or 4
Default: layout_1 or 1
See iFrame Configuration Layout Options section for more details.
inputStyle
(url. input_style)
String Sets the styles for the input boxes.
Options : input_style_{1-4} or {1-4}
Default: input_style_1 or 1
See iFrame Configuration Input Styles section for more details.
labelFontFamily
(url. label_font_family)
String Sets the font family to use on the label text.
Options : font_family_{1-20} or {1-20}
See iFrame Configuration Font Family Options section for more details.
labelFontSize
(url. label_font_size)
String Sets the font size of the text for the labels.
Options : font_size_{8-34} or {8-34}
See iFrame Configuration Font Size section for more details.
labelFontColor
(url. label_font_color)
String Sets the color of the text on the labels.
Options : Hex color
Default: #000000
inputFontFamily
(url. input_font_family)
String Sets the font family to use on the input/select element text.
Options : font_family_{1-20} or {1-20}
See iFrame Configuration Font Family Options section for more details.
inputFontSize
(url. input_font_size)
String Sets the size of the text on the input/select elements.
Options : font_size_{8-34} or {8-34}
See iFrame Configuration Font Size section for more details.
inputFontColor
(url. input_font_color)
String Sets the color of the text on the input/select elements.
Options : Hex color
Default: #000000
showPlaceholders
(url. show_placeholders)
String Boolean string that sets whether there will be placeholders on the input boxes or not.
Options : "true", "false"
Default: "true"
labelWidth
(url. label_width)
String Sets the width of the text labels for layout_1 and layout_4. Dimensions can be set in pixels, ems or percentages.
Options : {0-1000}px, {0-100}%, {0-100}em
Default: 70%
inputWidth
(url. input_width)
String Sets the width of the input boxes for layout_1 and layout_4. Dimensions can be set in pixels, ems or percentages.
Options : {0-1000}px, {0-100}%, {0-100}em
Default: 29%
numberLabel
(url. number_label)
Number Sets an alternative label text for the card number input field. Caution, this option is not compatible with languages other than English.
Options : {1-3}
See iFrame Configuration Card Number Label section for more details.
expyLabel
(url. expy_label)
Number Sets an alternative label text for the expiration date input field. Caution, this option is not compatible with languages other than English.
Options : {1-3}
See iFrame Configuration Expiration Date Label section for more details.
cvvLabel
(url. cvv_label)
Number Sets an alternative label text for the CVV2 input field. Caution, this option is not compatible with languages other than English.
Options : {1-13}
Default: 1
See iFrame Configuration CVV2 Label section for more details.

Computed Styles

The following properties allow attempting to detect automatically styling for the labels or inputs on the iFrame based on the styles of an existing element of the parent page.

Property name Type Description
matchLabelStyle String The ID or JQuery selector for a HTML element to base the labelFontSize, labelFontFamily and labelFontColor values on, e.g., elm_to_copy
See the Computing style from the parent page section for more details.
matchInputStyle String The ID or JQuery selector for a HTML element to base the inputFontSize, inputFontFamily and inputFontColor values on, e.g., input_elm_to_copy
See the Computing style from the parent page section for more details.

Advanced Customization

The following properties are the advanced customization properties. They have URL equivalent properties.

🚧

Caution

If set, these properties will override the basic customization properties.

Property name Type Description
css
(url. css)
String Custom CSS can allow the iFrame to be styled as the frame it is embedded in. See iFrame Configuration section for a list of the allowed values.
text
(url. text)
String Set these parameters to include custom text on the iFrame's controls. See iFrame Configuration section for a list of the allowed values.
font
(url. font)
String Allows the inclusion of particular fonts on the iFrame. See iFrame Configuration section for a list of the allowed values.

Return Value

The PaymentiFrame object is returned. The Payment iFrame has three core functions encrypt(), setMasked() and clear().

new PaymentiFrame({
    "create"   : false,
    "iframeId" : "payment_iframe"
});
new PaymentiFrame({
    "create"   : true,
    "iframeId" : "payment_iframe",
    "settings" : {
        "account"  : "10000000000",
        "parentId" : "iframe_container",
        "lang"   : "en",
        "cvv"    : "required",
        "expy"   : "single_input",
        "layout" : "1",
        "labelFontFamily" : "13",
        "inputFontFamily" : "13",
        "inputStyle"      : "1",
        "labelFontSize"   : "14",
        "inputFontSize"   : "14",
        "labelFontColor"  : "#000000",
        "inputFontColor" : "#000000",
        "style"     : "background-color:#FFFFFF; border-radius: 20px; padding:20px;",
        "width"     : "300px",
        "height"    : "140px",
        "showFrame" : false,
        "showPlaceholders" : true
    }
});

PaymentiFrame.encrypt()

The encrypt() method sends the card/check payment data from the iFrame to Bluefin's servers where it is encrypted, and it returns an eToken via an EncryptResponse object to the success callback function.

Internally, the encrypt function communicates with the encryption iFrame and instructs it to capture the user's input, validate the input, encrypt the payment data, and send the resulting eToken back to the parent page. The function takes an object as a parameter and returns the EncryptResponse object.

PaymentiFrame.encrypt(options)

Parameters

This method takes an object with the following properties as a parameter:

success
Function
A method that accepts a function as a parameter. The parameter function is executed when the method has executed successfully. The following object is passed to the callback function.

id
String
Unique GUID that identifies the API/function call. The same ID is returned from the encrypt function call.

eToken
String
A token for the captured payment data, this token must be passed in a QSAPI API call to complete a transaction.

masked
Object
An object containing the masked card data. Depending on the type of data captured (credit card or check) the object can contain the following properties:

number
String
A masked payment card number in the following format 4xxxxxxxxxxxxx1234.

expy
String
The unmasked payment expiry value in the clear, e.g., 1219.

cvv
String
The masked CVV value, e.g., xxx or xxxx.

Or an object containing the masked check data.

account_number
String
A masked check account number in the following format 1xxxxxxxx1234.

routing_number
String
The unmasked bank routing number in the clear, e.g., 124302150.

failure
Function
A method that accepts a function as a parameter. The parameter function is executed when the asynchronous encrypt function fails. The following object is passed to the callback function.

id
String
Unique GUID that identifies the API/function call. The same ID is returned from the encrypt function call.

message
String
A human-readable error message.

invalidInput
Function
A method that accepts a function as a parameter. This parameter function is executed when user input fails validation. The purpose of the data passed to this function is to allow the parent page to provide users with feedback.

id
String
Unique GUID that identifies the API/function call. The same ID is returned from the encrypt function call.

invalidInputs
Array
An array of invalidInput objects. The invalidInput object has the following properties:

field
String
Identifies the field with invalid input, must be one of number, expy, or cvv for card transactions or account_number or routing_number for check transactions.

message
String
A human-readable error message for the invalid input.

code
Number
A code to identify the reason that the user input value was rejected. For a full list of codes refer to the Invalid Input Codes section.

Return Value

An EncryptResponse object is returned from the paymentiFrame.encrypt() function.
It contains the success(), failure(), and invalidInput() methods which attach functions to the internal success, failure and invalidInput events. The callback functions passed to these methods have the same signature as the corresponding properties in the settings object.

paymentiFrame.encrypt()
    .success( function (res) {
        alert( "id " + res.id + " token=>" + res.eToken );
    })
    .failure( function (err) {
        alert("Error: " + err.id + " -> " + err.message );
    })
    .invalidInput( function (data) {
        for ( var i = 0; i < data.invalidInputs.length; i++ ){
            alert("Error: " + data.invalidInputs[i].code + " -> " + data.invalidInputs[i].message );
        }
    });
paymentiFrame.encrypt( { 
    success : function (res) {
       alert( "id " + res.id + " token=>" + res.eToken );
    },
    failure : function (err) {
        alert("Error: " + err.id + " -> " + err.message );
    },
    invalidInput : function (data) {
        for ( var i = 0; i < data.invalidInputs.length; i++ ){
            alert("Error: " + data.invalidInputs[i].code + " -> " + data.invalidInputs[i].message );
        }
    });

PaymentiFrame.setMasked()

The setMasked() method populates an iFrame with an eToken and the corresponding masked card data. If the user does not modify the values in the input box then the iFrame outputs the same masked data and eToken when the encrypt() function is called. However, if the user modifies the data in the input fields then the encrypt function will use the new values when creating an eToken. The function takes a settings object as a parameter and returns the MaskedResponse object.

PaymentiFrame.setMasked(maskedData, eToken, [settings])

Parameters

maskedData
Object
An object containing the masked card data. Depending on the type of data captured (credit card or check) the object can contain the following properties:

number
String
A masked payment card number in the following format 4xxxxxxxxxxxxx1234.

expy
String
The unmasked payment expiry value in the clear, e.g., 1219.

cvv
String
The masked CVV value, e.g., xxx or xxxx.

Or an object containing the masked check data.

account_number
String
A masked check account number in the following format 1xxxxxxxx1234.

routing_number
String
The unmasked bank routing number in the clear, e.g., 124302150.

eToken
String

An eToken obtained through the paymentiFrame.encrypt() function.

settings
Object
A set of key/value pairs that configure the encryption function call. All properties are optional.

success
Function(Object))
A function to be called when the asynchronous encrypt function successfully finishes. The function gets passed one argument, an Object with three properties:

id
String
Unique GUID that identifies the API/function call. The same ID is returned from the encrypt function call.
eToken
String
A token for the captured payment data, this token must be passed in a QSAPI API call to complete a transaction.

masked
Object
An object containing the masked card data. Depending on the type of data captured (Credit card or check) the object can contain the following properties:

number
String
A masked payment card number in the following format 4xxxxxxxxxxxxx1234.

expy
String
The unmasked payment expiry value in the clear, e.g., 1219.

cvv
String
The masked CVV value, e.g., xxx or xxxx.

And the following for check transactions

account_number
String
A masked check account number in the following format 1xxxxxxxx1234.

routing_number
String
The unmasked bank routing number in the clear, e.g., 124302150.

failure
Function
A method that accepts a function as a parameter. The parameter function is executed when the asynchronous encrypt function fails. The following object is passed to the callback function.

id
String
Unique GUID that identifies the API/function call. The same ID is returned from the encrypt function call.

message
String
A human-readable error message.

Return Value

A MaskedResponse object is returned from the PaymentiFrame.setMasked() function.
It contains the success() and failure() methods which attach functions to the internal success and failure events.

The callback functions passed to these methods have the same signature as the corresponding properties in the settings object.

var masked_data = {
            number : "5xxxxxxxxxxx5454",
            cvv    : "xxx",
            expy   : "1234"
        };

var eToken = "xRyzz2-9eREX_7Zu2Ix1zamDV2cMkqNKb4P05-CU-KXGhAfmfz67AVj0qkj3N278Khw80rxjzKfZEYdtnKPOnIzcgPlJRZ6weC4AVc5WQR00yhgT-Hcg0dAF7faZXSYd-J1-u94cTfsQwJmo5i5lGYIPGGa7Kex3w9-OO9VTFjdhFFVmAsuNx1ugJnGESy4zdeyR8N53H8D_nCOJ5jdwPSzA3dbw_TvY";

    
PaymentiFrame.setMasked( masked_data, eToken )
            .success(function(res){
                alert(res);
            })
            .failure(function(err){
                alert(err);
            });

PaymentiFrame.clear()

Clears the input fields within the iFrame.

PaymentiFrame.clear(options)

Parameters

This method takes an object which is a set of key/value pairs that configures the clear function call. All properties are optional.

success
Function
A function to be called when the asynchronous clear function successfully finishes. The function gets passed one argument, an object with a single property ID which contains a unique identifier for the API call.

id
String
Unique GUID that identifies the API/function call. The same ID is returned from the encrypt function call.

failure
Function
A method that accepts a function as a parameter. The parameter function is executed when the asynchronous encrypt function fails. The following object is passed to the callback function.

id
String
An ID which contains a unique identifier for the API call.

message
String
A human-readable error message.

Return Value

A ClearResponse object is returned from the PaymentiFrame.clear() function.
It contains the success() and failure() methods which attach functions to the internal success and failure events. The callback functions passed to these methods have the same signature as the corresponding properties in the settings object.

PaymentiFrame.clear()
    .success(function (res){
        alert("cleared");
    })
    .failure(function (err) {
        alert("failed to clear");
    });
PaymentiFrame.clear({
    success: function (res){
                 alert("cleared");
             },
    failure: function (err) {
                 alert("failed to clear");
             }
});

Throw new BluefinException()

There are certain conditions where the PaymentiFrame library will throw an exception during construction. These exceptions are only thrown in scenarios where the library cannot continue with stability, e.g., iFrame cannot be found. All exceptions are of type BluefinException.

BluefinException Object

The BluefinException object contains information about the circumstances that caused the exception to be thrown. It has :

name
String
Object name. This is always set to BluefinException.

message
String
A human-readable readable message that describes the exception.

code
Number
The code identifies the circumstances that caused the exception to be thrown. The codes are as follows:

100 an element with the ID provided in the iframeId cannot be found on the page.
101 an element with the iframeId was found on the page but it was not an iFrame.
102 an iFrame with the iframeId was found but its source is not pointing to a valid Bluefin domain.
103 an iFrame with the iframeId was found but it does not point to the correct path.

try {
    var paymentiFrame = new PaymentiFrame({
        "create": false,
        "iframeId": "payment_iframe",
    });
} catch (error) {
    alert( error.name + ' [' + error.code + '] error message: ' + error.message );
}