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.

| Configuration | Impact | |---|---| | No pseVersion (default / V1 flow with gnosisPayApiAuthToken) | No change | | pseVersion: 1 | No change | | pseVersion: 3 | No change | | pseVersion: 2 | Breaking — 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.