JavaScript Reference

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.

<iframe/> Tag Properties

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

General Properties

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

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.

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.

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.

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 );
}