@solo-pay/widget-js

Lightweight, framework-agnostic payment widget for SoloPay.

Installation

npm install @solo-pay/widget-js
# or
yarn add @solo-pay/widget-js
# or
pnpm add @solo-pay/widget-js

CDN

<script src="https://cdn.jsdelivr.net/npm/@solo-pay/widget-js/dist/widget.min.js"></script>

Usage

Vanilla JavaScript

const soloPay = new SoloPay({ publicKey: 'pk_live_xxx' });

soloPay.requestPayment({
  orderId: 'order-123',
  amount: '10',
  tokenAddress: '0xc2132D05D31c914a87C6611C10748AEb04B58e8F',
  successUrl: 'https://example.com/success',
  failUrl: 'https://example.com/fail',
});

React / Next.js

import { SoloPay } from '@solo-pay/widget-js';
import { useEffect, useRef } from 'react';

export default function CheckoutButton() {
  const soloPayRef = useRef<SoloPay | null>(null);

  useEffect(() => {
    soloPayRef.current = new SoloPay({ publicKey: 'pk_live_xxx' });
    return () => soloPayRef.current?.destroy();
  }, []);

  const handlePay = () => {
    soloPayRef.current?.requestPayment(
      {
        orderId: 'order-123',
        amount: '10',
        tokenAddress: '0xc2132D05D31c914a87C6611C10748AEb04B58e8F',
        successUrl: `${window.location.origin}/success`,
        failUrl: `${window.location.origin}/fail`,
      },
      undefined,
      {
        onClose: () => console.log('Widget closed'),
      }
    );
  };

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

Note: For Next.js App Router, add 'use client' at the top of the file.

SDK Reference

new SoloPay(config)

| Option | Type | Default | Description | | -------------- | ---------------------------------- | ----------------------------- | ------------------------------------------------------------------- | | publicKey | string | required | Your SoloPay public key | | widgetUrl | string | https://widget.solo-pay.com | Widget base URL (no path). SDK uses / on mobile, /pc on desktop | | debug | boolean | false | Enable debug logging | | redirectMode | 'auto' \| 'redirect' \| 'iframe' | 'auto' | On mobile only; PC always uses popup |

Behaviour:

• PC: Always opens the widget in a popup window (no iframe).
• Mobile: 'auto' or 'redirect' = redirect to widget; 'iframe' is deprecated and treated as redirect.

soloPay.requestPayment(request, mode?, options?)

Opens the payment widget.

Parameters:

• request - Payment request object (see below)
• mode - Override redirect mode for this payment (optional)
• options - Additional options (optional)

Request:

| Parameter | Type | Required | Description | | -------------- | ------------------ | -------- | ----------------------- | | orderId | string | Yes | Unique order identifier | | amount | string \| number | Yes | Payment amount | | tokenAddress | string | Yes | Token contract address | | successUrl | string | Yes | Redirect URL on success | | failUrl | string | Yes | Redirect URL on failure |

Options:

| Option | Type | Description | | --------- | ------------ | ---------------------------------------- | | onClose | () => void | Callback when the widget/popup is closed |

soloPay.getWidgetUrl(request)

Returns the widget URL for custom implementations.

soloPay.closeWidget()

Closes the payment popup if open.

soloPay.destroy()

Destroys the SDK instance and cleans up resources.

License

MIT