Secure Iframe Guide

Display a card's sensitive details (card number, expiry, CVV) in a PCI-compliant manner using a secure popup window or iframe.

Note: The integration method differs depending on the program your card is issued under. Please refer to your program configuration to determine which method is applicable to your implementation, or reach out to your Program Manager or Zoqq Support for confirmation.

---

Program A - Cards under Banking

Use this method to generate a short-lived, tokenized link that opens Zoqq's secure frame so you never need to handle or store sensitive card data directly.

Overview

To display card details or PIN, you need to:

1. Build a small payload with the required identifiers
2. Encode it into a token
3. Construct a secure URL using that token
4. Open the URL in a popup window or embed it as an iframe

💡 The generated link is time-bound and automatically expires after 60 seconds for security.

Step 1: Create the Payload

Collect the following details to build the payload:

Field	Description
accountId	The customer's Account ID
cardId	The Card Hash ID (card_hash_id)
env	Environment — "demo" for testing, "prod" for live/production
op	Operation type — "details" to view card number/CVV, or "pin" to view PIN
exp	Expiry timestamp — set to 60 seconds from the current time; the link auto-expires after this

Example:

const payload = {
  accountId: "{{accountId}}",
  cardId: "{{card_hash_id}}",
  env: "demo", // or "prod"
  op: "details", // or "pin"
  exp: Math.floor(Date.now() / 1000) + 60, // expires in 60 seconds
};

Step 2: Generate the Token

Encode the payload into a Base64 string to generate the token.

const token = btoa(JSON.stringify(payload));

// Example generated token:
// eyJraWQiOiJjNDRjODVkMD...

Step 3: Choose the Correct Domain

Select the base URL based on your environment:

Environment	Domain
demo	https://demo.zoqq.com
prod	https://business.zoqq.com

Step 4: Construct the Secure URL

Combine the domain and token into the final URL:

https://demo.zoqq.com/card-sensitive-details?token={{token}}

or, for production:

https://business.zoqq.com/card-sensitive-details?token={{token}}

Step 5: Render in a Popup or Iframe

Open the URL from Step 4 in a popup window or embed it via an iframe.

Recommended dimensions:

Setting	Value
Width	420px
Height	620px
Minimum size	300px × 200px (usable, but tighter fit)

Example (iframe):

<iframe
  src="https://demo.zoqq.com/card-sensitive-details?token={{token}}"
  width="420"
  height="620"
  frameborder="0"
></iframe>

Behavior: Once loaded, the secure window will display a loading spinner while initializing, render the requested card details or PIN inside Zoqq's secure frame, and automatically stop working after 60 seconds once the token expires.

---

Program B - Cards

Use this method to render card details directly using a Base64-encoded card ID and optional style parameters.

URLs

Environment	URL Pattern
Sandbox	https://spend.sandbox.zoqq.com/cardSensetiveDetails/{{card_id}}?styles={{styleEncoding}}
Production	https://spend.zoqq.com/cardSensetiveDetails/{{card_id}}?styles={{styleEncoding}}

Quick Start

const cardId = btoa("your-card-id");
const styles = {
  ".uq-card-container": {
    "background-color": "#ffffff",
    "border-radius": "12px"
  }
};
const styleEncoding = encodeURIComponent(JSON.stringify(styles));
const url = `https://spend.sandbox.zoqq.com/cardSensetiveDetails/${cardId}?styles=${styleEncoding}`;

Parameters

Parameter	Required	Description
card_id	Yes	Base64-encode the card ID before appending to the URL. Example: const encodedCardId = btoa(cardId);
styles	No	A JSON object of style overrides, URL-encoded. Example: const styleEncoding = encodeURIComponent(JSON.stringify(theme));

Supported Style Selectors

Selector	Description
body, html	Page background
.uq-card-container	Card container
.uq-card-label	Field labels
.uq-card-number	Card number
.uq-card-expiry	Expiry
.uq-card-cvv	CVV
.uq-card-button	Copy button
.uq-card-button:hover	Button hover state
.uq-card-tooltip	Tooltip

Example

const encodedCardId = btoa(cardId);
const styleEncoding = encodeURIComponent(JSON.stringify(theme));
const url = `https://spend.sandbox.zoqq.com/cardSensetiveDetails/${encodedCardId}?styles=${styleEncoding}`;

Session Behavior

• Session expires after 60 seconds.
• Reload to start a new session.
• The styles parameter is optional.

Error Handling

The following error states may be returned:

• Card ID is missing
• Invalid card_id format
• Card not found or deactivated
• Unable to fetch secure card details
• Failed to load secure card details
• Session expired

Implementation Note

Current implementation expects:

• card_id: Base64 encoded
• styles: URL-encoded JSON (not Base64)

---

Summary

Section	Program A	Program B
Method	Token-based popup link	Direct card ID in URL path
card_id encoding	Included inside Base64 token payload	Base64 encoded directly
Styling	Passed via styles param (URL-encoded JSON)	Passed via styles param (URL-encoded JSON)
Session expiry	60 seconds	60 seconds
Recommended size	420px × 620px	Not specified — follow container/style guidance

Note: Confirm which program your integration falls under before choosing a method — the two are not interchangeable.