@gnosispay/pse-sdk

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

GnosisPay SDK for Partner Secure Elements

原始使用文档
文档目录18 节
  1. Migration guide
  2. migrating to @gnosispay/pse-sdk v2
  3. Features
  4. Installation
  5. Usage
  6. Getting Card Token
  7. Initialize the SDK
  8. Create and Mount Card Elements
  9. Available Elements
  10. Element Lifecycle
  11. Message Handling
  12. Ephemeral Token Management
  13. Security Considerations
  14. Development
  15. Setup
  16. Building
  17. Publishing
  18. Support

GnosisPay PSE (Partner Secure Elements)

A secure, PCI-compliant SDK for integrating payment card elements into web applications.

Migration guide

migrating to @gnosispay/pse-sdk v2

Most integrations are unaffected. This is only a breaking change if

  • your application uses GnosisPay API v2 AND
  • you were explicitly passing pseVersion: 2.
ConfigurationImpact
No pseVersion (default / V1 flow with gnosisPayApiAuthToken)No change
pseVersion: 1No change
pseVersion: 3No change
pseVersion: 2Breaking — must migrate to pseVersion: 3 (see below)

Gnosis Pay API version: Omitting pseVersion or setting pseVersion: 1 applies only to integrations using Gnosis Pay API v1. pseVersion: 2 and pseVersion: 3 are used with Gnosis Pay API v2.

PSE version 2 did not require a wallet signature. PSE version 3 adds an EIP-712 second-factor: the user's wallet must sign a message for every sensitive card operation (view card details, view PIN, set/change PIN). This provides an additional layer of protection if a JWT is ever leaked.

Migrating from pseVersion: 2 to 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,
});

Features

  • 🔒 PCI-compliant iframe-based card elements
  • 🌐 Cross-origin secure communication

Installation

You can install and use via standard npm i @gnosispay/pse-sdk or use CDN to load directly into your page.

<!-- 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>

Usage

Getting Card Token

Before initializing card elements, you'll need to obtain a card token identifier. You can get this from the GnosisPay API with the following endpoint:

API Endpoint: GET https://api.gnosispay.com/v1/cards

Documentation: List All Cards API Reference

The response will include card objects with cardToken fields that serve as your card tokens for the SDK.

Initialize the 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);
  },
});

Create and Mount Card Elements

// 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());

Available Elements

The SDK provides the following secure card elements:

  • ElementType.CardData - Read credit card number, expiration date and CVV
  • ElementType.CardPin - Read PIN of credit card
  • ElementType.SetCardPin - Set PIN of credit card
  • ElementType.CardExpirationCopied - User copied card expiration date
  • ElementType.CardSecurityCodeCopied - User copied card security code
  • ElementType.CardNumberCopied - User copied card number

Each element is rendered in a secure iframe to ensure PCI compliance.

Element Lifecycle

Elements can be initialized and destroyed:

// 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();

Message Handling

The SDK provides callbacks to handle messages from the iframe elements:

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

The SDK supports the following callback types:

  • onActionSuccess - Called when an action is successfully completed (e.g., setting a PIN, copying card data)
  • onInvalidToken - Called when the ephemeral token is invalid
  • onError - Called for other errors that may occur

Ephemeral Token Management

The SDK provides a method to refresh the ephemeral token when needed:

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

This is useful when the current ephemeral token has expired, at which point an onInvalidToken callback will be invoked.

Security Considerations

  • The SDK communicates with iframes using secure postMessage
  • All sensitive data is handled within PCI-compliant iframes
  • Origin verification is enforced for all communications
  • No sensitive data is exposed to the parent window
  • HTTPS is required for production use

Development

Setup

  1. Clone the repository
  2. Install dependencies:
    npm install
    
  3. Start the development server:
    npm run dev
    

Building

npm run build

Publishing

Publishing to NPM is automatic via CI on git tag. Version will be inferred from the tag.

Support

For issues and feature requests, please contact our support team or open an issue in our support portal.

版本与发布记录

@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 for Partner Secure Elements

如何安装 @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 和提交记录判断。