Checkout Experience
What your customers see at each step of the payment flow.
Two Display Modes
SatsRail checkout pages adapt their layout based on your merchant's checkout mode setting. Each mode is designed for its context:
Embedded Mode
Opens in an overlay on the merchant's page
Compact, space-efficient layout. No popup blockers. Works on desktop and mobile.
New Tab Mode
Opens in a full browser tab
Two-column layout with product info on the left and payment details on the right.
data-mode
attribute.
Your Brand
Merchants choose three things in Checkout Settings → Appearance, with a live preview: a light or dark theme, one accent color, and the logo uploaded in General settings. The accent colors the main button and small highlights, and text on it switches between white and black so it stays readable. A color that would disappear against the chosen theme is refused when saving.
Everything else is the same for every merchant: the layout, the QR code (always black on white, so every wallet can read it), the amount and fee lines, the paid and expired colors, and "Powered by SatsRail".
Creating a checkout session returns checkout_theme (light or
dark) and checkout_accent_color (a #rrggbb hex, SatsRail gold
unless the merchant chose one), so your own page can match the checkout it opens.
Embedded Mode
Compact checkout embedded in an overlay iframe on the merchant's page.
Customer Info
Collects email, name, phone, or address based on merchant settings.
Payment Method
Shown when the merchant offers both Lightning and on-chain (early access) and the amount reaches the on-chain minimum. Otherwise this step is skipped.
QR Code
On a computer, scan the QR code with any Lightning or Bitcoin wallet. On a phone, Open in wallet comes first and hands the invoice to the wallet app on that phone. Real-time status via WebSocket.
Confirmed
Payment received. Customer is auto-redirected to your success URL.
New Tab Mode
Spacious two-column layout for the full browser experience.
Customer Info
Amount displayed on the left, form fields on the right.
Payment Method
Price on the left, payment method options on the right. Shown when both Lightning and on-chain (early access) are offered; otherwise this step is skipped.
QR Code
Amount and invoice details on the left, large QR code on the right.
Confirmed
Wider confirmation card with order details and email receipt notice.
Steps Are Adaptive
Not every checkout has all four steps. The flow adapts automatically:
| Step | When It Appears | When It's Skipped |
|---|---|---|
| 1. Customer Info | Merchant has customer fields configured (email, name, phone, address) | No customer fields configured, or info pre-filled via API |
| 2. Payment Method | The merchant offers both Lightning and on-chain (early access) and the amount reaches the on-chain minimum | Only one method can take the payment (an on-chain-only checkout goes straight to its screen), or the method is pre-selected via API |
| 3. QR Code | Always | Never skipped |
| 4. Confirmation | Always | Never skipped |
Try it yourself
See the checkout in action on our demo site, or integrate it into your own.