Embed Widget Flow

Merchant Website Loads

The merchant's HTML page includes a script tag:

<script src="https://satsrail.com/js/pay.js"
  data-product="prod_abc123"
  data-key="pk_live_..."
  data-mode="iframe"></script>

The browser sends a GET request to the SatsRail CDN to fetch the pay.js bundle.

Script Initializes

pay.js reads the data-* attributes from the script tag:

• data-key — validates pk_live_ or pk_test_ prefix format
• data-product — product slug to fetch price from (or data-amount for direct amount)
• data-mode — "iframe", "new_tab", or "redirect" (default: uses merchant setting)

If the API key format is invalid, the script stops and renders an error state.

Button Rendered

The script injects a styled "Pay with Bitcoin ⚡" button into the DOM at the script tag's position. The button class is .satsrail-pay-btn and can be styled with custom CSS.

Customer Clicks Button

pay.js sends a POST request to /api/v1/checkout_sessions with:

The CORS endpoint allows wildcard origins, so this works from any merchant domain.

SatsRail Creates Checkout Session

The API server:

1. Validates the publishable key against the merchant's API tokens
2. Looks up the product — fetches name, description, price (USD)
3. Converts USD price → sats using the real-time BTC/USD exchange rate
4. Creates a CheckoutSession record with a 15-minute expiry
5. Returns checkout_url, token, and expires_at

Rate limiting: API requests are throttled per key. Exceeding limits returns 429 Too Many Requests

Checkout Opens

Based on data-mode:

• iframe: Opens an embedded overlay on the merchant's page (500×700 on desktop, full-screen on mobile). No popup blockers.
• redirect: Navigates the customer's browser to the SatsRail hosted checkout page.

Invoice Generated (Non-Custodial)

SatsRail requests a Lightning invoice from the merchant's connected wallet/node:

• SatsRail sends the sats amount to the merchant's wallet connection
• The merchant's node generates a BOLT-11 invoice
• The invoice is returned to SatsRail and stored in the Invoice record

QR Code Displayed

The checkout page renders:

• Product name and description
• Price in USD and equivalent in sats
• QR code encoding the BOLT-11 invoice
• "Copy Invoice" button for desktop wallets
• 15-minute countdown timer for invoice expiry

WebLN-enabled browsers (e.g., Alby extension) are auto-detected — the wallet prompts to pay without scanning.

Customer Pays

Three payment paths:

• Path A — QR Scan: Customer opens their Lightning wallet app (Phoenix, Muun, etc.), scans the QR code, confirms the amount, and sends payment.
• Path B — Copy & Paste: Customer copies the BOLT-11 string, pastes into a desktop wallet, and confirms.
• Path C — WebLN: Browser extension wallet (Alby) auto-prompts. Customer clicks "Pay" in the extension popup.

Lightning Settlement (Instant)

Payment routes through Lightning Network channels and arrives at the merchant's wallet instantly. SatsRail detects settlement via:

• Primary: PaymentMonitorJob polls the merchant's wallet every 5 seconds
• Secondary: Webhook from the merchant's Lightning node (if configured)

Settlement is final and irreversible — no chargebacks.

Confirmation & Post-Payment

Once confirmed:

1. Transaction logged: timestamp, amount_sats, USD value at payment time, product_id, payment_hash, preimage
2. WebSocket broadcast: Checkout page receives real-time "payment confirmed" event
3. UI updates: Modal/page shows "Payment Confirmed ✓" with transaction details
4. Redirect: Customer sent to success_url (or shown confirmation if no URL configured)
5. Webhook fired: Async POST to merchant's webhook URL with full payment payload