@arthapay/widget

Embeddable crypto payment widget for ArthaPay — accept Bitcoin, Ethereum, USDC, and 12+ cryptocurrencies on any website with a single script tag or npm package.

Features

• Zero dependencies for the IIFE build — drop a single <script> tag
• Modal checkout — full in-page payment flow with QR code and real-time status
• Redirect checkout — send users to a hosted checkout page
• React component and hook included
• Declarative buttons via data-arthapay HTML attributes (no JS required)
• Shadow DOM isolation — widget styles never conflict with your page
• Real-time payment detection via Socket.IO
• Supports 12+ cryptocurrencies across 8 networks

Supported Currencies

BTC · ETH · USDC · USDT · MATIC · BNB · LTC · BCH · DOGE · SOL · TRX · XRP

Installation

Via npm

npm install @arthapay/widget

Via CDN (script tag)

<script src="https://cdn.jsdelivr.net/npm/@arthapay/widget/dist/arthapay.js"></script>

Usage

1. Script Tag (IIFE — simplest)

Drop the script tag anywhere on your page, then call ArthaPay.init():

<script src="https://cdn.jsdelivr.net/npm/@arthapay/widget/dist/arthapay.js"></script>
<script>
  const ap = ArthaPay.init({
    apiKey: 'pk_live_your_api_key',
    baseUrl: 'https://your-arthapay-server.com', // optional, auto-detected from script src
  });

  document.getElementById('pay-btn').addEventListener('click', () => {
    ap.createCheckout({
      amount: 49.99,
      currency: 'USD',
      orderId: 'ORD-001',
      onSuccess: (payment) => {
        console.log('Payment confirmed!', payment);
        window.location.href = '/thank-you';
      },
      onClose: () => console.log('Modal closed'),
      onError: (err) => console.error('Payment error', err),
    });
  });
</script>

2. Declarative Buttons (zero JS)

Add data-arthapay to any element and the widget will automatically inject a styled pay button inside it:

<script src="https://cdn.jsdelivr.net/npm/@arthapay/widget/dist/arthapay.js"></script>

<div
  data-arthapay
  data-api-key="pk_live_your_api_key"
  data-amount="29.99"
  data-currency="USD"
  data-order-id="ORD-001"
></div>

The widget scans the DOM on load and replaces matching elements with a styled "Pay with Crypto" button.

3. React — <ArthaPayButton> Component

import { ArthaPayButton } from '@arthapay/widget/react';

export function CheckoutPage() {
  return (
    <ArthaPayButton
      apiKey="pk_live_your_api_key"
      baseUrl="https://your-arthapay-server.com"
      amount={49.99}
      currency="USD"
      orderId="ORD-001"
      onSuccess={(payment) => {
        console.log('Paid!', payment.txHash);
      }}
      onClose={() => console.log('closed')}
      className="my-button-class"
    >
      Pay with Crypto
    </ArthaPayButton>
  );
}

Props

| Prop | Type | Default | Description | |---|---|---|---| | apiKey | string | required | Your ArthaPay API key | | baseUrl | string | auto-detected | ArthaPay server base URL | | amount | number | required | Charge amount | | currency | string | 'USD' | Fiat currency (USD, EUR, GBP, CAD, AUD) | | orderId | string | — | Your internal order reference | | redirectUrl | string | — | URL to redirect after payment (used with mode: 'redirect') | | metadata | object | — | Arbitrary key/value pairs stored on the invoice | | mode | 'modal' \| 'redirect' | 'modal' | Checkout mode | | onSuccess | (payment: PaymentData) => void | — | Called when payment is confirmed | | onClose | () => void | — | Called when the modal is dismissed | | onError | (error: Error) => void | — | Called on errors | | children | ReactNode | 'Pay $X.XX with Crypto' | Button label | | className | string | — | CSS class for the <button> element | | disabled | boolean | — | Disables the button |

4. React — useArthaPay Hook

For full control over when and how to trigger checkout:

import { useArthaPay } from '@arthapay/widget/react';

export function CartPage() {
  const { createCheckout, redirectToCheckout } = useArthaPay({
    apiKey: 'pk_live_your_api_key',
    baseUrl: 'https://your-arthapay-server.com',
  });

  const handlePay = () => {
    createCheckout({
      amount: 99.00,
      currency: 'USD',
      orderId: 'ORD-123',
      onSuccess: (payment) => {
        console.log('Confirmed tx:', payment.txHash);
      },
    });
  };

  return <button onClick={handlePay}>Pay Now</button>;
}

Hook return values

| Method | Signature | Description | |---|---|---| | createCheckout | (options: CheckoutOptions) => void | Opens the modal checkout | | redirectToCheckout | (options: RedirectCheckoutOptions) => Promise<void> | Redirects to hosted checkout |

5. Redirect to Hosted Checkout

Send customers to ArthaPay's hosted checkout page (useful when you don't want to embed the modal):

const ap = ArthaPay.init({ apiKey: 'pk_live_your_api_key' });

ap.redirectToCheckout({
  amount: 29.99,
  currency: 'EUR',
  orderId: 'ORD-002',
  redirectUrl: 'https://yoursite.com/thank-you', // redirect after payment
});

Configuration

ArthaPayConfig

interface ArthaPayConfig {
  apiKey: string;    // Your merchant API key from the ArthaPay dashboard
  baseUrl?: string;  // Base URL of your ArthaPay server (auto-detected from script src)
}

CheckoutOptions

interface CheckoutOptions {
  amount: number;                             // Charge amount in fiat
  currency?: string;                          // 'USD' | 'EUR' | 'GBP' | 'CAD' | 'AUD'
  orderId?: string;                           // Your order reference
  redirectUrl?: string;                       // Redirect URL after payment
  metadata?: Record<string, unknown>;         // Custom data stored on the invoice
  onSuccess?: (payment: PaymentData) => void; // Payment confirmed callback
  onClose?: () => void;                       // Modal closed callback
  onError?: (error: Error) => void;           // Error callback
}

PaymentData

interface PaymentData {
  status: string;          // 'confirmed' | 'complete'
  currency: string;        // Crypto currency (e.g. 'ETH')
  network: string;         // Network (e.g. 'ethereum')
  amount: string;          // Crypto amount paid
  txHash: string | null;   // On-chain transaction hash
  confirmations: number;
  detectedAt: string | null;
  confirmedAt: string | null;
}

API Reference

ArthaPay.init(config) → ArthaPayWidget

Initialises the widget. If called again, destroys the previous instance first.

widget.createCheckout(options) → void

Opens the embedded checkout modal.

widget.redirectToCheckout(options) → Promise<void>

Creates an invoice server-side and redirects the browser to the hosted checkout page.

widget.destroy() → void

Unmounts the widget and removes it from the DOM.

ArthaPay.getInstance() → ArthaPayWidget | null

Returns the current widget instance (or null if not initialised).

TypeScript

Full TypeScript types are included. Import from the package directly:

import type {
  ArthaPayConfig,
  CheckoutOptions,
  RedirectCheckoutOptions,
  PaymentData,
  InvoiceData,
  CryptoOption,
} from '@arthapay/widget/react';

Bundle Formats

| File | Format | Use case | |---|---|---| | dist/arthapay.js | IIFE (self-contained) | <script> tag, CDN | | dist/iife/arthapay.js | IIFE (self-contained) | <script> tag, CDN | | dist/esm/index.js | ESM (React bundled) | npm + bundler (React included) | | dist/esm/react.js | ESM (React as peer dep) | npm + bundler (bring your own React) | | dist/types/ | TypeScript declarations | Type checking |

License

MIT © ArthaPay