Setup

Learn how to initialize the PayConex iFrame and start collecting payments.

The Payment iFrame can be implemented two ways:

  • Using an <iframe /> HTML tag.
  • Letting the Payment iFrame create the <iframe /> for you, inside a parent element that you specify.

Both methods are shown below. The methods are the same except steps 4 and 5.

🚧

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
722722

Download the Payment iFrame JavaScript Library

The Payment iFrame JavaScript library can be downloaded from the Bluefin server. You may upload a copy of this library to your website or use the library directly from 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 with 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 above, the Payment iFrame can be initialized with JavaScript alone.

Add a Parent HTML Element

Add an html element to your page where you want the Payment iFrame to appear.

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

Initialize the JavaScript Library

Next, initialize the iFrame JavaScript client library with the create flag set to true. 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 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.

We recommend you 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, the iFrame is placed on the page and the rest of the initialization function is executed. If it is not found, 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.

By placing the JavaScript invocation after the parent HTML element, as in the example below, the Payment iFrame is loaded immediately:

<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>

Another example, but 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>