GnosisPay PSE (合作伙伴安全要素)
一个安全、符合PCI的SDK,用于将支付卡元素纳入网络应用程序.
移徙指南
迁移到 @ gnosispay/ pse- sdk v2
大多数整合没有受到影响. 这只是一个突破性的变化,如果
- 您的应用程序使用 GnosisPay API v2 和
- 你被明确通过
pseVersion: 2。 。 。 .
| 配置 | 影响 |
|---|---|
没有 pseVersion (默认 / V1 与 gnosisPayApiAuthToken(中文(简体) ) | 无变动 |
pseVersion: 1 | 无变动 |
pseVersion: 3 | 无变动 |
pseVersion: 2 | 断开 - 必须迁移到 pseVersion: 3 (见下文) |
Gnosis Pay API 版本 : 选择 pseVersion 或设置 pseVersion: 1 仅适用于使用 Gnosis 付费 API v1。 。 。 . pseVersion: 2 财务报告和审定财务报表 pseVersion: 3 用于 Gnosis 付费 API v2。 。 。 .
PSE 第2版不需要钱包签名 。 PSE 第3版增加了一款EIP-712第二因子:用户的钱包必须为每张敏感卡操作(查看卡细节,查看PIN,设定/更改PIN)签名消息. 如果JWT漏出,这又提供了一层保护.
从 pseVersion: 2 改为 pseVersion: 3数字 :
// 1. Before opening a card element, fetch an EIP-712 challenge from the auth-module
const response = await fetch(
`https://your-auth-module/pci/cards/${cardId}/challenge?action=view-details`,
{ headers: { Authorization: `Bearer ${authModuleJwt}` } }
);
const challenge = await response.json();
// action can be "view-details", "view-pin", or "change-pin"
// 2. Ask the user's wallet to sign the challenge
const signature = await wallet.signTypedData({
domain: challenge.domain,
types: challenge.types,
primaryType: challenge.primaryType,
message: {
authorization: challenge.message.authorization,
nonce: BigInt(challenge.message.nonce), // must be BigInt
},
});
// 3. Initialise the SDK — note pseVersion: 3
const gp = new GPSDK({
pseVersion: 3,
appId: "your_app_id",
ephemeralToken: "your_ephemeral_token",
authModuleToken: authModuleJwt,
eip712Signature: signature,
eip712Nonce: challenge.message.nonce,
});
特征
- +++ PCI 符合 iframe 的卡片元素
- * 跨界安全通信
安装
您可以通过标准安装和使用 npm i @gnosispay/pse-sdk 或使用CDN直接加载到您的页面.
<!-- For modern browsers (ES modules) -->
<script
type="module"
src="https://unpkg.com/@gnosispay/[email protected]/dist/gp-sdk.es.js"
></script>
<!-- For older browsers (UMD) -->
<script src="https://unpkg.com/@gnosispay/[email protected]/dist/gp-sdk.umd.js"></script>
使用量
获取纸牌
在初始化卡片元素之前,需要获得卡片符号标识符. 您可以从 GnosisPay API 中获取此选项,其端点如下:
API 终点数字 : GET https://api.gnosispay.com/v1/cards
文档数字 : 列出全部卡片 API 引用
答复中将包括卡片对象 cardToken 用作 SDK 的卡片符号的字段.
初始化 SDK
// ES modules
import GPSDK, { ElementType, IframeMessageType } from "@gnosispay/pse-sdk";
// Or if using the UMD build
const GPSDK = window.GPSDK;
const gp = new GPSDK({
appId: "your_app_id_provided_by_gnosispay",
ephemeralToken: "your_ephemeral_token_here",
gnosisPayApiAuthToken: "jwt_from_gnosispay_api",
iframeHost: "https://api-pse-public.gnosispay.com", // Optional, defaults to production
// Optional callbacks for handling messages from the iframe
onActionSuccess: (action) => {
console.log("Action completed successfully:", action);
},
onInvalidToken: (message) => {
console.error("Ephemeral token is invalid", message);
},
onError: (message, details) => {
console.error("An error occurred", message, details);
},
});
创建并挂载卡片元素
// Initialize and mount the card data element
const cardData = gp.init(ElementType.CardData, "#card-data-container", {
cardToken: "obtained-card-token",
});
// Initialize and mount the card PIN element
const cardPin = gp.init(ElementType.CardPin, "#card-pin-container", {
cardToken: "obtained-card-token",
});
// Initialize and mount the set PIN element
const setCardPin = gp.init(ElementType.SetCardPin, "#set-pin-container", {
cardToken: "obtained-card-token",
});
// When you're done with the elements
[cardData, cardPin, setCardPin].forEach((element) => element.destroy());
可用元素
SDK提供以下安全卡元素: 1
ElementType.CardData- 读取信用卡号码、过期日期和CVVElementType.CardPin- 阅读信用卡的PINElementType.SetCardPin- 设立PIN信用卡ElementType.CardExpirationCopied- 用户复制的卡片过期日期ElementType.CardSecurityCodeCopied- 用户复制的卡片安全码ElementType.CardNumberCopied- 用户复制的卡号
每个要素都在一个安全的iframe中提供,以确保遵守PCI.
元素生命周期
要素可以初始化并被销毁:
// Initialize an element
const cardDataContainer = gp.init(
ElementType.CardData,
"#card-data-container",
{
cardToken: "your-card-token",
}
);
// When you're done with the element
cardDataContainer.destroy();
信件处理
SDK提供回调处理来自iframe元素的信息:
// Initialize the SDK with callbacks
const gp = new GPSDK({
appId: "your_app_id_provided_by_gnosispay",
ephemeralToken: "your_ephemeral_token_here",
gnosisPayApiAuthToken: "jwt_from_gnosispay_api",
onActionSuccess: (action) => {
switch (action) {
case IframeMessageType.SetPinSuccess:
console.log("PIN was successfully set");
break;
case IframeMessageType.DoneSettingPin:
console.log("PIN setting process completed");
break;
case IframeMessageType.CardNumberCopied:
console.log("Card number was copied");
break;
case IframeMessageType.CardExpirationCopied:
console.log("Card expiration was copied");
break;
case IframeMessageType.CardSecurityCodeCopied:
console.log("Card security code was copied");
break;
}
},
onInvalidToken: (message) => {
console.error("Ephemeral token is invalid", message);
// Show error message to user or refresh token
},
onError: (message, details) => {
console.error("An error occurred", message, details);
// Handle other errors
},
});
SDK支持下列回调类型:
onActionSuccess- 当动作成功完成时调用(例如设置PIN,复制卡片数据)onInvalidToken- 当电期令牌无效时调用onError- 其他可能发生的错误
Ephemeral Token 管理系统
SDK提供了一个在需要时刷新电平符的方法:
// Refresh the ephemeral token
gp.refreshToken("new_ephemeral_token_here");
当当前发音符已过期时, 这一点是有用的 onInvalidToken 将引用回调.
安全考虑
- SDK 使用安全信使与 Iframe 通信
- 所有敏感数据均在符合PCI的iframes内处理
- 对所有通信执行来源核查
- 没有敏感数据暴露在父窗口
- 生产需要HTTPS
发展
设置
- 清除仓库
- 安装依赖性 :
npm install - 启动开发服务器 :
npm run dev
大楼
npm run build
出版
国家防范机制的出版工作通过CI自动进行。 版本将从标签中推断出来 .
支助
关于问题和专题请求,请与我们的支助小组联系,或在我们的支助门户网站上开启一个问题.