@photonpay/cashierjs

Embedded crypto payment SDK for PhotonPay. 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

# npm
npm install @photonpay/cashierjs

# yarn
yarn add @photonpay/cashierjs

# pnpm
pnpm add @photonpay/cashierjs

Or via CDN:

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

Quick Start

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

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

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:

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