GnosisPay SDK

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

Features

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

Installation

You can install and use via standard npm i @gnosispay/pci-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

Initialize the SDK

// ES modules
import GPSDK from "@gnosispay/pci-sdk";

// Or if using the UMD build
const GPSDK = window.GPSDK;

const gp = new GPSDK({
  ephemeralToken: "your_ephemeral_token_here",
  gnosisPayApiAuthToken: "jwt_from_gnosispay_api",
  // Optional callbacks for handling messages from the iframe
  onActionSuccess: (action) => {
    console.log("PIN was successfully set");
  },
  onInvalidToken: (message) => {
    console.error("Ephemeral token is invalid", message);
  },
  onError: (message, details) => {
    console.error("An error occurred", message, details);
  },
});

await gp.init();

Create and Mount Card Elements

// Initialize and mount card number element
const cardNumber = gp.init("cardData", "#card-number-container", {
  cardToken: "your-card-token",
});

// When you're done with the element
cardNumber.destroy();

Available Elements

The SDK provides the following secure card elements:

• cardData - Read credit card number, expiration date and CVV
• cardPin - Read PIN of credit card
• setCardPin - Set PIN of credit card

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

Element Lifecycle

Elements can be initialized and destroyed:

// Initialize an element
const cardNumber = gp.init("cardData", "#card-number-container", {
  cardToken: "your-card-token",
});

// When you're done with the element
cardNumber.destroy();

Message Handling

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

// Initialize the SDK with callbacks
const gp = new GPSDK({
  ephemeralToken: "your_ephemeral_token_here",
  gnosisPayApiAuthToken: "jwt_from_gnosispay_api",
  onActionSuccess: (action) => {
    console.log("PIN was successfully set");
  },
  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)
• onInvalidToken - Called when the ephemeral token is invalid
• onError - Called for other errors that may occur

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.