Setup

Learn how to initialize the PayConex iFrame and start collecting payments

The Payment iFrame can either implemented using an <iframe /> HTML tag or by letting the Payment iFrame create the <iframe /> for you, inside a parent element that you specify. Both methods are shown below, these only differ in steps 4 and 5, the other steps apply to both methods.

🚧

Important

If you are integrating with the Payment iFrame for development purposes, please change the base url of the iFrame to the Bluefin development server https://cert.payconex.net/.

iFrame Implementation

Settings

Add your website domains to the settings page under Domain Whitelist

google.com,bluefin.com, www.bluefin.com

Download the Payment iFrame JavaScript Library

The Payment iFrame JavaScript library can be downloaded from the Bluefin Server. You may either choose to upload a copy of this library to your website or use the library directly form the Bluefin Server at the following url:

https://secure.payconex.net/iframe/iframe-lib-1.0.0.js

Load iFrame JavaScript Library

Embed the Javascript library on your HTML page.

If you are hosting the library on your server:

<script type="text/javascript" src="/js/iframe-lib-1.0.0.js"></script>

If you are using the library directly from Bluefin's servers:

<script type="text/javascript" src="https://secure.payconex.net/iframe/iframe-lib-1.0.0.js"></script>

Add iFrame element

Add an iFrame element that points to the Bluefin iFrame server on the HTML page. Make sure to replace the aid value in the src attribute to your Bluefin account id.

<iframe
 id="payment_iframe"
 width="300px"
 height="140px"
 style="background-color:#FFFFFF; border-radius: 20px; padding:20px;"
 frameborder="0"
 src="https://secure.payconex.net/iframe?aid=000000000001&lang=en&cvv=required&expy=single_input&layout=4&show_placeholders=true&label_font_family=13&label_font_size=14&input_style=1&label_font_color=%23000000">
</iframe>

Initialize the Javascript Library

The following example is in javascript.

var paymentiFrame = new PaymentiFrame({
     create   : false,
     iframeId : "payment_iframe"
});

Integrate Into the Web Application

Integrate the encrypt, setMasked, and clear functions into your the web application. E.g. call the encrypt function when the user clicks the pay now button.

Sample code that attaches callback functions to the encrypt API call:

$("#pay_now_button").click(function(){
 paymentiFrame.encrypt()
     .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 );
         }
     })
     .success( function (res) {
         alert( "id " + res.id + " token=>" + res.eToken );
     })
 return false;
});

The same code using the alternative method for specifying the callbacks:

$("#pay_now_button").click(function(){
 paymentiFrame.encrypt({
     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 );
         }
     },
     success : function (res) {
         alert( "id " + res.id + " token=>" + res.eToken );
     }
 })
 return false;
});

Alternative Payment iFrame Initialization

As an alternative to steps 4 and 5 in the Quickstart Guide the Payment iFrame can be initialized with JavaScript alone.

Add a Parent HTML Element

Add an html element to your page in the location that you want the Payment iFrame to appear.

<div id="iframe_container"></div>

Initialize the JavaScript Library

Next, when we initialize the iFrame JavaScript client library with the create flag set to true. We also pass a settings object that contains the URL configuration properties as well as a number of configuration options for the iFrame tag.

🚧

Important

The parentId in the settings object that must match up with the id of the HTML element that is placed on the page.

The devServer value in the settings object overrides the default server from which the iFrame is loaded.

The onload property in the settings object attaches a JavaScript function to be executed once the page has loaded within the Payment iFrame. This is useful when used in combination with the setMasked function.

It is recommended to initialize the Payment iFrame after the parent HTML element has been created, rather than before.

The following example will initialize an iFrame for a card transaction with basic styling options implemented:

new PaymentiFrame({
 create: true,
 iframeId: "payment_iframe",
 settings: {
     account         : "000000000001",
     parentId        : "iframe_container",
     lang            : "en",
     cvv             : "required",
     expy            : "single_input",
     layout          : "1",
     inputFontFamily : "13",
     inputStyle      : "1",
     labelFontSize   : "14",
     labelFontColor  : "#000000",
     style           : "background-color:#FFFFFF; border-radius: 20px; padding:20px;",
     width           : "300px",
     height          : "140px",
     showFrame       : false,
     devServer       : "https://cert.payconex.net",
     onload          : function(){ alert("The Payment iFrame has loaded") }
 }
});

This example initializes an iFrame for a card transaction with more advanced options implemented - applying custom CSS and label text to the iFrame as well as harnessing custom fonts:

new PaymentiFrame({
 create: true,
 iframeId: "payment_iframe",
 settings: {
     account         : "000000000001",
     parentId        : "iframe_container",
     lang            : "en",
     cvv             : "required",
     width           : "300px",
     height          : "140px",
     showFrame       : false,
     devServer       : "https://cert.payconex.net",
     onload          : function(){ alert("The Payment iFrame has loaded") },
     payment_method  : "cc",
     css             : {
         class_label           : "width: 200px",
         id_expy_label         : "font-weight:600;font-family:Macondo;",
         id_cvv_label          : "color:#999999;"
     },
     text     : {
         number : {
             label       : "Enter Card Number",
             placeholder : "eg 4444333322221111"
         },
         cvv : {
             label       : "Enter CVV Number",
             placeholder : "eg CVV"
         },
         expy_double : {
             label         : "Enter Card Expiry Number",
             placeholder_1 : "Enter Month",
             placeholder_2 : "Enter Year"
         }
     },
     font     : {
         font_1 : {
             file   : "ProximaNova-Reg-webfont.woff",
             family : "ProximaNova"
         },
         font_2 : {
             file   : "ProximaNova-Sbold-webfont.ttf",
             family : "ProximaNova bold"
         }
     }
 }
});

This example initializes an iFrame for an ach/check transaction with more advanced styling options implemented - note the differences in the payment_method parameter value and the text parameter values to reflect this.

new PaymentiFrame({
 create: true,
 iframeId: "payment_iframe",
 settings: {
     account         : "000000000001",
     parentId        : "iframe_container",
     lang            : "en",
     cvv             : "required",
     width           : "300px",
     height          : "140px",
     showFrame       : false,
     devServer       : "https://cert.payconex.net",
     payment_method  : "ach",
     css             : {
         class_label           : "width: 200px",
         id_routing_label      : "font-weight:600;",
         id_account_label      : "color:#999999;"
     },
     text     : {
         bank_account : {
             label       : "Enter Account Number",
             placeholder : "eg 14251245645"
         },
         routing_number : {
             label       : "Enter Routing Number",
             placeholder : "eg 121122676"
         }
     }
 }
});

When to Initialize the Payment iFrame Library

When using the JavaScript API to initialize the Payment iFrame, the API first looks for the parent element (parentId in the settings). If it is found then the iFrame is placed on the page and the rest of the initialization function is executed. If it is not found then the iFrame output and remainder of the initialization is placed in a callback function which is attached to an "DOMContentLoaded" event, in a similar way as would do a jQuery ready function, and executed after the page has fully loaded. Consequently, the iFrame is not loaded until the other elements on the page load first.

To avoid this behavior and speed up the loading of the Payment iFrame, the JavaScript constructor invocation code should be placed after the parent HTML element on the page.

<html>
  <head>
    <title>My checkout page</title>
  </head>
  <body>
    <div id="iframe_container"></div>

    <script type="text/javascript">
      new PaymentiFrame({
        create: true,
        iframeId: "payment_iframe",
        settings: {
            account    : "000000000001",
            parentId   : "iframe_container"
        }
      });
    </script>
  </body>
</html>

By placing the JavaScript invocation after the parent HTML element the Payment iFrame is loaded immediately.

Similar example, but this time using an inline script tag:

<html>
  <head>
    <title>My checkout page</title>
  </head>
  <body>
    <div id="iframe_container"></div>
    <script type="text/javascript" src="application_logic.js"></script>
  </body>
</html>

Did this page help you?