@photonpay/cashierjs

Embedded payment SDK for PhotonPay. Drop a secure checkout into any website with a few lines of code.

Features

• Multiple Payment Methods — Credit card, Apple Pay, Google Pay, local payment, and cryptocurrency
• Embedded Checkout — Render a payment form inside an iframe on your page
• 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://cdn.photonpay.com/sdk/v2.0.19/photon-sdk.umd.js"
  integrity="sha384-xxx"
  crossorigin="anonymous">
</script>

<script>
  const { Photon } = PhotonSDK

  const photon = new Photon({
    environment: 'production',
    authCode: 'ac_xxx'
  })
</script>

integrity 值可从对应版本的 manifest 文件获取： https://cdn.photonpay.com/sdk/v2.0.11/manifest.json

Quick Start

import { Photon } from '@photonpay/cashierjs'

// 1. Create a Photon instance
const photon = new Photon({
  environment: 'production',
  authCode: 'ac_xxx'
})

// 2. Initialize the embedded checkout
const checkout = await photon.initEmbeddedCheckout({
  container: '#checkout-container',    // CSS selector or HTMLElement
  locale: 'en',                        // 'en' | 'zh-CN'
  theme: 'light',                      // 'light'
})

// 3. Listen for events
checkout.on('ready', () => console.log('Checkout ready'))
checkout.on('complete', (result) => console.log('Payment completed', result))
checkout.on('submit_error', (error) => console.log('Payment failed', error.message, error.tradeNo))
checkout.on('error', (error) => console.error('General error', error.message))
checkout.on('back_to_merchant', () => console.log('Back to merchant'))

// 4. Submit payment (e.g. on button click)
document.getElementById('pay-btn').addEventListener('click', async () => {
  try {
    await checkout.submit()
  } catch (err) {
    // 'Form validation failed' if form is incomplete
    console.error(err.message)
  }
})

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

Configuration

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

| Option | Type | Default | Description | |--------|------|---------|-------------| | environment | string | 'production' | Target environment | | 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

| Option | Type | Required | Description | |--------|------|----------|-------------| | container | string \| HTMLElement | ✅ | CSS selector or DOM element to mount the checkout | | locale | string | — | 'en' | 'zh-CN'. Defaults to browser language | | showOrderInfo | boolean | — | Show order info (default: true) | | theme | string | — | 'light' (default) | | debug | boolean | — | Enable verbose logging (default: false) | | onReady | (payload) => void | — | Called when checkout is ready | | onComplete | (result) => void | — | Called when payment succeeds | | onError | (error) => void | — | Called on general error | | onBackToMerchant | (payload) => void | — | Called when user clicks back |

Error Handling

// Initialization errors
try {
  const checkout = await photon.initEmbeddedCheckout({ ... })
} catch (err) {
  console.error('Init failed:', err.message)
}

// Payment failed — plain object with full response data
checkout.on('submit_error', (error) => {
  console.log(error.message)   // e.g. 'Payment failed'
  console.log(error.code)      // e.g. '0000'
  console.log(error.tradeNo)   // trade number
  console.log(error.reqId)     // request ID
  console.log(error.status)    // 'failed'
})

// General errors (also fires when submit_error occurs)
checkout.on('error', (error) => console.error(error.message))

Note: submit_error bubbles up to error. If you register both, payment failures will trigger both handlers. Use submit_error for payment-specific handling and error for system-level errors only.

Events

| Event | Payload | Description | |-------|---------|-------------| | ready | — | Checkout form loaded, safe to call submit() | | complete | { status, tradeNo, ... } | Payment succeeded | | submit_error | { message, code, tradeNo, reqId, status, ... } | Payment failed, full response data | | error | Error | General error (also fires on payment failure) | | submit_start | — | Payment request sent | | change | { config, validation, checkoutState } | Form data changed | | validation | { isValid, errors } | Form validation result | | resize | { height } | iframe height changed, unit: px | | back_to_merchant | — | User clicked back button | | 3ds_required | action | 3DS verification required (card payments) | | 3ds_complete | result | 3DS verification completed (card payments) |

Note: change, 3ds_required, and 3ds_complete are only relevant for card payments. Apple Pay and Google Pay use submit_start, complete, submit_error, and error.

Methods

checkout.submit()

Trigger payment submission programmatically. Runs form validation first — throws 'Form validation failed' if the form is incomplete, and fires the validation event with error details.

try {
  await checkout.submit()
} catch (err) {
  console.error(err.message) // 'Form validation failed'
}

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