From 0bb12c20627d46353b412c291b8d6ebb030d928f Mon Sep 17 00:00:00 2001 From: naveenkumar29052006 Date: Tue, 10 Feb 2026 11:49:40 +0530 Subject: [PATCH] docs: add payment flow lifecycle and mermaid diagram #24 --- references/bitcoin-connect/bitcoin-connect.md | 35 +++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/references/bitcoin-connect/bitcoin-connect.md b/references/bitcoin-connect/bitcoin-connect.md index 5da3580..9b22abe 100644 --- a/references/bitcoin-connect/bitcoin-connect.md +++ b/references/bitcoin-connect/bitcoin-connect.md @@ -43,6 +43,41 @@ or - Payment UI for accepting payments via QR code or connected wallet - Supports multiple wallet connectors: Alby Hub, NWC, LNbits, Lightning Node Connect, and more +## Payment Flow Lifecycle + +Understanding the transition between the button states and the payment modal is key to building a great user experience. The process follows a 4-stage flow: + +```mermaid +graph TD + A[1. Start - Idle] -->|User Clicks Button| B[2. Requesting Invoice] + B -->|Invoice Set| C[3. Paying - Modal Opens] + C -->|WebLN Paid / External SetPaid| D[4. Success Screen] + D -->|Done| A +``` + +### 1. Start (Idle) +- The user sees a `` or a custom button. +- The component is in an idle state, waiting for user interaction. + +### 2. Requesting Invoice +- Triggered by the `click` event. +- The application fetches a BOLT-11 invoice (e.g., from your backend or using `@getalby/lightning-tools`). +- **Web Component**: Set the `invoice` attribute on ``. +- **React**: Update the `invoice` prop on `PayButton`. + +### 3. Paying +- The **Payment Modal** launches automatically (via `PayButton`) or programmatically (via `launchPaymentModal`). +- The user chooses a payment method: + - **Extension**: Uses an installed WebLN provider (like Alby). + - **NWC**: Uses Nostr Wallet Connect. + - **Scanner**: Shows a QR code for external wallets. +- If using WebLN, the payment is executed as `provider.sendPayment(invoice)`. + +### 4. Showing Success Screen +- **Automatic**: For WebLN payments, the modal transitions to the success screen automatically. +- **Manual**: For QR code payments, the app must poll for payment status and then call `setPaid()` to show the success screen in the modal. +- **Completion**: The `onPaid` (React) or `bc:onpaid` (Web Components) event fires, providing the `preimage`. + ## Units Unlike NWC, WebLN operates on sats, not millisats. (1000 millisats = 1 satoshi)