Pay Link Checkout Flow
When a customer opens a pay link, they do not immediately see a Bitcoin QR code. There are two distinct steps.
Step 1 — Order review page
The customer first sees a Coinsnap-hosted page showing the prefilled order details:
- Who the payment is for (the
titleyou set — customer name or order label) - The order amount and currency
- The description
- A "Pay with Bitcoin" button
The Bitcoin exchange rate is not locked yet at this point. This protects both parties — the rate is only set when the customer actively starts the payment.
Step 2 — Bitcoin payment page
When the customer clicks "Pay with Bitcoin", Coinsnap:
- Converts the fiat amount to Bitcoin at the current market rate
- Generates a Bitcoin invoice (15-minute payment window)
- Shows both a Lightning QR code (instant, recommended) and a Bitcoin QR code (fallback)
The customer scans the QR code with any Bitcoin or Lightning wallet.
What happens if the invoice expires
If the customer doesn't pay within 15 minutes, the Bitcoin invoice expires. The exchange rate and QR code become invalid.
The pay link itself remains valid. The customer can close the tab, come back later, reopen the same pay link, and a fresh Bitcoin invoice is generated at the new exchange rate.
This is the key difference from a standard invoice integration: a pay link survives expired payment attempts. The customer doesn't need to go back to your site to start again.
After payment is confirmed
- The Coinsnap payment page shows a success message
- If you set a
redirectUrl, the customer is sent there - Coinsnap sends a
Settledwebhook to your server
Do not use the redirect as payment confirmation. The redirect is a UX convenience — it can arrive before the payment is fully confirmed, or be bypassed entirely. Always rely on the webhook.
Lightning vs Bitcoin
| Lightning | On-chain | |
|---|---|---|
| Confirmation | Instant (1–3 seconds) | ~10 minutes (1 block) |
| Fees | Near-zero | Variable |
| Recommended for | All eCommerce payments | Large amounts |
For most eCommerce scenarios, the customer will use Lightning. Your webhook handler doesn't need to distinguish between them — you receive the same Settled event either way.