npm package: @gnosispay/pse-sdk
Description: GnosisPay SDK for Partner Secure Elements
Latest version: 1.5.0

# GnosisPay PSE (Partner Secure Elements)

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/pse-sdk` or use CDN to load directly into your page.

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

<!-- For older browsers (UMD) -->
<script src="https://unpkg.com/@gnosispay/pse-sdk@1.2.0/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](https://docs.gnosispay.com/api-reference/list-all-cards)

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

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

### Create and Mount Card Elements

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

### 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:

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

### Message Handling

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

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

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:

```javascript
// 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:
   ```bash
   npm install
   ```
3. Start the development server:
   ```bash
   npm run dev
   ```

### Building

```bash
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.