forgelayer-react 1.0.0

package/README.md

@@ -0,0 +1,256 @@
+# forgelayer-react
+
+> React components for crypto checkout powered by [ForgeLayer](https://forgelayer.io).
+
+Drop a `<ForgeLayerButton>` anywhere in your React app and get a full crypto payment modal — QR code, countdown timer, live status polling, and success/expired states — with zero UI dependencies.
+
+---
+
+## Install
+
+```bash
+npm install forgelayer-react
+```
+
+Requires React 17 or later. Pairs with [`forgelayer-node`](https://github.com/forgelayer-tech/forgelayer-node) on the backend.
+
+---
+
+## Quick Start
+
+```jsx
+import { ForgeLayerButton } from 'forgelayer-react';
+
+export default function ProductPage() {
+  return (
+    <ForgeLayerButton
+      amount={49.99}
+      currency="USD"
+      chain="ethereum"
+      token="USDT"
+      orderId="ORDER-123"
+      baseUrl="/fl"
+      onSuccess={(order) => console.log('Paid!', order)}
+    >
+      Pay $49.99 with USDT
+    </ForgeLayerButton>
+  );
+}
+```
+
+---
+
+## How It Works
+
+```
+<ForgeLayerButton> clicked
+   │
+   ├── POST /fl/create   →  Node.js backend (forgelayer-node)
+   │                         generates deposit address + crypto amount
+   │
+   ├── modal opens       →  QR code + address + countdown timer
+   │
+   └── GET /fl/status    →  polls every 15 seconds
+         ├── pending      →  keep showing modal
+         ├── confirmed    →  show success state, fire onSuccess()
+         └── expired      →  show expired state, fire onExpired()
+```
+
+All API calls go to your own backend — the React component never talks to ForgeLayer directly.
+
+---
+
+## Proxy Setup
+
+In development, proxy `/fl` to your Node.js backend in `vite.config.js`:
+
+```js
+export default {
+  server: {
+    proxy: {
+      '/fl': 'http://localhost:3000',
+    },
+  },
+};
+```
+
+In production, your reverse proxy (nginx/Caddy) handles it.
+
+---
+
+## Components
+
+### `<ForgeLayerButton>`
+
+Self-contained button + modal. The simplest way to add crypto checkout.
+
+```jsx
+<ForgeLayerButton
+  // Payment params
+  amount={49.99}
+  currency="USD"           // default: 'USD'
+  chain="ethereum"         // ethereum | bsc | tron | bitcoin
+  token="USDT"             // any token supported by your backend
+  orderId="ORDER-123"      // your order ID
+  paymentWindow={30}       // minutes before payment expires (default: 30)
+  reuseAddress={false}     // reuse deposit address for same orderId
+
+  // Backend
+  baseUrl="/fl"            // path where forgelayer-node is mounted
+
+  // Button UI
+  label="Pay with Crypto"  // overridden by children if provided
+  className="my-btn"       // optional CSS class
+  style={{ width: '100%' }}
+
+  // Callbacks
+  onSuccess={(order) => router.push('/thank-you')}
+  onExpired={() => setShowExpiredMsg(true)}
+  onError={(err) => console.error(err)}
+>
+  Pay $49.99 with USDT
+</ForgeLayerButton>
+```
+
+---
+
+### `useForgeLayerCheckout(options)`
+
+Hook for full control — use when you need to trigger checkout from your own button, form, or custom event.
+
+```jsx
+import { useForgeLayerCheckout, ForgeLayerModal } from 'forgelayer-react';
+
+function CustomCheckout() {
+  const { modalState, order, timeLeft, error, open, close } = useForgeLayerCheckout({
+    baseUrl:   '/fl',
+    onSuccess: (order) => console.log('Confirmed:', order),
+    onExpired: ()      => console.log('Expired'),
+    onError:   (err)   => console.error(err),
+  });
+
+  return (
+    <>
+      <button onClick={() => open({ amount: 25, currency: 'USD', chain: 'tron', token: 'USDT', orderId: 'ORDER-1' })}>
+        Pay with Crypto
+      </button>
+
+      {modalState !== 'closed' && (
+        <ForgeLayerModal
+          modalState={modalState}
+          order={order}
+          timeLeft={timeLeft}
+          error={error}
+          onClose={close}
+        />
+      )}
+    </>
+  );
+}
+```
+
+**`open(params)`** — opens the modal and calls `/fl/create`.
+
+| Param | Type | Description |
+|---|---|---|
+| `amount` | `number` | Fiat amount to charge |
+| `currency` | `string` | ISO currency code (e.g. `'USD'`) |
+| `chain` | `string` | `ethereum` \| `bsc` \| `tron` \| `bitcoin` |
+| `token` | `string` | Token symbol (e.g. `'USDT'`, `'ETH'`, `'BTC'`) |
+| `orderId` | `string` | Your order ID |
+| `paymentWindow` | `number` | Minutes until expiry (default: `30`) |
+
+**Hook return values:**
+
+| Value | Type | Description |
+|---|---|---|
+| `modalState` | `string` | `'closed'` \| `'loading'` \| `'payment'` \| `'success'` \| `'expired'` \| `'error'` |
+| `order` | `object \| null` | Response from `/fl/create` |
+| `timeLeft` | `number \| null` | Seconds remaining in payment window |
+| `error` | `string \| null` | Error message if `modalState === 'error'` |
+| `open(params)` | `function` | Start a new checkout session |
+| `close()` | `function` | Close the modal and reset state |
+
+---
+
+### `<ForgeLayerModal>`
+
+The modal UI on its own. Used alongside `useForgeLayerCheckout` for custom layouts.
+
+```jsx
+<ForgeLayerModal
+  modalState={modalState}   // from useForgeLayerCheckout
+  order={order}
+  timeLeft={timeLeft}
+  error={error}
+  onClose={close}
+/>
+```
+
+---
+
+## Modal States
+
+| State | What the user sees |
+|---|---|
+| `loading` | Spinner — "Generating payment address…" |
+| `payment` | QR code, deposit address, amount, countdown timer |
+| `success` | ✅ Payment Confirmed |
+| `expired` | ⏳ Payment Expired |
+| `error` | ⚠️ Error message |
+
+---
+
+## Full Example
+
+```jsx
+import { ForgeLayerButton } from 'forgelayer-react';
+
+const PRODUCTS = [
+  { id: 'PRO-001', name: 'Pro License',  price: 49.99, chain: 'ethereum', token: 'USDT' },
+  { id: 'PLAN-002', name: 'Annual Plan', price: 119.88, chain: 'bitcoin',  token: 'BTC'  },
+];
+
+export default function Shop() {
+  return (
+    <div>
+      {PRODUCTS.map((p) => (
+        <div key={p.id}>
+          <h2>{p.name} — ${p.price}</h2>
+          <ForgeLayerButton
+            amount={p.price}
+            chain={p.chain}
+            token={p.token}
+            orderId={p.id}
+            baseUrl="/fl"
+            onSuccess={() => alert('Payment received!')}
+          >
+            Pay with {p.token}
+          </ForgeLayerButton>
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+---
+
+## Backend
+
+This package is the frontend half. You need [`forgelayer-node`](https://github.com/forgelayer-tech/forgelayer-node) on your Express server:
+
+```bash
+npm install forgelayer-node
+```
+
+```js
+const { createCheckout } = require('forgelayer-node');
+app.use('/fl', createCheckout({ apiKey: process.env.FORGELAYER_API_KEY }).middleware());
+```
+
+---
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "forgelayer-react",
+  "version": "1.0.0",
+  "description": "React components for crypto checkout powered by ForgeLayer",
+  "main": "src/index.js",
+  "module": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src/",
+    "README.md"
+  ],
+  "keywords": [
+    "forgelayer", "crypto", "payments", "bitcoin", "ethereum",
+    "usdt", "react", "checkout", "modal", "components"
+  ],
+  "author": "ForgeLayer <support@forgelayer.io>",
+  "license": "MIT",
+  "homepage": "https://github.com/forgelayer-tech/forgelayer-react#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/forgelayer-tech/forgelayer-react.git"
+  },
+  "bugs": {
+    "url": "https://github.com/forgelayer-tech/forgelayer-react/issues"
+  },
+  "peerDependencies": {
+    "react": ">=17.0.0",
+    "react-dom": ">=17.0.0"
+  }
+}

package/src/ForgeLayerButton.jsx

@@ -0,0 +1,94 @@
+import React from 'react';
+import { useForgeLayerCheckout } from './useForgeLayerCheckout.js';
+import { ForgeLayerModal } from './ForgeLayerModal.jsx';
+
+/**
+ * Drop-in React checkout button.
+ *
+ * Usage:
+ *   <ForgeLayerButton
+ *     amount={49.99}
+ *     currency="USD"
+ *     chain="ethereum"
+ *     token="USDT"
+ *     orderId="ORDER-123"
+ *     onSuccess={(order) => router.push('/thank-you')}
+ *   >
+ *     Pay $49.99
+ *   </ForgeLayerButton>
+ */
+export function ForgeLayerButton({
+  // Payment params
+  amount,
+  currency       = 'USD',
+  chain          = 'ethereum',
+  token          = 'USDT',
+  orderId,
+  paymentWindow,
+  reuseAddress,
+  // Backend base path (proxied or absolute)
+  baseUrl        = '/fl',
+  // Button UI
+  label,
+  children,
+  className,
+  style,
+  disabled,
+  // Callbacks
+  onSuccess,
+  onExpired,
+  onError,
+}) {
+  const { modalState, order, timeLeft, error, open, close } = useForgeLayerCheckout({
+    baseUrl,
+    onSuccess,
+    onExpired,
+    onError,
+  });
+
+  const isOpen = modalState !== 'closed';
+
+  const handleClick = () => {
+    open({ amount, currency, chain, token, orderId, paymentWindow, reuseAddress });
+  };
+
+  return (
+    <>
+      <button
+        onClick={handleClick}
+        disabled={disabled || isOpen}
+        className={className}
+        style={{
+          display: 'inline-flex',
+          alignItems: 'center',
+          gap: 8,
+          padding: '12px 24px',
+          background: '#f7931a',
+          color: '#fff',
+          border: 'none',
+          borderRadius: 8,
+          fontSize: 15,
+          fontWeight: 600,
+          cursor: (disabled || isOpen) ? 'not-allowed' : 'pointer',
+          opacity: (disabled || isOpen) ? 0.65 : 1,
+          fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif',
+          lineHeight: 1.2,
+          transition: 'opacity .15s',
+          ...style,
+        }}
+      >
+        {label ?? children ?? 'Pay with Crypto'}
+      </button>
+
+      {isOpen && (
+        <ForgeLayerModal
+          modalState={modalState}
+          order={order}
+          timeLeft={timeLeft}
+          error={error}
+          onClose={close}
+        />
+      )}
+    </>
+  );
+}

package/src/ForgeLayerModal.jsx

@@ -0,0 +1,267 @@
+import React, { useEffect, useState } from 'react';
+
+// Injected once — handles animations, hover, and pseudo-elements
+// that can't be done with inline styles.
+const MODAL_CSS = `
+@keyframes fl-r-fade{from{opacity:0}to{opacity:1}}
+@keyframes fl-r-up{from{transform:translateY(16px);opacity:0}to{transform:translateY(0);opacity:1}}
+@keyframes fl-r-spin{to{transform:rotate(360deg)}}
+@keyframes fl-r-pulse{0%,100%{opacity:1}50%{opacity:.35}}
+.fl-r-backdrop{position:fixed;inset:0;background:rgba(0,0,0,.6);z-index:99999;
+  display:flex;align-items:center;justify-content:center;padding:16px;
+  animation:fl-r-fade .18s ease}
+.fl-r-modal{background:#fff;border-radius:16px;width:100%;max-width:520px;
+  box-shadow:0 24px 64px rgba(0,0,0,.28);overflow:hidden;
+  animation:fl-r-up .22s ease;
+  font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif;
+  font-size:14px;color:#111}
+.fl-r-spinner{width:38px;height:38px;border:3px solid #e5e7eb;
+  border-top-color:#f7931a;border-radius:50%;
+  animation:fl-r-spin .7s linear infinite;margin:0 auto 14px}
+.fl-r-dot-pending{background:#f59e0b;animation:fl-r-pulse 1.6s ease-in-out infinite}
+.fl-r-dot-confirmed{background:#10b981}
+.fl-r-dot-expired{background:#ef4444}
+.fl-r-xbtn:hover{background:#f3f4f6 !important;color:#111 !important}
+.fl-r-cpbtn:hover{background:#f3f4f6 !important}
+.fl-r-cpbtn-copied{border-color:#10b981 !important;color:#059669 !important}
+@media(max-width:460px){.fl-r-grid{flex-direction:column !important;align-items:center !important}}
+`;
+
+let _cssInjected = false;
+function ensureCSS() {
+  if (_cssInjected || typeof document === 'undefined') return;
+  _cssInjected = true;
+  const el = document.createElement('style');
+  el.textContent = MODAL_CSS;
+  document.head.appendChild(el);
+}
+
+function fmtTime(secs) {
+  const m = Math.floor(secs / 60);
+  const s = secs % 60;
+  return `${String(m).padStart(2, '0')}:${String(s).padStart(2, '0')}`;
+}
+
+export function ForgeLayerModal({ modalState, order, timeLeft, error, onClose }) {
+  const [copied, setCopied] = useState(false);
+
+  useEffect(() => { ensureCSS(); }, []);
+
+  // Escape key
+  useEffect(() => {
+    const handler = (e) => { if (e.key === 'Escape') onClose(); };
+    document.addEventListener('keydown', handler);
+    return () => document.removeEventListener('keydown', handler);
+  }, [onClose]);
+
+  // Lock body scroll
+  useEffect(() => {
+    const prev = document.body.style.overflow;
+    document.body.style.overflow = 'hidden';
+    return () => { document.body.style.overflow = prev; };
+  }, []);
+
+  const copyAddress = () => {
+    if (!order?.address) return;
+    navigator.clipboard?.writeText(order.address).catch(() => {});
+    setCopied(true);
+    setTimeout(() => setCopied(false), 2000);
+  };
+
+  const urgent = timeLeft !== null && timeLeft <= 120;
+
+  return (
+    <div
+      className="fl-r-backdrop"
+      role="dialog"
+      aria-modal="true"
+      aria-label="Crypto payment"
+      onClick={(e) => { if (e.target === e.currentTarget) onClose(); }}
+    >
+      <div className="fl-r-modal">
+
+        {/* ── Header ── */}
+        <div style={{
+          display: 'flex', alignItems: 'center', justifyContent: 'space-between',
+          padding: '16px 18px', borderBottom: '1px solid #e5e7eb', background: '#fafafa',
+        }}>
+          <div style={{ display: 'flex', alignItems: 'center', gap: 9, fontSize: 15, fontWeight: 700 }}>
+            <div style={{
+              width: 26, height: 26, background: '#f7931a', borderRadius: 6,
+              display: 'flex', alignItems: 'center', justifyContent: 'center',
+              color: '#fff', fontSize: 10, fontWeight: 800, flexShrink: 0,
+            }}>FL</div>
+            Pay with Crypto
+          </div>
+          <button
+            className="fl-r-xbtn"
+            onClick={onClose}
+            aria-label="Close"
+            style={{
+              background: 'none', border: 'none', fontSize: 22, lineHeight: 1,
+              cursor: 'pointer', color: '#6b7280', padding: '4px 8px',
+              borderRadius: 5, transition: 'background .12s',
+            }}
+          >×</button>
+        </div>
+
+        {/* ── Body ── */}
+        <div style={{ padding: '20px 18px' }}>
+
+          {/* Loading */}
+          {modalState === 'loading' && (
+            <div style={{ textAlign: 'center', padding: '28px 0' }}>
+              <div className="fl-r-spinner" />
+              <p style={{ color: '#6b7280', fontSize: 13, margin: 0 }}>
+                Generating payment address…
+              </p>
+            </div>
+          )}
+
+          {/* Error */}
+          {modalState === 'error' && (
+            <div style={{ textAlign: 'center', padding: '28px 0' }}>
+              <div style={{ fontSize: 48, marginBottom: 12 }}>⚠️</div>
+              <div style={{ fontSize: 15, fontWeight: 700, marginBottom: 8 }}>Something went wrong</div>
+              <div style={{ fontSize: 13, color: '#6b7280' }}>{error}</div>
+            </div>
+          )}
+
+          {/* Payment */}
+          {modalState === 'payment' && order && (
+            <>
+              {/* Status bar */}
+              <div style={{
+                display: 'flex', alignItems: 'center', gap: 9,
+                padding: '9px 13px', borderRadius: 8,
+                background: '#f9fafb', border: '1px solid #e5e7eb',
+                marginBottom: 14, fontSize: 13,
+              }}>
+                <span
+                  className="fl-r-dot-pending"
+                  style={{ width: 8, height: 8, borderRadius: '50%', flexShrink: 0 }}
+                />
+                <span>Awaiting payment…</span>
+                <span style={{
+                  marginLeft: 'auto', fontWeight: 600, fontSize: 13,
+                  color: urgent ? '#ef4444' : '#374151',
+                  fontVariantNumeric: 'tabular-nums',
+                }}>
+                  {timeLeft !== null ? fmtTime(timeLeft) : '--:--'}
+                </span>
+              </div>
+
+              {/* Network warning */}
+              <div style={{
+                background: '#fffbeb', border: '1px solid #fde68a', borderRadius: 8,
+                padding: '9px 13px', fontSize: 12, color: '#92400e',
+                marginBottom: 14, lineHeight: 1.5,
+              }}>
+                <strong>⚠ Important:</strong> Send only <strong>{order.token}</strong> on the{' '}
+                <strong>{order.chainName}</strong> network only. Wrong network = permanent loss.
+              </div>
+
+              {/* QR + info grid */}
+              <div className="fl-r-grid" style={{ display: 'flex', gap: 18, marginBottom: 14 }}>
+                {/* QR side */}
+                <div style={{ flexShrink: 0, display: 'flex', flexDirection: 'column', alignItems: 'center', gap: 6 }}>
+                  <img
+                    src={order.qrUrl}
+                    alt={`Send to ${order.address}`}
+                    width={148}
+                    height={148}
+                    style={{ border: '1px solid #e5e7eb', borderRadius: 10, display: 'block', background: '#f9fafb' }}
+                  />
+                  <p style={{ fontSize: 11, color: '#9ca3af', margin: 0 }}>Scan with wallet</p>
+                </div>
+
+                {/* Info side */}
+                <div style={{ flex: 1, minWidth: 0, display: 'flex', flexDirection: 'column', gap: 13 }}>
+                  {/* Amount */}
+                  <div>
+                    <label style={{ display: 'block', fontSize: 10, fontWeight: 700, color: '#6b7280', textTransform: 'uppercase', letterSpacing: '.06em', marginBottom: 4 }}>
+                      Amount to Send
+                    </label>
+                    <div style={{ fontSize: 22, fontWeight: 700, lineHeight: 1.2 }}>
+                      {order.cryptoAmount
+                        ? `${parseFloat(order.cryptoAmount).toFixed(8).replace(/\.?0+$/, '')} ${order.token}`
+                        : `${order.currency} ${parseFloat(order.amount).toFixed(2)}`}
+                    </div>
+                    {order.cryptoAmount && (
+                      <div style={{ fontSize: 12, color: '#6b7280', marginTop: 2 }}>
+                        ≈ {order.currency} {parseFloat(order.amount).toFixed(2)}
+                      </div>
+                    )}
+                  </div>
+
+                  {/* Address */}
+                  <div>
+                    <label style={{ display: 'block', fontSize: 10, fontWeight: 700, color: '#6b7280', textTransform: 'uppercase', letterSpacing: '.06em', marginBottom: 4 }}>
+                      Deposit Address
+                    </label>
+                    <div style={{ display: 'flex', alignItems: 'flex-start', gap: 7 }}>
+                      <span style={{ fontFamily: 'monospace', fontSize: 12, color: '#374151', wordBreak: 'break-all', flex: 1, lineHeight: 1.5 }}>
+                        {order.address}
+                      </span>
+                      <button
+                        className={`fl-r-cpbtn${copied ? ' fl-r-cpbtn-copied' : ''}`}
+                        onClick={copyAddress}
+                        style={{
+                          flexShrink: 0, background: '#fff', border: '1px solid #d1d5db',
+                          borderRadius: 6, padding: '5px 11px', fontSize: 12,
+                          cursor: 'pointer', color: '#374151',
+                          transition: 'background .12s', whiteSpace: 'nowrap',
+                        }}
+                      >
+                        {copied ? 'Copied!' : 'Copy'}
+                      </button>
+                    </div>
+                  </div>
+
+                  {/* Network badge */}
+                  <div>
+                    <label style={{ display: 'block', fontSize: 10, fontWeight: 700, color: '#6b7280', textTransform: 'uppercase', letterSpacing: '.06em', marginBottom: 4 }}>
+                      Network
+                    </label>
+                    <span style={{ display: 'inline-flex', alignItems: 'center', gap: 5, padding: '3px 10px', background: '#f3f4f6', borderRadius: 100, fontSize: 12, fontWeight: 500, color: '#374151' }}>
+                      <span style={{ width: 7, height: 7, borderRadius: '50%', background: '#10b981', flexShrink: 0 }} />
+                      {order.chainName} · {order.token}
+                    </span>
+                  </div>
+                </div>
+              </div>
+            </>
+          )}
+
+          {/* Success */}
+          {modalState === 'success' && (
+            <div style={{ textAlign: 'center', padding: '30px 16px' }}>
+              <div style={{ fontSize: 52, marginBottom: 14 }}>✅</div>
+              <div style={{ fontSize: 19, fontWeight: 700, color: '#111', marginBottom: 7 }}>Payment Confirmed!</div>
+              <div style={{ fontSize: 13, color: '#6b7280' }}>Your payment has been received.</div>
+            </div>
+          )}
+
+          {/* Expired */}
+          {modalState === 'expired' && (
+            <div style={{ textAlign: 'center', padding: '30px 16px' }}>
+              <div style={{ fontSize: 52, marginBottom: 14 }}>⏳</div>
+              <div style={{ fontSize: 19, fontWeight: 700, color: '#111', marginBottom: 7 }}>Payment Expired</div>
+              <div style={{ fontSize: 13, color: '#6b7280' }}>
+                The payment window has closed. Please start a new payment.
+              </div>
+            </div>
+          )}
+        </div>
+
+        {/* ── Footer ── */}
+        <div style={{ padding: '10px 18px 14px', textAlign: 'center', fontSize: 11, color: '#9ca3af', borderTop: '1px solid #f3f4f6' }}>
+          Secured by{' '}
+          <a href="https://forgelayer.io" target="_blank" rel="noopener noreferrer" style={{ color: '#f7931a', textDecoration: 'none' }}>
+            ForgeLayer
+          </a>
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/index.js

@@ -0,0 +1,3 @@
+export { ForgeLayerButton } from './ForgeLayerButton.jsx';
+export { ForgeLayerModal }  from './ForgeLayerModal.jsx';
+export { useForgeLayerCheckout } from './useForgeLayerCheckout.js';

package/src/useForgeLayerCheckout.js

@@ -0,0 +1,93 @@
+'use strict';
+import { useState, useRef, useCallback, useEffect } from 'react';
+
+/**
+ * Core hook — handles all state and API calls for the checkout flow.
+ *
+ * modalState values:
+ *   'closed' | 'loading' | 'payment' | 'success' | 'expired' | 'error'
+ */
+export function useForgeLayerCheckout({ baseUrl = '/fl', onSuccess, onExpired, onError } = {}) {
+  const [modalState, setModalState] = useState('closed');
+  const [order,      setOrder]      = useState(null);
+  const [timeLeft,   setTimeLeft]   = useState(null);
+  const [error,      setError]      = useState(null);
+
+  const pollRef = useRef(null);
+  const cdRef   = useRef(null);
+
+  const stopTimers = useCallback(() => {
+    if (pollRef.current) { clearInterval(pollRef.current); pollRef.current = null; }
+    if (cdRef.current)   { clearInterval(cdRef.current);   cdRef.current   = null; }
+  }, []);
+
+  // Cleanup on unmount
+  useEffect(() => stopTimers, [stopTimers]);
+
+  const close = useCallback(() => {
+    stopTimers();
+    setModalState('closed');
+    setOrder(null);
+    setTimeLeft(null);
+    setError(null);
+  }, [stopTimers]);
+
+  const startCountdown = useCallback((expiresAt) => {
+    if (cdRef.current) clearInterval(cdRef.current);
+    const tick = () => {
+      const rem = expiresAt - Math.floor(Date.now() / 1000);
+      setTimeLeft(rem <= 0 ? 0 : rem);
+      if (rem <= 0) clearInterval(cdRef.current);
+    };
+    tick();
+    cdRef.current = setInterval(tick, 1000);
+  }, []);
+
+  const startPolling = useCallback((orderData) => {
+    if (pollRef.current) clearInterval(pollRef.current);
+    pollRef.current = setInterval(async () => {
+      try {
+        const res  = await fetch(`${baseUrl}/status?session=${encodeURIComponent(orderData.sessionKey)}`);
+        const data = await res.json();
+        if (!data.ok) return;
+        if (data.status === 'confirmed') {
+          stopTimers();
+          setModalState('success');
+          onSuccess?.(orderData);
+        } else if (data.status === 'expired') {
+          stopTimers();
+          setModalState('expired');
+          onExpired?.();
+        }
+      } catch (_) {}
+    }, 15_000);
+  }, [baseUrl, stopTimers, onSuccess, onExpired]);
+
+  const open = useCallback(async (params) => {
+    stopTimers();
+    setModalState('loading');
+    setOrder(null);
+    setTimeLeft(null);
+    setError(null);
+
+    try {
+      const res  = await fetch(`${baseUrl}/create`, {
+        method:  'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body:    JSON.stringify(params),
+      });
+      const data = await res.json();
+      if (!data.ok) throw new Error(data.error || 'Failed to generate payment address.');
+      setOrder(data);
+      setModalState('payment');
+      startCountdown(data.expiresAt);
+      startPolling(data);
+    } catch (e) {
+      setError(e.message);
+      setModalState('error');
+      onError?.(e);
+    }
+  }, [baseUrl, stopTimers, startCountdown, startPolling, onError]);
+
+  return { modalState, order, timeLeft, error, open, close };
+}