npm package: @gnosispay/pci-sdk
Description: GnosisPay SDK for secure card info
Latest version: 1.0.6

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

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

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

## Usage

### Initialize the SDK

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

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

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

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