Getting Started

Introduction

Using Qolo's PCI Widgets involves generating a token to access the widgets, with an optional step to require authentication before accessing or updating sensitive data. The different phases of Qolo's PCI Widget are categorized into three primary groups: Validation (referred to as "require"), Core Function (referred to as "main"), and Payment Processing (referred to as "payment") in the PCI widget configuration.

PCI Components

Detailed below are the primary groups of the PCI widget and its field parameters used in the configuration of the PCI widget.

Validation

An added step to require users to verify a card before accessing or updating it.

Core Function

Card action required by users.

Payment Processing

Payment action required by users.

Widgets are configured to meet specific business requirements.

Generating a Token

In order to generate a PCI Widget Session, a token is required to authenticate the use of widgets. These tokens ensure that sensitive operations remain secure and are valid only for a single transaction or session.

How to Generate a Token

• Requires authentication using a JWT (JSON Web Token).

1. Identify the widget you want to generate using the parameters listed below:

   Parameter	Purpose
   card_proxy	Used when validating or setting a card-related widget.
   program_guid	Used for generating a token for external card capture.
   person_guid	Used for generating a token for external payments.

2. Token Generation Requests:

• Generate a token for validating a card:

curl --location --request GET 'https://<HOST PROVIDED BY QOLO>/api/v1/auth/token?card_proxy={{card_proxy}}' \
--H 'Content-type: application/json' \
--H 'Authorization: Bearer <YOUR_JWT_HERE>' \

• Generate a token for external payment:

curl --location --request GET 'https://<HOST PROVIDED BY QOLO>/api/v1/auth/token?person_guid={{person_guid}}' \
--H 'Content-type: application/json' \
--H 'Authorization: Bearer <YOUR_JWT_HERE>' 

• Generate a token for external card capture:

curl --location --request GET 'https://<HOST PROVIDED BY QOLO>/api/v1/auth/token?program_guid={{program_guid}}' \
--H 'Content-type: application/json' \
--H 'Authorization: Bearer <YOUR_JWT_HERE>' 

Token Generation Request by Widget Type

Token Expiry and Reuse Rules:

• A token can only be used once for security reasons.
• If a token is generated but not used within 5 minutes, it expires and must be regenerated.
• Each widget operation requires a new token to function.

Required Dependencies

To integrate PCI Widgets into a web application, you must ensure the following dependencies are met:

1. A Web Environment – A web page (HTML/JavaScript-based) where the widget will be embedded.
2. Qolo JavaScript File – This file initializes the PCI Widgets and must be included in the application.
3. Session Token – A secure token is required to authenticate each widget session.
4. JSON Configuration Object – A properly formatted JSON object defining the widget type and behavior.

Loading the Qolo JavaScript File

To use PCI Widgets, you must load the Qolo JavaScript file into your HTML application.

Steps to Include the JavaScript File:

1. Add the following

<script type="text/javascript" src="https://stg-widgets.qolopay.com/widgets/js/qolo.initialize.v3.js"></script>

• This file must be included before initializing any PCI Widgets.
• Ensure you are using version v3, as previous versions may not support all features.

2. Create a div container in your HTML where the widget will be displayed:

<div id="widget_container" name="widget_container"></div>

• This element serves as the embedding point for the widget.

3. Initialize the widget in JavaScript:

<script type="text/javascript">
widget = {
    onSuccess: (details) => {
        console.log("PCI widget completed successfully", details);
    },
    onFailure: (details) => {
        console.log("PCI widget failure", details);
    },
    frame: {
        container_id: 'widget_container',
        iframe_class: 'widget-iframe',
    },
    target_origin: 'https://stg-widgets.qolopay.com',
    config: {
        token: 'your-secure-token-here',
        require: 'validate_card',
        main: 'cvv_only',
        payment: 'external_payment'
    }
};
pciWidget(widget);
</script>

• Replace 'your-secure-token-here' with an actual Widget token.
• Configure require, main, and payment values based on your use case.

Summary

• PCI Widgets securely manage sensitive payment information using embeddable web components.
• Dependencies include a valid web environment, the Qolo JavaScript file, and a secure token.
• The Qolo JavaScript file must be loaded before widget initialization.
• A One-Time Token is required for each widget session and expires after 5 minutes.