Secure Iframe 集成指南

本指南介绍如何集成 Secure Iframe 功能，在无需自身 PCI DSS 合规的前提下展示敏感卡信息。 Secure Iframe 功能让你能以符合 PCI 合规的方式获取敏感卡信息（卡号、过期日期、CVV），无论你自身是否具备 PCI 合规资质。对于需要向持卡人展示卡信息、但没有 PCI DSS 认证的商户来说，这是理想方案。应用自定义样式后，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-cvv`	CVV	color、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-background`	iframe 页面背景（默认 `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_domain`	string	是	Iframe 服务域名	`https://embedded-sandbox.uqpaytech.com`
`pan_token`	string	是	步骤 1 获取的 PAN token	`pan_eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9`
`card_id`	string	是	卡标识符（必须与创建 token 时一致）	`7242a504-e43d-4b95-b4c8-f9fc5992d02b`
`lang`	string	否	显示语言（默认：`en`）	`en`、`zh`、`zh-TW`
`styles`	string	否	URL 编码后的 CSS 样式 JSON	URL 编码后的 JSON 对象
`show_data`	boolean	否	加载时直接显示卡号、过期日期、CVV，无需用户操作。建议仅在受信环境中使用（默认：`false`）	`true`
`cardholder_name`	boolean	否	渲染持卡人姓名字段。展示值为卡的 `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）。

入门

持卡人

卡片

充值

管理与安全

集成

参考

步骤 1：创建 PAN Token

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

可用的 CSS 选择器

支持的 CSS 属性

步骤 3：构造 Iframe URL

参数

环境域名

示例

切换敏感数据显示

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

​步骤 1：创建 PAN Token

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

​可用的 CSS 选择器

​支持的 CSS 属性

​步骤 3：构造 Iframe URL

​参数

​环境域名

​示例

​切换敏感数据显示

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

步骤 1：创建 PAN Token

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

可用的 CSS 选择器

支持的 CSS 属性

步骤 3：构造 Iframe URL

参数

环境域名

示例

切换敏感数据显示

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