@gnosispay/pse-sdk

中文文档
2.0.1发布于 2026/04/23Apache-2.0TypeScriptESM + CJS零依赖近 30 天下载 4356

伴侣安全要素的GnosisPay SDK

中文使用文档
文档目录18 节
  1. 移徙指南
  2. 迁移到 @ gnosispay/ pse- sdk v2
  3. 特征
  4. 安装
  5. 使用量
  6. 获取纸牌
  7. 初始化 SDK
  8. 创建并挂载卡片元素
  9. 可用元素
  10. 元素生命周期
  11. 信件处理
  12. Ephemeral Token 管理系统
  13. 安全考虑
  14. 发展
  15. 设置
  16. 大楼
  17. 出版
  18. 支助

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 - 读取信用卡号码、过期日期和CVV
  • ElementType.CardPin - 阅读信用卡的PIN
  • ElementType.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

发展

设置

  1. 清除仓库
  2. 安装依赖性 :
    npm install
    
  3. 启动开发服务器 :
    npm run dev
    

大楼

npm run build

出版

国家防范机制的出版工作通过CI自动进行。 版本将从标签中推断出来 .

支助

关于问题和专题请求,请与我们的支助小组联系,或在我们的支助门户网站上开启一个问题.

版本与发布记录

@gnosispay/pse-sdk 共发布 14 个版本,首次发布于 2025/05/23;过去 12 个月发布了 5 个版本。

版本发布日期距今
2.0.1latest2026/04/236 个月前
2.0.02026/04/226 个月前
1.5.02026/04/077 个月前
1.4.02026/03/257 个月前
1.3.02025/12/0111 个月前
1.2.32025/10/201.1 年前

关于 @gnosispay/pse-sdk 的常见问题

@gnosispay/pse-sdk 是什么?

伴侣安全要素的GnosisPay SDK

如何安装 @gnosispay/pse-sdk?

在项目目录运行 npm install @gnosispay/pse-sdk,或使用 pnpm add / yarn add / bun add。

@gnosispay/pse-sdk 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@gnosispay/pse-sdk 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@gnosispay/pse-sdk 可以商用吗?

@gnosispay/pse-sdk 使用 Apache-2.0 许可。宽松许可:允许商业使用、修改和再分发,并附带明确的专利授权;分发时需保留许可与 NOTICE 文件,修改过的文件要注明改动。以上为概括,不构成法律意见,请以许可原文为准。

@gnosispay/pse-sdk 的下载量有多少?

根据 npm 官方下载统计,@gnosispay/pse-sdk 在 2026/10/17 – 2026/11/15 这 30 天内被下载 4,356 次,日均约 145 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@gnosispay/pse-sdk 还在维护吗?

最新版本 2.0.1 发布于 2026/04/23(6 个月前);至今共发布 14 个版本,其中过去 12 个月发布了 5 个;首次发布于 2025/05/23。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。