Hosted checkout
SatsRail's payment page, from a session to a paid order.
Ways in
Three ways in, one checkout page.
The API. Create a session from your server and send the customer to its checkout_url.
Send an amount, or a product_id to charge the product's price and taxes:
curl -X POST https://app.satsrail.com/api/v1/m/checkout_sessions \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"checkout_session": {
"amount_cents": 2500,
"customer_email": "buyer@example.com",
"metadata": { "order_ref": "ORD-42" }
}
}'
A payment link. Every active product has one, its payment_link_url
(https://www.satsrail.com/pay/prod_abc123def456); a test-mode product has none. Each visit starts its own session,
so one link takes any number of payments. No code: share it by email, chat or QR code.
The embed button. pay.js and a publishable key open the checkout from any web page. See
Embed button.
What happens
- A session is made for an amount or a product. It lasts 15 minutes.
- The customer reaches the payment step. SatsRail makes the order, prices it in sats at the current rate, and makes its invoice: a Lightning invoice from the merchant's wallet, or an on-chain address. From then on the session carries
order_idandinvoice_id. - The customer pays from their own wallet, straight to the merchant's. The page sees the payment by itself.
- SatsRail records the payment: the invoice and the order become
paid, the sessioncompleted, andpayment.receivedgoes to your webhook endpoints.
A Lightning invoice's own expiry is set by the merchant's wallet provider. If it runs out while the session is still
open, opening the checkout again gets a new invoice for the same order. A session left unpaid reads expired:
make a new one.
Statuses
| Record | Statuses |
|---|---|
| Checkout session | pending → completed (paid), expired or cancelled |
| Order | pending → invoice_generated → paid, then possibly partially_refunded or refunded; or cancelled or expired unpaid |
| Invoice | pending → paid, expired or cancelled |
Knowing it was paid
Deliver on the payment.received webhook, after checking its signature and that data.order_total_amount_cents is what you meant to charge: see Webhooks. To ask instead, read the session:
curl https://app.satsrail.com/api/v1/m/checkout_sessions/SESSION_ID \
-H "Authorization: Bearer $SATSRAIL_KEY"
The answer is wrapped in data: data.status is completed once paid. Never deliver because the customer came back to your page; the webhook or the session's status is the proof. There is no URL to send the customer back to: after paying they see SatsRail's confirmation.
Bitcoin conversion fee
A merchant can add a fee of up to 3% to bitcoin payments, to cover selling the sats. The price
(amount_cents, total_amount_cents) doesn't change: the fee is on top, and the
invoice is priced at amount_due_cents. The hosted checkout shows it as its own line. When the
fee isn't zero these fields are added, so your own screen can show it too:
"total_amount_cents": 10000,
"conversion_fee_percent": 1.5,
"conversion_fee_cents": 150,
"amount_due_cents": 10150,
"total_amount_sats": 101500
On orders, invoices, payment requests, checkout sessions and the order in webhook payloads; absent when the
fee is zero and on cash orders. GET /api/v1/m/merchant returns the merchant's
conversion_fee_percent.
What the customer sees
In pay.js's overlay the checkout fills the frame; in a page of its own (a payment link, a
checkout_url) it is one card. Each step shows only when it is needed:
| Step | Shown when |
|---|---|
| Choose an option | The product is sold in more than one option (sizes, colors). |
| Your details | The merchant asks for details (email, name, phone, shipping address) and the session carries none. |
| How to pay | More than one way can take the amount: Lightning, on-chain (early access, from its minimum), card, a bank transfer. |
| Pay | Always. A QR code to scan; on a phone, Open in wallet hands the invoice to a wallet app on it. |
| Paid | Always. In the overlay, "Payment received", then the overlay closes; in a tab, the confirmation page with the receipt. |
Creating a session answers checkout_theme (light or dark) and
checkout_accent_color (#rrggbb), the merchant's choices for the checkout, so your page can match.