跳转到主要内容
本指南介绍如何集成 Secure Iframe 功能，在无需自身 PCI DSS 合规的前提下展示敏感卡信息。 Secure Iframe 功能让你能以符合 PCI 合规的方式获取敏感卡信息（卡号、过期日期、CVV），无论你自身是否具备 PCI 合规资质。对于需要向持卡人展示卡信息、但没有 PCI DSS 认证的商户来说，这是理想方案。 应用自定义样式后，iframe 渲染效果如下： Secure Iframe 渲染预览
想在集成前先看看效果？可以使用 沙盒预览工具，在沙盒环境里调试 iframe 参数和自定义样式。

​
步骤 1：创建 PAN Token

使用 Create PAN Token API，传入 card_id 参数。 请求： 
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>'
响应： 
{
  "token": "pan_eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9",
  "expires_in": 60,
  "expires_at": "2025-11-13T10:31:00Z"
}
说明：
  • 每个 token 只能使用一次
  • Token 60 秒后过期

​
步骤 2：准备样式（选填）

可通过传入 CSS 样式的 JSON 对象自定义 iframe 外观。样式需经过 URL 编码后作为查询参数传递。 
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));

​
可用的 CSS 选择器

选择器说明支持的属性
.uq-card-number卡号color、font-size、font-family、font-weight
.uq-card-expiry过期日期color、font-size、font-family、font-weight
.uq-card-cvvCVVcolor、font-size、font-family、font-weight
.uq-card-cardholder持卡人姓名（仅在 cardholder_name=true 时渲染）color、font-size、font-family、font-weight
.uq-card-container容器background-color、padding、border、border-radius、width、height、min-height、max-width、min-width
.uq-card-row行布局（每行一个字段——左侧标签，右侧值）display、justify-content、align-items、flex-direction、gap
.uq-card-label标签文字color、font-size
.uq-card-button复制按钮color、background-color、border、border-radius、padding
.uq-card-button:hover按钮 hover 状态color、background-color
.uq-card-button:active按钮 active 状态color、background-color
.uq-card-tooltip复制提示color、background-color、font-size、border-radius
.uq-page-backgroundiframe 页面背景（默认 transparent）background-color

​
支持的 CSS 属性

全局支持的属性：color、background-color、font-size、font-family、font-weight、padding、margin、border、border-radius、text-align、line-height、letter-spacing

​
步骤 3：构造 Iframe URL

按以下模式构建 iframe 源 URL： 
{iframe_domain}/iframe/card?token={pan_token}&cardId={card_id}&lang={lang}&styles={encoded_styles}

​
参数

参数类型是否必填说明示例
iframe_domainstring是Iframe 服务域名https://embedded-sandbox.uqpaytech.com
pan_tokenstring是步骤 1 获取的 PAN tokenpan_eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
card_idstring是卡标识符（必须与创建 token 时一致）7242a504-e43d-4b95-b4c8-f9fc5992d02b
langstring否显示语言（默认：en）en、zh、zh-TW
stylesstring否URL 编码后的 CSS 样式 JSONURL 编码后的 JSON 对象
show_databoolean否加载时直接显示卡号、过期日期、CVV，无需用户操作。建议仅在受信环境中使用（默认：false）true
cardholder_nameboolean否渲染持卡人姓名字段。展示值为卡的 name_on_card；若未设置，则回退到持卡人的 first_name + last_name。可通过 .uq-card-cardholder 自定义样式（默认：false）true

​
环境域名

  • 沙盒： https://embedded-sandbox.uqpaytech.com
  • 生产： https://embedded.uqpay.com

​
示例

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}`;

​
切换敏感数据显示

未设置 show_data（或设为 false）时，卡号、过期日期、CVV 在加载时默认以掩码形式显示。终端用户可通过以下两种方式切换显示与隐藏：
  • 点击 CVV 标签旁的眼睛图标。眼睛图标始终常驻显示，可一次性切换全部三个敏感字段。
  • 直接点击任意掩码值（****、**/**、***）即可切换显示状态。
设置 show_data=true 时，数据在加载时直接展示；眼睛图标与点击掩码切换的行为仍然可用，可用于重新隐藏数据。

​
步骤 4：在你的页面嵌入 Iframe

将 iframe 元素添加到 HTML 页面： 
<iframe 
  src="${iframeUrl}"
  width="400"
  height="400"
  frameborder="0"
></iframe>
尺寸提示：
  • iframe 内部页面最大宽度为 1280px。父容器宽度超过 1280px 时，卡片渲染宽度将被限制在 1280px。
  • iframe 内部容器最小高度为 400px。建议将 iframe height 至少设置为 400，避免内容被截断或出现滚动条。
  • 如需将卡片固定为指定尺寸，可通过 styles 参数为 .uq-card-container 设置 width / height（参见步骤 2）。