Skip to content
Global Payments Oceania API Global Payments Oceania API

Secure Panel v1.1.0

The Secure Panel solution provides the flexibility of a credit card form that appears entirely on your website, but the fields are actually hosted securely by Global Payments. This gives you the benefit of a PCI DSS compliant solution to securely collect credit card information, whilst still having full control over the customer experience on your website.

Even though the contents of the Secure Panel are hosted by Global Payments, you can provide layout and styling so that the Secure Panel merges seamlessly into your website.

Because all credit card controls reside in the same iframe, customers can use the autofill capabilities of modern web browsers to populate their card details with a single click. To take advantage of autofill, it is a requirement that SSL is used to secure the webpage and provide reassurance to customers.

What’s New in v1.1.0

  • Added surcharging functionality - The Secure Panel now supports automatic surcharge calculation and display based on the card number entered by the customer.

SecurePanel Supported Use Cases

Transaction Flow with Surcharging

  • Transaction Flow with Surcharging - This flow includes the new surcharging functionality added in v1.1.0
sequenceDiagram
    autonumber
    participant End_User(Browser)
    box rgb(240,230,210) Merchant
    participant Merchant_Website
    participant Merchant_Server
    end
    box rgb(210,240,230) GP
    participant SingleAPI
    participant SingleAPI_Hosted
    participant SecurePanel
    end
    
    End_User(Browser)<<->>Merchant_Website: Request Merchant Website
    End_User(Browser)<<->>Merchant_Website: Navigate to Payments Page
    Merchant_Website->>Merchant_Server: Request PaymentsPage
    Merchant_Server->>SingleAPI: Request One-Time Token (/tokens)
    SingleAPI-->>Merchant_Server: Return One-Time Token
    Merchant_Server->>Merchant_Website: Send One-Time Token
    Merchant_Website->>End_User(Browser): Render PaymentsPage
    End_User(Browser)->>SingleAPI_Hosted: Request SecurePanel.js
    SingleAPI_Hosted-->>End_User(Browser): Provide SecurePanel.js
    End_User(Browser)->>SecurePanel: SecurePanel.js - Initialise with One-Time Token and Amount
    SecurePanel->>End_User(Browser): Render SecurePanel in Iframe
    End_User(Browser)->>End_User(Browser): End User - Input Card Number
    SecurePanel->>End_User(Browser): Trigger Surcharge Callback with Surcharge Amount
    End_User(Browser)->>End_User(Browser): Display Surcharge Amount to User
    End_User(Browser)->>End_User(Browser): End User - Complete Remaining Card Details
    End_User(Browser)->>SecurePanel: Submit - SecurePanel.js - Process with One-Time token and Card Information
    SecurePanel->>End_User(Browser): Process Response (canProcessTransaction=true)
    End_User(Browser)->>Merchant_Website: Process Transaction with One-Time Token
    Merchant_Website->>Merchant_Server: Process Transaction with One-Time Token
    Merchant_Server->>SingleAPI: Process Transaction (/transactions) with One-Time Token 
    SingleAPI-->>Merchant_Server: Transaction Response
    Merchant_Server-->>Merchant_Website: Transaction Response
    Merchant_Website-->>End_User(Browser): Display Transaction Response to End User

Token Flow with Surcharging

  • Token Flow with Surcharging - This flow includes the new surcharging functionality added in v1.1.0
sequenceDiagram
    autonumber
    participant End_User(Browser)
    box rgb(240,230,210) Merchant
    participant Merchant_Website
    participant Merchant_Server
    end
    box rgb(210,240,230) GP
    participant SingleAPI
    participant SingleAPI_Hosted
    participant SecurePanel
    participant Surcharge
    end
    
    End_User(Browser)<<->>Merchant_Website: Request Merchant Website
    End_User(Browser)<<->>Merchant_Website: Navigate to Payments Page
    Merchant_Website->>Merchant_Server: Request PaymentsPage
    Merchant_Server->>SingleAPI: Request One-Time Token (/tokens)
    SingleAPI-->>Merchant_Server: Return One-Time Token
    Merchant_Server->>Merchant_Website: Send One-Time Token
    Merchant_Website->>End_User(Browser): Render PaymentsPage
    End_User(Browser)->>SingleAPI_Hosted: Request SecurePanel.js
    SingleAPI_Hosted-->>End_User(Browser): Provide SecurePanel.js
    End_User(Browser)->>SecurePanel: SecurePanel.js - Initialise with One-Time Token and Amount
    SecurePanel->>Surcharge: Request Surcharge Amount and static data based on CardType (Domectic Surcharge %)
    SecurePanel->> SecurePanel: Return Surcharge Amount & static data % as part of Initialise Response
    SecurePanel->>End_User(Browser): Render SecurePanel in Iframe
    End_User(Browser)->>End_User(Browser): End User - Input Card Number
    SecurePanel->>End_User(Browser): Trigger Surcharge Callback with Surcharge Amount
    End_User(Browser)->>End_User(Browser): Display Surcharge Amount to User
    End_User(Browser)->>End_User(Browser): End User - Complete Remaining Card Details
    End_User(Browser)->>SecurePanel: Submit - SecurePanel.js - Process with One-Time token and Card Information
    SecurePanel->>End_User(Browser): Process Response (canProcessTransaction=true)
    End_User(Browser)->>Merchant_Website: Create Card on File with One-Time Token
    Merchant_Website->>Merchant_Server: Create Card on File with One-Time Token
    Merchant_Server->>SingleAPI: Create Payer (/customers)
    SingleAPI-->>Merchant_Server: Payer Response
    Merchant_Server->>SingleAPI: Create Token (/customers/{id}/paymentinstruments) with One-Time Token
    SingleAPI-->>Merchant_Server: Token Response
    Merchant_Server-->>Merchant_Website: Token Response
    Merchant_Website-->>End_User(Browser): Display Token Response to End User

Implementing the Secure Panel requires:

  • Using JavaScript and HTML to add the Secure Panel to your website.
  • Passing the oneTimeToken to the Transactions API to complete the transaction.

Requirements for Secure Panel

To include the Secure Panel in an existing web page, first the latest version of securepanel.min.js JavaScript needs to be included:

Sandbox:

<script src="https://sandbox.hosted.gpaunz.com/static/securepanel/1.1.0/js/securepanel.min.js" data-init="false"></script>

Production:

<script src="https://hosted.gpaunz.com/static/securepanel/1.1.0/js/securepanel.min.js" data-init="false"></script>

The Secure Panel supports the following desktop browsers:

  • Chrome 38+
  • Safari 10.1+
  • Firefox 29+
  • Edge 15+
  • Opera 25+

The Secure Panel supports the following mobile browsers:

  • iOS Safari 9+ and other browsers and web views which use the system-provided WebKit engine
  • Android Chrome 38+
  • Samsung Browser 7.1+

TLS 1.2 must also be supported by the browser.

If an unsupported browser is encountered, a system_error will be returned in the response object.

NOTE: The Secure Panel identifies the browser by using the user-agent string. If the user-agent is missing, it will be treated as an unsupported browser.

Step 1: Configure the Secure Panel

The Secure Panel requires a config that tells Global Payments what fields to display and how they should look. This is done with a JavaScript object, which accepts the following values:

  • oneTimeToken: The one time token obtained from the /tokens endpoint. Each page impression should have a separate oneTimeToken.
  • fieldDivId: The id of the div to place the Secure Panel iframe in.
  • layout : A JavaScript object that describes the fields and labels that are to be displayed in the Secure Panel (for customising the layout see step 5).

The Secure Panel requires a corresponding <div> with the id defined in the configuration. See the below html example that generates a simple HTML page containing the Secure Panel.

<html>
<head>
  <script src="https://hosted.gpaunz.com/static/securepanel/1.1.0/js/securepanel.min.js" data-init="false"></script>
</head>
<body>
<script type="text/javascript">
    var oneTimeToken = "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"; // replace with your onetimetoken
    var purchaseAmount = 100.00; // purchase amount


    var config = {
        oneTimeToken: oneTimeToken,
        fieldDivId: "secure-panel",
        layout : {
            rows : [ {
                        cells:  [ {
                                    colspan: 6,
                                    label: { text: "Card Name:", fieldColspan: 5 },
                                    field: { fieldType: "name", fieldColspan: 7 }
                                  }, {
                                    colspan: 6,
                                    label: { text: "Card Number:", fieldColspan: 5 },
                                    field: { fieldType: "number", fieldColspan: 7 }
                                  }
                        ],
                     },
                     {
                        cells:  [ {
                                    colspan: 6,
                                    label: { text: "Expiry:", fieldColspan: 5 },
                                    field: { fieldType: "expiry", fieldColspan: 7 }
                                  }, {
                                    colspan: 6,
                                    label: { text: "CVV Number:", fieldColspan: 5 },
                                    field: { fieldType: "cvn", fieldColspan: 7 }
                                  }
                        ]
                     }
            ]
        }
    };


</script>
<h1> This is a simple page demonstrating the Global Payments Secure Panel with Surcharging</h1>
<div id="secure-panel"></div>
<div id="surcharge-amount"></div><br><br>
<input id="submit-secure-panel" type="button" value="Submit" />
</body>
</html>

Step 2: Initialise the Secure Panel with Surcharging

In version 1.1.0, the Secure Panel supports surcharging functionality. This requires passing an additional parameter (initialiseModel) with the transaction amount and a surcharge callback function to handle the surcharge amount returned after the customer enters their card number.

function initialiseCallback(response) {
  console.log("response", response);
}


function surchargeCallback(response, data) {
  console.log("surcharge amount: ", data.surcharge);
}


var initialiseModel = { amount: <purchase amount> };


window.addEventListener("load", function (event) {
  GPAUNZ.SecurePanel.initialise(config, initialiseModel, initialiseCallback, null, surchargeCallback);
});

The surchargeCallback function will be triggered after the customer enters their card number, allowing your website to display the surcharge amount to the customer before they complete their payment.

The response object has the following structure:

{
   result : {
       status: "<standard api status: one of ok, validation_error, system_error>",
       codes: [
          {
             id: "<standard api codes>",
             message: "<standard api code message>"
          }
       ]
   }
}

Step 3: Collect the Card Details

In this step, the customer enters their card details directly into the credit card fields rendered in the Secure Panel.

When using Secure Panel v1.1.0 with surcharging enabled, the following process occurs:

  1. The customer enters their card number
  2. The Secure Panel triggers the surcharge callback with the calculated surcharge amount
  3. Your website can display this surcharge amount to the customer
  4. The customer completes the remaining card details (expiry date, CVV)

Step 4: Process the Completed Secure Panel

When the containing form is submitted in your website, the Secure Panel processing operation requires a JavaScript callback function that will return a response object and data object. The response object contains any validation or error statuses. The data object contains hints as to the subsequent API calls required to complete the transaction.

An example of the processing callback function is as follows:

function processCallback(response, data) {
    console.log("response", response);
    console.log("data", data);
  }

The response object has the following structure:

{
   result : {
       status: "<standard api status: one of ok, validation_error, system_error>",
       codes: [
          {
             id: "<standard api codes>",
             message: "<standard api code message>"
          }
       ]
   }
}

The data object has the following structure:

{
   canCreateTransaction: <flag indicating a transaction can be created using the oneTimeToken>
}

The Secure Panel processing operation is triggered by calling the process function, as follows:

  button.addEventListener("click", function (event) {
    GPAUNZ.SecurePanel.process(processCallback);
  });

Final html with Surcharging

<html>
<head>
  <script src="https://hosted.gpaunz.com/static/securepanel/1.1.0/js/securepanel.min.js" data-init="false"></script>
</head>
<body>
<script type="text/javascript">
    var oneTimeToken = "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"; // replace with your onetimetoken
    var purchaseAmount = 100.00; // purchase amount


    var config = {
        oneTimeToken: oneTimeToken,
        fieldDivId: "secure-panel",
        layout : {
            rows : [ {
                        cells:  [ {
                                    colspan: 6,
                                    label: { text: "Card Name:", fieldColspan: 5 },
                                    field: { fieldType: "name", fieldColspan: 7 }
                                  }, {
                                    colspan: 6,
                                    label: { text: "Card Number:", fieldColspan: 5 },
                                    field: { fieldType: "number", fieldColspan: 7 }
                                  }
                        ],
                     },
                     {
                        cells:  [ {
                                    colspan: 6,
                                    label: { text: "Expiry:", fieldColspan: 5 },
                                    field: { fieldType: "expiry", fieldColspan: 7 }
                                  }, {
                                    colspan: 6,
                                    label: { text: "CVV Number:", fieldColspan: 5 },
                                    field: { fieldType: "cvn", fieldColspan: 7 }
                                  }
                        ]
                     }
            ]
        }
    };


    function initialiseCallback(response) {
    console.log("response", response);
  }


    function surchargeCallback(response, data) {
        console.log("surcharge amount: ", data.surcharge);
        // Update your UI to display the surcharge amount to the customer
        document.getElementById('surcharge-amount').textContent = "Surcharge: $" + data.surcharge;
    }


    function processCallback(response, data) {
    console.log("response", response);
    console.log("data", data);
  }


    var initialiseModel = { amount: purchaseAmount };


    window.addEventListener("load", function (event) {
      GPAUNZ.SecurePanel.initialise(config, initialiseModel, initialiseCallback, null, surchargeCallback);


        let button = document.getElementById('submit-secure-panel');


        button.addEventListener("click", function (event) {
        GPAUNZ.SecurePanel.process(processCallback);
      });
  });


</script>
<h1> This is a simple page demonstrating the Global Payments Secure Panel with Surcharging</h1>
<div id="secure-panel"></div>
<div id="surcharge-amount"></div><br><br>
<input id="submit-secure-panel" type="button" value="Submit" />
</body>
</html>

A thing to know

You need to replace the oneTimeToken value with your own oneTimeToken value that you have obtained by calling SingleAPI

Secure Panel Sample App

To further understand the whole server side interaction works, we have created a sample app ( it is only to demonstrate the integration and api calls involved, this is not production grade code)

Customising the Secure Panel

The Secure Panel can be constructed from any combination of credit card fields that can be displayed in any order. How the fields and their respective labels are displayed is defined using the layout value in the Secure Panel definition.

The layout value is a JSON object with a structure defined below. It describes which fields and labels are to appear in the iframe, using a row/column structure. You can use colSpan values to control the spacing, and additionally you’re able to specify class elements for each field control, label, the containing divs for each, and the overall containing divs. Only classes provided by Bootstrap are supported.

The HTML generated from the layout is a Bootstrap style responsive layout using divs and CSS. Spacing for each element in a row, and for the spacing of each label/field is controlled using colSpan values of 1-12. At iframe widths of 480 pixels or less, each element stacks (i.e. consumes all 12 of the available columns).

Default values are provided for simple layouts which evenly space each label/field pair in a row. Style properties can be set on each element and containing div, allowing precise spacing to match existing grids. In general, use of padding on containing divs is the best approach to achieve a specific alignment as that ensures that iFrame scrollbars will not occur.

layout Object Definition

  • rows: An array of JavaScript objects, each of which describes one row of the layout (see row object below).

row Object Definition

Each row object in a layout’s rows array describes a single row consisting of multiple cells. It also contains class values to apply to the containing div for the row. It contains the following values:

  • classes: (optional), string. This value is set on the containing div for the row.
  • cells: array of JavaScript objects, each of which describes a label and a field (see “cell” object below).

cell Object Definition

Each cell object in the cells array describes a single field, and its label along with style and spacing properties. It contains the following values:

  • classes: (optional), string. A set of classes to apply to the containing div.
  • colSpan: (optional), number. A value from 1-12 describing what portion of the row the cell consumes when the browser width is greater than 480px.
  • label: object. Describes the label to use for this field, and any additional styles. (see details below).
  • field: object. The field to display. (see “field” object below for details).

label Object Definition

Describes the label that is attached to the field. It contains following values:

  • text: string. Display text.
  • classes: (optional) string. Additional classes to be applied to the label itself.
  • fieldColSpan: (optional) number. Value from 1-12 describing what portion of the cell is consumed by the label when the browser width is greater than 480px.

field Object Definition

Describes a field to be displayed in the Secure Panel. It contains following values:

  • fieldType: string. The type of credit card field to display. May be one of the following (name, expiry, cvn, number)
  • classes: (optional) string: classes attached to the field control.
  • fieldColSpan: (optional) number: value from 1-12 describing what portion of the cell is consumed by the control when the browser width is greater than 480px.