Integration Guide

Overview

Integrating PCI Widgets into a web application requires embedding the widget in an HTML file, configuring it using JavaScript, and ensuring secure token handling. The integration process involves loading the Qolo PCI Widget script, defining a widget configuration using JSON, and implementing callback functions for success and failure handling.

This section provides step-by-step instructions on embedding PCI Widgets in an HTML document, setting up callbacks for user interactions, and handling API calls for token management.

Embedding Widgets in HTML

To integrate PCI Widgets into a web application, you need to:

Load the Qolo JavaScript file – This script initializes the PCI Widget.
Create a container element – The widget will be embedded inside this <div>.
Define widget configuration in JavaScript – The JSON object specifies the widget type, behavior, and security settings.

PCI Widget Tutorial

Step 1: Initialize Qolo Widget in HTML File

<!doctype html>
<html>
  <head>
    <meta charset="utf-8">
    <title>Qolo PCI Widget</title>
  </head>
  <body>
      <script type="text/javascript" src="https://stg-widgets.qolopay.com/widgets/js/qolo.initialize.v3.js"></script>
  </body>
</html>

Step2 : Retrieve a session token

fetch('/api/v1/auth/token?card_proxy=1234567890', {
    method: 'GET',
    headers: {
        'Authorization': 'Bearer your-jwt-token'
    }
})

Step 3: Configure Widget Operation with Session Token

 widget = {
                onSuccess: (details) => {
                        console.log("pci widget completed successfully-test", details);
                    },
                onFailure: (details) => {
                        console.log("pci widget failure-test", details);
                    },
                frame: {
                        container_id: 'widget_container',
                        iframe_class: 'widget-iframe',
                        //loading spinner
                        //spinner: true
                        //loading_class:
                        filter: 'invert(27%) sepia(51%) saturate(2878%) hue-rotate(346deg) brightness(104%)',
                        //margin:
                        //width:
                        //display:
                    },
                target_origin: 'https: //stg-widgets.qolopay.com',
                config: {
                        token: '4aea9a89-394b-4307-a805-9d3300bc0bb0',
                        main: 'show_pan'
                    }
        };
        pciWidget(widget);

Sample HTML Structure

The following is a basic HTML template for integrating a PCI Widget into a webpage:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8" />
    <title>PCI Widget Integration</title>
    <meta http-equiv="X-UA-Compatible" content="IE=edge, chrome=1" />
    <meta name="viewport" content="width=device-width, initial-scale=1, minimum-scale=1" />
    <meta name="description" content="PCI Widget Integration Example" />
    
    <style type="text/css">
        .widget-iframe {
            border: 0;
            width: 100%;
            height: 600px;
        }
        body {
            margin: 0 auto;
        }
    </style>
</head>
<body>

    <!-- Widget Container -->
    <div id="widget_container" name="widget_container"></div>

    <!-- Load Qolo PCI Widget JavaScript File -->
    <script type="text/javascript" src="https://stg-widgets.qolopay.com/widgets/js/qolo.initialize.v3.js"></script>

    <script type="text/javascript">
      fetch('/api/v1/auth/token?card_proxy=1234567890', {
        method: 'GET',
        headers: {
          'Authorization': 'Bearer your-jwt-token'
        }
      })
        .then(response => response.json())
        .then(data => {
        let widgetConfig == {
            onSuccess: (details) => {
                console.log("PCI Widget completed successfully", details);
            },
            onFailure: (details) => {
                console.log("PCI Widget failed", details);
            },
            frame: {
                container_id: 'widget_container',
                iframe_class: 'widget-iframe',
            },
            config: {
                token: 'your-secure-token-here',
                require: 'validate_card',
                main: 'cvv_only',
                payment: 'external_payment'
            }
        };
        pciWidget(widgetConfig);
      })
      .catch(error => console.error('Error fetching token:', error));
    </script>

</body>
</html>

Key Elements in the HTML Structure

Widget Container (<div id="widget_container">)
- The widget is injected into this container.
PCI Widget JavaScript File
- The <script> tag loads the widget from the Qolo staging environment.
- URL: https://stg-widgets.qolopay.com/widgets/js/qolo.initialize.v3.js
JavaScript Configuration (widget object)
- This defines the widget’s behavior, including the security token, validation requirements, and core functions and payment options.

Script and Callback Functions (onSuccess, onFailure, etc.)

Callback Functions

PCI Widgets support callback functions to handle different events during widget interaction.

Callback Function	Purpose
`onSuccess(details)`	Executes when the widget completes successfully.
`onFailure(details)`	Executes when an error occurs in the widget.
`onLoadIframe(details)`	Executes when the widget iframe has loaded.

Example with Callbacks

widget = {
    onSuccess: (details) => {
        console.log("PCI Widget completed successfully", details);
    },
    onFailure: (details) => {
        console.log("PCI Widget failed", details);
    },
    onLoadIframe: (details) => {
        console.log("PCI Widget iframe loaded", details);
    },
    frame: {
        container_id: 'widget_container',
        iframe_class: 'widget-iframe',
    },
    config: {
        token: 'your-secure-token-here',
        require: 'validate_card',
        main: 'show_pan'
    }
};

Customizing Callback Functions

These functions can be used to trigger additional logic, such as:

Displaying confirmation messages.
Redirecting users to another page upon success.
Logging failures for debugging.

Summary

Embedding PCI Widgets requires adding the JavaScript file, defining a container, and configuring a JSON object.
Callback functions (onSuccess, onFailure, onLoadIframe) allow handling widget interactions.