Skip to main content

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, without your application ever handling raw card data directly.

This method renders card details using Base64-encoded card ID, user ID and token values passed in the URL path, along with optional style parameters to match your application's theme.

Security Note: This URL exposes sensitive card data (PAN, expiry, CVV) once loaded. Always render it inside a sandboxed iframe or popup. Never fetch or proxy the response through your own backend, and never log the resolved URL (it also contains your token).


Card Details Preview​

Secure Iframe Test Harness

Generate a live, PCI-compliant card details URL and preview the rendered iframe.

Sandbox Credentials
Styling (optional)
Live Preview

Enter a Card ID and User ID, then generate the URL to preview the embedded card view here.

This form encodes your input client-side only. Nothing is transmitted except the request your browser makes directly to the generated URL.

Obtaining the Token​

The token used in the URL is the access token returned by the Obtain Access Token API. Call that API first, then Base64-encode the token it returns and add it to the URL path.

  • Request the access token from your backend. Never expose your API credentials (such as client ID or secret) in frontend code.
  • Request a fresh token each time you generate a new card details URL.
  • Treat the token as a credential: do not log it, store it in client-side storage, or share it.

URLs​

EnvironmentURL Pattern
Sandboxhttps://spend.sandbox.zoqq.com/cardSensetiveDetails/{{card_id}}/{{x_user_id}}/{{token}}?styles={{styleEncoding}}
Productionhttps://spend.zoqq.com/cardSensetiveDetails/{{card_id}}/{{x_user_id}}/{{token}}?styles={{styleEncoding}}

💡 Use the sandbox URL for testing and the production URL for live integrations.


Quick Start​

const cardId = "your-card-id";
const xUserId = "your-user-id";
const token = "your-token";

const encodedCardId = btoa(cardId);
const encodedXUserId = btoa(xUserId);
const encodedToken = btoa(token);

const styles = {
".card-container": {
"background-color": "#ffffff",
"border-radius": "12px"
},
".card-label": {
"color": "#666666"
},
".card-number": {
"font-size": "16px"
}
};

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

const url = `https://spend.sandbox.zoqq.com/cardSensetiveDetails/${encodedCardId}/${encodedXUserId}/${encodedToken}?styles=${styleEncoding}`;

Embedding as an Iframe​

<iframe
src="https://spend.sandbox.zoqq.com/cardSensetiveDetails/{{card_id}}/{{x_user_id}}/{{token}}?styles={{styleEncoding}}"
width="520"
height="280"
sandbox="allow-scripts allow-same-origin"
style="border: none; border-radius: 12px;"
title="Secure Card Details"
></iframe>

Recommended container size: 520px × 280px. Adjust styling via the styles parameter rather than resizing content post-load, to avoid layout shift or clipped fields.


Parameters​

ParameterRequiredDescription
card_idYesBase64-encoded card ID appended to the URL path. Example: const encodedCardId = btoa(cardId);
x_user_idYesBase64-encoded user ID appended to the URL path. Example: const encodedXUserId = btoa(xUserId);
tokenYesToken, Base64-encoded before being added to the URL path. Example: const encodedToken = btoa(token); Confirm the token source and delivery requirements with the SDK provider.
stylesNoA JSON object of CSS overrides, URL-encoded (not Base64). Example: const styleEncoding = encodeURIComponent(JSON.stringify(theme));

Supported Style Selectors​

SelectorDescription
body, htmlPage background
.card-containerCard container
.card-labelField labels
.card-numberCard number
.card-expiryExpiry
.card-cvvCVV
.card-buttonCopy button
.card-button:hoverButton hover state
.card-tooltipTooltip

Full Example​

const cardId = "your-card-id";
const xUserId = "your-user-id";
const token = "your-token";

const encodedCardId = btoa(cardId);
const encodedXUserId = btoa(xUserId);
const encodedToken = btoa(token);

const styleEncoding = encodeURIComponent(JSON.stringify(theme));

const url = `https://spend.sandbox.zoqq.com/cardSensetiveDetails/${encodedCardId}/${encodedXUserId}/${encodedToken}?styles=${styleEncoding}`;

Session Behavior​

  • The session expires after 60 seconds.
  • Reload the iframe/popup to start a new session — the URL must be regenerated (not cached or reused) on reload.
  • The styles parameter is optional; omitting it renders with default styling.

Error Handling​

The following error states may be returned:

ErrorLikely Cause
Card ID is missingcard_id not appended to the URL
User ID is missingx_user_id not appended to the URL
Invalid card_id formatValue isn't valid Base64, or doesn't decode to a valid card ID
Card not found or deactivatedCard ID is valid but doesn't match an existing/active card
Unable to fetch secure card detailsBackend/network issue while resolving the card
Failed to load secure card detailsRendering failure on the secure details page itself
Session expiredMore than 60 seconds elapsed since the URL was generated

Implementation Notes​

  • card_id — must be Base64 encoded.
  • x_user_id — must be Base64 encoded.
  • token: must be Base64 encoded.
  • styles — must be URL-encoded JSON (not Base64). Do not Base64-encode the styles object; only encodeURIComponent it.
  • Do not persist or cache the generated URL — treat it as a short-lived, single-use link tied to the 60-second session.