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

  1. A session is made for an amount or a product. It lasts 15 minutes.
  2. 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_id and invoice_id.
  3. The customer pays from their own wallet, straight to the merchant's. The page sees the payment by itself.
  4. SatsRail records the payment: the invoice and the order become paid, the session completed, and payment.received goes 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

RecordStatuses
Checkout sessionpending → completed (paid), expired or cancelled
Orderpending → invoice_generated → paid, then possibly partially_refunded or refunded; or cancelled or expired unpaid
Invoicepending → 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:

StepShown when
Choose an optionThe product is sold in more than one option (sizes, colors).
Your detailsThe merchant asks for details (email, name, phone, shipping address) and the session carries none.
How to payMore than one way can take the amount: Lightning, on-chain (early access, from its minimum), card, a bank transfer.
PayAlways. A QR code to scan; on a phone, Open in wallet hands the invoice to a wallet app on it.
PaidAlways. In the overlay, "Payment received", then the overlay closes; in a tab, the confirmation page with the receipt.
Your details: the customer's email
How to pay: Lightning or on-chain
Pay: the invoice's QR code

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.