通过安全 iframe 向持卡人展示卡号、有效期和 CVV。卡片敏感数据只在 EYJ 托管的 iframe 内获取、解密和渲染,你的页面、App 和服务器都不会接触明文卡片数据。
| 特性 | 说明 |
|---|---|
| 数据隔离 | 卡号、有效期、CVV 只在 iframe 内渲染;页面、JavaScript、服务器均不会通过 URL、postMessage 或 SDK 收到明文。 |
| 一次性展示票 | PAN Token 签发后 60 秒过期、只能使用一次,并且只能用于签发时指定的卡片。 |
| 密钥绑定 | Token 绑定 iframe 内生成的密钥对(jkt),兑换时需要持钥证明。即使 token 泄露,其他页面也无法使用。 |
| 默认遮罩 | 卡片默认遮罩显示;展示 30 秒后、窗口失焦或标签页隐藏时自动恢复遮罩。 |
| 端到端加密 | 卡片数据通过 TLS 直接传到 iframe,并使用仅存在于该 iframe 实例内的密钥加密。 |
本功能需由 EYJ 为你的代理商账户开通。未开通时签票接口会返回错误,请联系你的客户经理。
持卡人点击「查看卡片详情」
│
▼
① 你的前端 → 你的后端:请求真实卡片 ID
│ 你的后端 → EYJ:POST /agent/v1/card/pan-card-id
▼
② 你的前端:初始化 SDK,createElement('issuingCardSecure', { cardId: pan_card_id, getToken })
│
▼
③ iframe 加载并生成密钥对,SDK 调用 getToken(jkt)
│
▼
④ 你的前端 → 你的后端:携带 jkt 请求签票
│ 你的后端 → EYJ:POST /agent/v1/card/pan-token
▼
⑤ getToken 返回 token,SDK 通过 postMessage 交给 iframe
│
▼
⑥ iframe 兑换 token,解密并以遮罩形式展示卡片X-Access-Key、X-Timestamp、X-Nonce、X-Signature,签名规则见《EYJ 开放 API 通用说明》。https://agent.eyj.world/agent/v1POST,Content-Type: application/jsonPOST /agent/v1/card/pan-card-idcardId 需要使用安全展示专用的卡片 ID(pan_card_id),它与开放 API 其他接口中的 card_id 不同,请通过此接口换取。| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
card_id | string | 是 | 开放 API 中的卡片 ID(开卡、卡列表接口返回的 card_id)。 |
{ "card_id": "4eac0b82-247e-4fb0-abd5-ec05a096a96f" }{
"code": 200,
"msg": "success",
"time": 1762140000,
"data": {
"card_id": "4eac0b82-247e-4fb0-abd5-ec05a096a96f",
"pan_card_id": "7242a504-e43d-4b95-b4c8-f9fc5992d02b"
}
}| 字段 | 说明 |
|---|---|
card_id | 原样返回的开放 API 卡片 ID。 |
pan_card_id | 传给 SDK createElement 的 cardId。 |
pan_card_id对同一张卡是固定的,你可以在服务端缓存,避免每次都调用此接口。
POST /agent/v1/card/pan-tokengetToken(jkt) 回调中由你的后端调用。| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
card_id | string | 是 | 开放 API 中的卡片 ID(注意:不是 pan_card_id)。 |
jkt | string | 是 | SDK 传给 getToken 的值,由 43 个 base64url 字符组成(A-Z a-z 0-9 _ -)。原样透传,不要修改。 |
{
"card_id": "4eac0b82-247e-4fb0-abd5-ec05a096a96f",
"jkt": "Xo1h7m0Jb3QZqk2y8gS9sL4vN6tR5wE1aD3fG7hJ0kM"
}{
"code": 200,
"msg": "success",
"time": 1762140000,
"data": {
"token": "pan_xxxxxxxxxxxxxxxx",
"expires_in": 60,
"expires_at": "2026-11-03T11:30:00+08:00"
}
}| 字段 | 说明 |
|---|---|
token | PAN 展示票,原样返回给前端 getToken。请视为不透明字符串,不要解析、校验或记录到日志。 |
expires_in | 有效期(秒),固定为 60。 |
expires_at | 到期时间(含时区)。 |
{
"code": "AGENT_BIZ_30002",
"msg": "卡号不存在",
"detail": "Card not found",
"request_id": "req_6727...",
"timestamp": 1762140000,
"ip": "1.2.3.4"
}code | msg | 说明 |
|---|---|---|
AGENT_BIZ_30002 | 卡号不存在 | card_id 不存在或不属于当前代理商。 |
AGENT_BIZ_30013 | 卡状态异常 | 卡片未激活或不可用。 |
AGENT_BIZ_30017 | System | 上游服务异常,或账户未开通安全展示功能。 |
AGENT_SYS_50003 | CardId Empty / Jkt Empty / Jkt Format error | 参数缺失或 jkt 格式不正确。 |
AGENT_AUTH_* | — | 鉴权失败,见《EYJ 开放 API 通用说明》。 |
getToken、通过 postMessage 传票、校验消息来源、根据卡片尺寸调整高度。<template>
<div class="card-stage">
<div ref="cardRef" class="secure-card"></div>
</div>
</template>
<script setup>
import { ref, onMounted, onBeforeUnmount } from 'vue'
import { init, createElement } from '@uqpay/embedded-sdk'
const props = defineProps({ cardId: String, panCardId: String })
const cardRef = ref(null)
let card = null
onMounted(async () => {
await init({ env: 'production' })
card = await createElement('issuingCardSecure', {
cardId: props.panCardId,
lang: 'zh-CN',
getToken: async (jkt) => {
const res = await fetch('/your-api/card/pan-token', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ cardId: props.cardId, jkt }),
})
if (!res.ok) throw new Error('Token request failed')
return (await res.json()).token
},
})
card.on('error', (e) => console.warn(e.code))
card.mount(cardRef.value)
})
onBeforeUnmount(() => card?.destroy())
</script>import { useEffect, useRef } from 'react';
import { init, createElement } from '@uqpay/embedded-sdk';
export function SecureCard({ cardId, panCardId }) {
const ref = useRef(null);
useEffect(() => {
let card;
let cancelled = false;
(async () => {
await init({ env: 'production' });
const el = await createElement('issuingCardSecure', {
cardId: panCardId,
lang: 'zh-CN',
getToken: async (jkt) => {
const res = await fetch('/your-api/card/pan-token', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ cardId, jkt }),
});
if (!res.ok) throw new Error('Token request failed');
return (await res.json()).token;
},
});
if (cancelled) return el.destroy();
card = el;
card.mount(ref.current);
})();
return () => { cancelled = true; card?.destroy(); };
}, [cardId, panCardId]);
return <div ref={ref} />;
}mount(Vue 用 onMounted / nextTick,弹窗类组件要等弹窗打开后)。card.destroy(),清理 iframe 和事件监听。destroy() 新创建的实例,不要再挂载。| 选项 | 类型 | 说明 |
|---|---|---|
cardId | string | 必填。pan-card-id 接口返回的 pan_card_id。 |
getToken | (jkt) => Promise<string> | 必填。接收 jkt,返回后端签发的 token。 |
lang | string | 显示语言:en(默认)、zh / zh-CN(简体)、zh-TW(繁体)。 |
styles | object | 自定义样式对象,见自定义外观。SDK 自动编码,无需 encodeURIComponent。 |
appearance | object | 外观配置,支持 mode 和 variables。 |
showData | boolean | 加载后直接展示敏感数据,仅用于完全可信的页面。默认 false。 |
cardholderName | boolean | 在卡面上显示持卡人姓名。默认 false。 |
layout | 'card' | 'list' | card(SDK 默认)为银行卡卡面;list 为每个字段一行的列表样式。 |
height | number | string | iframe 初始高度,例如 400 或 '100%'。 |
autoResize | boolean | 跟随卡片内容自动调整 iframe 高度。 |
title | string | iframe 的 title(无障碍)。 |
iframeClassName | string | 给 iframe 添加 class,便于外层样式控制。 |
| 方法 | 说明 |
|---|---|
mount(target) | 把 iframe 挂到容器(元素 ID 或 DOM 元素)。 |
unmount() | 移除 iframe,实例仍可再次 mount(会创建新的 iframe 并重新签票)。 |
destroy() | 移除 iframe 并清除所有监听,实例不可再用。 |
on(event, handler) / once(event, handler) | 订阅事件,返回取消订阅函数。 |
{EMBEDDED_HOST} 为安全展示服务域名,请向 EYJ 获取。自定义样式在原生方式下通过 URL 参数 styles=传入(URL 编码后的 JSON),见URL 参数。
styles 传入"选择器 → 属性"对象(SDK 直接传对象;原生 iframe 传 URL 编码后的 JSON)。只接受下表中的选择器和属性,每个值都会校验,其余内容会被静默丢弃。 选择器名称(.uq-*)为固定标识,请原样使用。| 选择器 | 元素 | 可用属性 |
|---|---|---|
.uq-card-number | 卡号 | color, font-size, font-family, font-weight, text-align |
.uq-card-expiry | 有效期 | color, font-size, font-family, font-weight |
.uq-card-cvv | CVV | color, font-size, font-family, font-weight |
.uq-card-cardholder | 持卡人姓名(仅 cardholderName: true 时显示) | color, font-size, font-family, font-weight |
.uq-card-container | 卡片容器 | background-color, background-image(仅 none 或由颜色停靠点组成的一个 linear-gradient(...),禁止 url()), padding, border, border-radius, width, height, min-height, max-width, min-width |
.uq-card-label | 行内 有效期 / CVV 标签 | color, font-size, white-space |
.uq-card-row | 字段行(姓名、卡号、有效期、CVV) | padding, padding-top, padding-bottom, margin, margin-top, margin-bottom, display, justify-content, align-items, flex-direction, gap |
.uq-card-button | 眼睛切换按钮与复制按钮 | color, background-color, border, border-radius, padding |
.uq-card-button:hover | 按钮悬停 | color, background-color |
.uq-card-button:active | 按钮按下 | color, background-color |
.uq-card-tooltip | "已复制"提示 | color, background-color, font-size, border-radius |
.uq-copy-tip | .uq-card-tooltip 的兼容别名 | 同上 |
.uq-page-background | iframe 页面背景(默认透明) | background-color |
.uq-card-brand | 右下角卡组织标志(Visa / Mastercard) | color, display |
.uq-card-art | 字段后方的默认图案层(水印与非接触标志) | color, opacity, display |
| 属性类别 | 支持的值 |
|---|---|
颜色(color, background-color) | #rgb, #rgba, #rrggbb, #rrggbbaa;数字分量的 rgb() / rgba() / hsl() / hsla();颜色名称;transparent, currentColor, inherit |
长度(font-size, padding*, margin*, gap, width, height, min-*, max-*, letter-spacing) | 带 px, em, rem, %, vh, vw, vmin, vmax, pt, ch, ex 单位的数字,或 0;padding / margin 最多四个值,gap 最多两个;margin 可为负数或 auto;宽度类还支持 auto, none, max-content, min-content, fit-content;font-size 还支持 xx-small ~ xxx-large、smaller、larger |
font-family | 字母、数字、空格、逗号、引号及连字符,例如 "Courier New", monospace |
font-weight | 100–900, normal, bold, bolder, lighter |
border | 最多三个部分:宽度(长度或 thin / medium / thick)、样式(none, solid, dashed, dotted, double, groove, ridge, inset, outset, hidden)、颜色 |
border-radius | 最多四个长度;可再加 / 和最多四个长度定义椭圆圆角 |
| 关键字 | display: block, inline, inline-block, flex, inline-flex, grid, inline-grid, none, contents · justify-content: flex-start, flex-end, center, space-between, space-around, space-evenly, start, end, left, right, normal, stretch · align-items: flex-start, flex-end, center, baseline, stretch, start, end, normal, self-start, self-end · flex-direction: row, row-reverse, column, column-reverse · text-align: left, right, center, justify, start, end · white-space: normal, nowrap, pre, pre-wrap, pre-line, break-spaces · 所有关键字属性还支持 inherit, initial, unset |
url(、expression(、calc()、var()、!important@、;、{、}、<、>、反斜杠、注释、控制字符styles JSON常见踩坑: line-height、letter-spacing(除长度类外)、box-shadow、opacity(.uq-card-art以外)都不在白名单内,写了也不会生效。
#e5e7eb 边框和柔和阴影;标签颜色 #374151,字段值为 #111827 等宽字体,页面背景透明。| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
cardId | string | 是 | pan_card_id,必须与签票时的卡片一致。 |
parent_origin | string | 强烈建议 | 你的页面来源,例如 https://app.example.com。iframe 只接收该来源发来的 uq:token,也只向该来源发送事件。 |
layout | string | 否 | card:银行卡卡面;list:字段列表(不传时为 list)。 |
lang | string | 否 | en(默认)、zh / zh-CN、zh-TW;其他值回退为 en。 |
styles | string | 否 | URL 编码的样式 JSON。 |
show_data | boolean | 否 | true 表示加载后直接展示数据,仅识别字面值 true。自动遮罩仍然生效。 |
cardholder_name | boolean | 否 | true 显示持卡人姓名行。 |
sandbox 时必须同时包含 allow-scripts 和 allow-same-origin,不需要其他权限。allow="clipboard-write" 让复制按钮使用现代剪贴板 API;不设置时回退到旧式复制。uq:resize 调整(SDK 用 autoResize: true 自动处理)。| 事件 | 数据 | 触发时机 |
|---|---|---|
ready | — | iframe 已就绪。 |
jkt | { jkt } | iframe 已生成密钥对(SDK 会自动调用 getToken,一般无需处理)。 |
rendered | — | 卡片数据已解密并渲染(默认遮罩状态)。适合在此关闭 loading。 |
masked | { reason } | 数据恢复遮罩,reason:user / timeout / blur / hidden / unload。 |
resize | { width, height } | 卡片尺寸变化。 |
error | { code, message } | 终止性错误,见错误处理。 |
message | 原始消息 | 所有原始 uq:* 消息,仅用于调试。 |
type | 数据 | 触发时机 |
|---|---|---|
uq:ready | — | 参数已解析,页面就绪。 |
uq:jkt | jkt: string(43 字符) | 已生成密钥对,等待你回传 uq:token。 |
uq:rendered | — | 卡片已渲染。 |
uq:masked | reason | 数据恢复遮罩。 |
uq:error | code: string | 终止性错误。 |
uq:resize | width, height(CSS px) | 尺寸变化,用于调整 iframe 高度。 |
iframe-loaded / card-rendered | — | 旧事件,card-rendered 不代表数据已显示,请以 uq:rendered 为准。 |
type | 数据 | 规则 |
|---|---|---|
uq:token | token: string | 只接受第一条有效消息;targetOrigin 必须是 iframe 所在域名,禁止 '*'。 |
uq:ready → uq:resize → uq:jkt → 你发送 uq:token → uq:rendered → … uq:masked …1234 5678 •••• 3456),有效期 ••/••,CVV •••,姓名 ••••。MM/YY)。lang 控制标签、按钮、提示与错误文案的语言;遮罩格式固定不可修改。error 事件。错误会终止当前实例,重试时需 destroy() 后重新创建(会重新签票)。code | 原因 | 处理方式 |
|---|---|---|
TOKEN_FETCH_FAILED / NO_TOKEN | getToken 抛错或返回空值(例如你的后端签票失败)。 | 在页面提示用户,检查后端日志中开放 API 返回的错误码。 |
INVALID_TOKEN | Token 已过期、已使用、属于其他卡片,或密钥证明不匹配。 | 关闭后重新打开卡片详情。 |
INVALID_JKT / JKT_REQUIRED | jkt 被修改或未传。 | jkt 必须原样透传。 |
SECURE_IFRAME_DISABLED | 账户未开通安全展示。 | 联系 EYJ 客户经理。 |
RATE_LIMITED | 签票或兑换次数过多。 | 稍后重试,不要循环挂载。 |
BOT_CHECK_FAILED | 浏览器未通过自动化流量检测。 | 让用户重新加载;检查 https://challenges.cloudflare.com 是否可访问(企业代理、广告拦截、受限 WebView)。 |
UNSUPPORTED_BROWSER | 缺少 WebCrypto 等能力,最常见原因是父页面使用了 http://。 | 使用 HTTPS(开发时可用 localhost)。 |
MISSING_PARAMS | cardId 缺失或格式错误。 | 检查是否传入了 pan_card_id。 |
NETWORK_ERROR | 兑换请求未发出(离线、代理、扩展拦截)。 | 检查网络后重新打开。 |
DECRYPT_FAILED | 响应在传输中被篡改或损坏。 | 重新打开;持续出现请联系 EYJ。 |
UNKNOWN 等其他 | 其他服务端错误。 | 重新打开;持续出现请携带错误码和时间联系 EYJ。 |
localhost)。https://challenges.cloudflare.com(自动化流量检测)。file:// 本地页面,否则无法使用 WebCrypto。challenges.cloudflare.com。frame-src、script-src、connect-src。SDK 即使通过 npm 安装,也需要从该域名加载元素代码。event.origin 用 === 精确比较,禁止 indexOf / endsWith / 正则;同时校验 event.source === iframe.contentWindow。showData: true 只用于完全由你控制的页面,页面中不能有未经审查的第三方脚本。url(),无法在 iframe 内放图片。如果想使用自己的卡面背景图和品牌 Logo,推荐以下做法(EYJ App 已采用):styles 隐藏默认图案层,并把 iframe 内的卡片容器和页面背景设为透明,文字改为适合深色卡面的颜色。overflow: hidden,即可让卡片与背景图重合。pan_card_id 和 card_id 有什么区别?card_id 是开放 API 中的卡片 ID,用于所有开放 API 接口(包括 pan-token);pan_card_id 只用于前端 SDK 的 cardId。http://(localhost 除外),或 App 用 file:// 加载页面,导致无法使用 WebCrypto。其他原因包括 iframe sandbox 缺少 allow-same-origin,或 WebView 内核过旧。INVALID_TOKEN,关闭后重新打开即可(会重新签票)。createElement 并 mount,各自独立签票、独立事件。showData 只控制初始状态。lang 决定,遮罩格式固定。字体、字号、颜色可通过 styles 白名单调整。url()、calc()、!important)。常见不生效的属性有 line-height、box-shadow。url(),请参考自有品牌卡面,在外层容器放背景图。POST /agent/v1/card/set-pin。