Troubleshooting and FAQs

Overview

When integrating PCI Widgets, developers may encounter issues related to configuration, API requests, token expiration, or incorrect widget initialization. This section provides solutions to common problems, debugging techniques for API and token errors, details on supported widget versions and URLs, and best practices for maintaining PCI compliance.

Common Integration Issues and Solutions

Below are some frequently encountered issues and how to resolve them:

Issue 1: Blank Widget Display

Possible Causes:

1. Incorrect or missing JavaScript file inclusion.
2. Invalid widget configuration.

Solution:

Ensure you are using the correct v3 widget file:

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

• Verify the JSON configuration object is correctly structured.
• Ensure that the widget container (<div id="widget_container">) exists in the HTML file.

Issue 2: Token Not Working

Possible Causes:

1. The token has expired (tokens expire after 5 minutes).
2. The token has already been used once.

Solution:

• Generate a new token before each widget session.
• Ensure that the correct API parameter (card_proxy, program_guid, person_guid) is passed when generating the token.

Example API call for generating a new token:
GET /api/v1/auth/token?card_proxy=1234567890

Issue 3: Incorrect or Missing Widget URL

Possible Causes:

1. Using an outdated or incorrect widget version.
2. Using the wrong environment (staging vs. production).

Solution:

• Use the correct widget JavaScript file:

Staging environment:
https://stg-widgets.qolopay.com/widgets/js/qolo.initialize.v3.js

Production environment:
https://widgets.qolopay.com/widgets/js/qolo.initialize.v3.js

• Ensure that the target_origin in the JSON configuration matches the correct environment.

Issue 4: Callback Functions Not Triggering

Possible Causes:

1. Callbacks (onSuccess, onFailure, onLoadIframe) are not properly defined.
2. The widget is not correctly initialized.

Solution:

Verify that callback functions are included inside the widget configuration:

widget = {
    onSuccess: (details) => {
        console.log("Widget completed successfully", details);
    },
    onFailure: (details) => {
        console.log("Widget failed", details);
    },
    onLoadIframe: (details) => {
        console.log("Widget iframe loaded successfully", details);
    },
    config: {
        token: "your-secure-token",
        main: "set_pin"
    }
};

• Ensure that pciWidget(widget); is called after the JSON object is defined.

Debugging Token and API Errors

1. Checking Token Status

If a token is not working, confirm its validity by checking the API response:

{
    "error": "Token expired or already used"
}

• If expired: Generate a new token.
• If already used: A new session requires a fresh token.

2. Handling Token Generation Errors

API Endpoint:

/api/v1/auth/token

Required parameters:

Example API Call:

GET /api/v1/auth/token?card_proxy=1234567890

3. Debugging API Errors

If an API call fails, check the response error message:

{
    "error": "Invalid card_proxy provided"
}

Solution:

• Ensure the correct parameter value is passed (card_proxy, program_guid, person_guid).
• Verify that the user is authenticated when making API requests.

Supported Widget Versions and URLs

Widget JavaScript Files

Which Widget Version Should You Use?

• Always use v3 (qolo.initialize.v3.js) since previous versions may not support newer features.
• If using an older version, update the script to v3.

Best Practices for PCI Compliance

To maintain security and PCI DSS (Payment Card Industry Data Security Standard) compliance, follow these best practices:

1. Ensure Tokens Are Used Securely

• Never store or reuse tokens; they are one-time use and expire after 5 minutes.
• Generate a fresh token before each widget session.

2. Secure API Calls

• Ensure that API requests to /api/v1/auth/token use authenticated sessions (JWT required).
• Do not expose API keys or credentials in client-side code.

3. Mask Sensitive Data

• Use timeout settings to automatically mask card details (min: 20s, max: 90s).

Example:

config: {
    timeout: 60
}

• This ensures that sensitive details like PIN and CVV are hidden after 60 seconds.

4. Use the Correct Environment

• Use staging URLs for development and testing.
• Use production URLs only for live transactions.

5. Enable Secure Embedding

• Ensure that the widget is embedded in a secure HTTPS environment.

Example <iframe> embedding:

frame: {
    container_id: "widget_container",
    iframe_class: "widget-iframe",
    target_origin: "https://stg-widgets.qolopay.com"
}

Summary

By following these troubleshooting steps and best practices, you can ensure a smooth and secure integration of PCI Widgets.