Secure Iframe Guide

Display sensitive card details such as card number, expiry, and CVV in a PCI-compliant manner using the Secure Iframe.

This guide provides instructions for integrating with the Secure Iframe functionality to display sensitive card information without PCI DSS compliance.

The Secure Iframe feature allows you to retrieve sensitive card details (card number, expiry date, CVV) in a PCI-compliant manner, regardless of your PCI compliance status. This is ideal for merchants who need to display card information to cardholders but do not have PCI DSS certification.

Here’s what a rendered iframe looks like with custom styles applied:

Want to see it in action before you integrate? Use the Sandbox Preview Tool to experiment with iframe parameters and custom styles in the sandbox environment.

Step 1: Create PAN Token

Use the Create PAN Token API with the card_id parameter.

Request:

curl --location --request POST 'https://api-sandbox.uqpaytech.com/api/v1/issuing/cards/{card_id}/token' \
--header 'x-on-behalf-of;' \
--header 'Accept: application/json' \
--header 'x-auth-token: <your_access_token>' \
--header 'x-idempotency-key: <uuid>'

Response:

{
  "token": "pan_eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9",
  "expires_in": 60,
  "expires_at": "2025-11-13T10:31:00Z"
}

Note:

• Each token can only be used once
• Token expires after 60 seconds

Step 2: Prepare Styles (Optional)

You can customize the iframe appearance by providing CSS styles as a JSON object. The styles need be URL-encoded and passed as a query parameter.

const styles = {
    ".uq-card-number": {
        "color": "#2196F3",
        "font-size": "20px",
        "font-weight": "600",
        "font-family": "Arial, sans-serif"
    },
    ".uq-card-expiry": {
        "color": "#4CAF50",
        "font-size": "18px",
        "font-weight": "500"
    },
    ".uq-card-cvv": {
        "color": "#FF9800",
        "font-size": "18px",
        "font-weight": "500"
    },
    ".uq-card-container": {
        "background-color": "#f5f5f5",
        "border-radius": "12px",
        "padding": "20px",
        "border": "1px solid #e0e0e0"
    },
    ".uq-card-label": {
        "color": "#666666",
        "font-size": "14px"
    },
    ".uq-card-button": {
        "background-color": "#2196F3",
        "color": "#ffffff",
        "border": "none",
        "border-radius": "8px"
    },
    ".uq-card-button:hover": {
        "background-color": "#1976D2"
    },
    ".uq-card-tooltip": {
        "background-color": "#d4edda",
        "color": "#155724",
        "font-size": "12px",
        "border-radius": "4px"
    }
};

const encodedStyles = encodeURIComponent(JSON.stringify(styles));

Available CSS Selectors

Selector	Description	Supported Properties
.uq-card-number	Card number	color, font-size, font-family, font-weight
.uq-card-expiry	Expiry date	color, font-size, font-family, font-weight
.uq-card-cvv	CVV	color, font-size, font-family, font-weight
.uq-card-cardholder	Cardholder name (only rendered when cardholder_name=true)	color, font-size, font-family, font-weight
.uq-card-container	Container	background-color, padding, border, border-radius, width, height, min-height, max-width, min-width
.uq-card-row	Row layout (one row per field — label on the left, value on the right)	display, justify-content, align-items, flex-direction, gap
.uq-card-label	Label text	color, font-size
.uq-card-button	Copy button	color, background-color, border, border-radius, padding
.uq-card-button:hover	Button hover state	color, background-color
.uq-card-button:active	Button active state	color, background-color
.uq-card-tooltip	Copy tooltip	color, background-color, font-size, border-radius
.uq-page-background	Iframe page background (default transparent)	background-color

Supported CSS Properties

Global supported properties: color, background-color, font-size, font-family, font-weight, padding, margin, border, border-radius, text-align, line-height, letter-spacing

Step 3: Construct Iframe URL

Build the iframe source URL using the following pattern:

{iframe_domain}/iframe/card?token={pan_token}&cardId={card_id}&lang={lang}&styles={encoded_styles}

Parameters

Parameter	Type	Required	Description	Example
iframe_domain	string	Yes	Iframe service domain	https://embedded-sandbox.uqpaytech.com
pan_token	string	Yes	PAN token from Step 1	pan_eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
card_id	string	Yes	Card identifier (must match token creation)	7242a504-e43d-4b95-b4c8-f9fc5992d02b
lang	string	No	Display language (default: en)	en, zh, zh-TW
styles	string	No	URL-encoded CSS styles JSON	URL-encoded JSON object
show_data	boolean	No	Reveal card number, expiry, and CVV on load without a user action. Recommended for trusted environments only (default: false)	true
cardholder_name	boolean	No	Render the cardholder name field. The displayed value is the card’s name_on_card; if not set, the iframe falls back to first_name + last_name from the cardholder. Style via .uq-card-cardholder (default: false)	true

Environment Domains

• Sandbox: https://embedded-sandbox.uqpaytech.com
• Production: https://embedded.uqpay.com

Example

const iframeDomain = 'https://embedded-sandbox.uqpaytech.com';
const panToken = 'pan_eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9';
const cardId = '7242a504-e43d-4b95-b4c8-f9fc5992d02b';
const lang = 'en';
const styles = {
  ".uq-card-container": {
    "background-color": "#ffffff",
    "border": "1px solid #e0e0e0",
    "border-radius": "8px"
  }
};

const encodedStyles = encodeURIComponent(JSON.stringify(styles));
const iframeUrl = `${iframeDomain}/iframe/card?token=${panToken}&cardId=${cardId}&lang=${lang}&styles=${encodedStyles}`;

Toggle Sensitive Data Visibility

When show_data is not set (or set to false), card number, expiry, and CVV are masked on load. End users can reveal or re-mask the data in two ways:

• Click the eye icon next to the CVV label. The eye icon is persistently visible and toggles all three sensitive fields at once.
• Click any masked value directly (****, **/**, ***) to toggle visibility.

When show_data=true, the data is shown on load; the eye icon and click-to-toggle behavior remain available for re-masking.

Step 4: Embed Iframe on Your Page

Add the iframe element to your HTML page:

<iframe 
  src="${iframeUrl}"
  width="400"
  height="400"
  frameborder="0"
></iframe>

Sizing notes:

• The iframe’s internal page has a maximum width of 1280px. If your parent container is wider than 1280px, the rendered card will be capped at 1280px.
• The iframe’s internal container has a minimum height of 400px. Set the iframe height to at least 400 to avoid clipping or scrollbars.
• To pin the card to fixed dimensions, set width / height on .uq-card-container via the styles parameter (see Step 2).