@ironix-pay/sdk

Embed IronixPay Checkout directly into your website using an iFrame-based SDK.

Installation

NPM

npm install @ironix-pay/sdk

CDN

<script src="https://unpkg.com/@ironix-pay/sdk@latest/dist/ironix-pay.umd.js"></script>

Quick Start

import { IronixPay } from '@ironix-pay/sdk';

// 1. Initialize SDK
const ironixPay = new IronixPay({
  environment: 'production' // or 'sandbox'
});

// 2. Create payment element (sessionId from your backend)
const element = ironixPay.createPaymentElement({
  sessionId: 'cs_abc123',
  theme: 'dark',
  locale: 'en'
});

// 3. Mount to DOM
element.mount('#checkout-container');

// 4. Listen for events
element.on('ready', () => console.log('Checkout loaded'));

element.on('payment_success', (result) => {
  console.log('Payment successful!', result);
  // ⚠️ IMPORTANT: Verify via webhook before fulfilling order
  window.location.href = `/orders/${result.sessionId}/success`;
});

element.on('payment_expired', () => {
  console.log('Session expired');
});

element.on('error', (err) => {
  console.error('Checkout error:', err);
  // Show fallback UI
});

CDN Usage

<script>
  const ironixPay = new IronixPay.default({
    environment: 'production'
  });
  // ... same as above
</script>

API Reference

IronixPay(options)

| Option | Type | Required | Description | |--------|------|----------|-------------| | environment | 'production' \| 'sandbox' | ❌ | Default: 'production' | | checkoutUrl | string | ❌ | Custom checkout URL (self-hosted) |

createPaymentElement(options)

| Option | Type | Required | Description | |--------|------|----------|-------------| | sessionId | string | ✅ | Checkout session ID from backend | | theme | 'light' \| 'dark' \| 'auto' | ❌ | Default: 'dark' | | locale | 'en' \| 'zh-CN' | ❌ | Default: 'en' | | style.width | string | ❌ | Default: '100%' | | style.height | string | ❌ | Default: '480px' | | style.borderRadius | string | ❌ | Default: '12px' |

Events

| Event | Payload | Description | |-------|---------|-------------| | ready | - | Checkout loaded successfully | | payment_success | PaymentResult | Payment confirmed | | payment_expired | { sessionId } | Session expired | | payment_detected | { sessionId, amountReceived } | Transaction detected (pending) | | error | PaymentError | Load or runtime error | | resize | { height } | iFrame content height changed |

Security Note

⚠️ Never rely on frontend events for order fulfillment!

The payment_success event is for UI purposes only. Always verify payment status via backend webhooks before shipping products or granting access.

License

MIT