# @gnosispay/pse-sdk 中文文档

规范地址：https://npmcn.com/package/%40gnosispay/pse-sdk/

版本：2\.0\.1
npm 元数据更新时间：2026-04-23T13:24:57.390Z
中文译文更新时间：2026-11-16T17:28:12.393Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40gnosispay/pse-sdk
原文对照：https://npmcn.com/package/%40gnosispay/pse-sdk/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：65.7 kB，9 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2025-05-23T13:27:30.730Z
- 最新版本发布：2026-04-23T13:24:57.271Z
- 近 30 天下载量：4356（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：14（近 12 个月 5 个）

## 中文简介

伴侣安全要素的GnosisPay SDK

## 安装

```sh
npm install @gnosispay/pse-sdk
```

也可以使用：`pnpm add @gnosispay/pse-sdk`、`yarn add @gnosispay/pse-sdk`、`bun add @gnosispay/pse-sdk`

## README

# 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`数字 :**

```javascript
// 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直接加载到您的页面.

```html
<!-- For modern browsers (ES modules) -->
<script
  type="module"
  src="https://unpkg.com/@gnosispay/pse-sdk@2.0.0/dist/gp-sdk.es.js"
></script>

<!-- For older browsers (UMD) -->
<script src="https://unpkg.com/@gnosispay/pse-sdk@2.0.0/dist/gp-sdk.umd.js"></script>
```

## 使用量

### 获取纸牌

在初始化卡片元素之前,需要获得卡片符号标识符. 您可以从 GnosisPay API 中获取此选项,其端点如下:

**API 终点**数字 : `GET https://api.gnosispay.com/v1/cards`

**文档**数字 : [列出全部卡片 API 引用](https://docs.gnosispay.com/api-reference/list-all-cards)

答复中将包括卡片对象 `cardToken` 用作 SDK 的卡片符号的字段.

### 初始化 SDK

```javascript
// 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);
  },
});
```

### 创建并挂载卡片元素

```javascript
// 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.

### 元素生命周期

要素可以初始化并被销毁:

```javascript
// 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元素的信息:

```javascript
// 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提供了一个在需要时刷新电平符的方法:

```javascript
// Refresh the ephemeral token
gp.refreshToken("new_ephemeral_token_here");
```

当当前发音符已过期时, 这一点是有用的 `onInvalidToken` 将引用回调.

## 安全考虑

-   SDK 使用安全信使与 Iframe 通信
-   所有敏感数据均在符合PCI的iframes内处理
-   对所有通信执行来源核查
-   没有敏感数据暴露在父窗口
-   生产需要HTTPS

## 发展

### 设置

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

### 大楼

```bash
npm run build
```

### 出版

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

## 支助

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

## 常见问题

### @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 和提交记录判断。

