npm package: @photonpay/cashierjs
Description: Photon Enterprise SDK
Author: Photon Team
Latest version: 2.0.6

# @photonpay/cashierjs

Embedded crypto payment SDK for [PhotonPay](https://www.photonpay.com). Drop a secure cryptocurrency checkout into any website with a few lines of code.

## Features

- **Crypto Payment** — Accept cryptocurrency payments via an embedded checkout form
- **Embedded Checkout** — Render a payment form inside an iframe on your page
- **Responsive** — Auto-detects desktop / mobile, or set manually
- **Secure** — All sensitive data handled inside an isolated iframe
- **TypeScript** — Ships with full type definitions

## Installation

```bash
# npm
npm install @photonpay/cashierjs

# yarn
yarn add @photonpay/cashierjs

# pnpm
pnpm add @photonpay/cashierjs
```

Or via CDN:

```html
<script src="https://unpkg.com/@photonpay/cashierjs/dist/photon-sdk.umd.min.js"></script>
```

## Quick Start

```js
import { Photon } from '@photonpay/cashierjs'

// 1. Create a Photon instance with your app ID
const photon = new Photon('your_app_id', {
  environment: 'production',
  platform: 'desktop'
})

// 2. Initialize the embedded checkout for crypto payment
const checkout = await photon.initEmbeddedCheckout({
  container: '#checkout-container',
  clientSecret: 'cs_xxx',
  enabledMethods: ['cryptoPay'],
  locale: 'en',
  payMethod: 'cryptoPay',
  defaultExpandedGroup: 'cryptoPay'
})

// 3. Listen for events
checkout.on('ready', () => console.log('Checkout ready'))
checkout.on('complete', (result) => console.log('Payment completed', result))
checkout.on('error', (error) => console.error('Payment error', error))

// 4. Submit payment (e.g. on button click)
document.getElementById('pay-btn').addEventListener('click', () => {
  checkout.submit()
})

// 5. Clean up when done
checkout.destroy()
```

## Configuration

```js
const photon = new Photon('your_app_id', {
  environment: 'production',  // 'production' | 'pre' | 'uat' | 'sit' | 'dev' | 'local'
  platform: 'auto',           // 'auto' | 'desktop' | 'mobile'
  debug: false,               // Enable debug logging
  authCode: 'ac_xxx',         // Authorization code (if required)
})
```

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `environment` | `string` | `'production'` | Target environment |
| `platform` | `string` | `'auto'` | Platform detection mode |
| `debug` | `boolean` | `false` | Enable verbose console logging |
| `authCode` | `string` | — | Authorization code for the session |
| `timeout` | `number` | `600000` | Request timeout in ms |

> **Note:** Non-production environments are only available when running on `localhost` or `*.photontech.cc` domains. External sites always resolve to `production`.

## Embedded Checkout Options

```js
const checkout = await photon.initEmbeddedCheckout({
  container: '#checkout',          // CSS selector or HTMLElement
  clientSecret: 'cs_xxx',         // Client secret from your server
  fetchClientSecret: async () => { // Or fetch it dynamically
    const res = await fetch('/api/create-session')
    const { clientSecret } = await res.json()
    return clientSecret
  },
  enabledMethods: ['cryptoPay'],
  locale: 'en',
  payMethod: 'cryptoPay',
  defaultExpandedGroup: 'cryptoPay',
  isShowPayInfo: true,
  onReady: (payload) => {},
  onComplete: (result) => {},
  onError: (error) => {},
  onBackToMerchant: (payload) => {},
})
```

## Events

Listen to checkout lifecycle events:

```js
checkout.on('ready', () => { /* Form loaded */ })
checkout.on('change', (data) => { /* Form data changed */ })
checkout.on('validation', (errors) => { /* Validation result */ })
checkout.on('submit_start', () => { /* Payment started */ })
checkout.on('complete', (result) => { /* Payment succeeded */ })
checkout.on('submit_error', (error) => { /* Payment failed */ })
checkout.on('resize', ({ height }) => { /* iframe resized */ })
checkout.on('back_to_merchant', () => { /* User clicked back */ })
checkout.on('error', (error) => { /* General error */ })
```

## Methods

### `checkout.submit()`

Trigger payment submission programmatically.

### `checkout.destroy()`

Remove the checkout iframe and clean up all event listeners.

### `checkout.updateConfig(config)`

Update checkout configuration after initialization.

### `checkout.mount(container)`

Mount the checkout to a different container.

## Browser Support

| Browser | Version |
|---------|---------|
| Chrome | 60+ |
| Firefox | 55+ |
| Safari | 12+ |
| Edge | 79+ |

## Module Formats

| Format | File | Use Case |
|--------|------|----------|
| ESM | `dist/photon-sdk.esm.js` | Vite, Webpack, Rollup |
| CJS | `dist/photon-sdk.cjs` | Node.js, CommonJS |
| UMD | `dist/photon-sdk.umd.js` | `<script>` tag, CDN |

## License

MIT