Checkout Sessions

Overview

A CheckoutSession creates a hosted payment page where your customer can pay with Bitcoin Lightning. You embed the checkout on your page (or open a new tab), and SatsRail handles the rest.

Token format	`cs_*`
Expiry	15 minutes from creation
Statuses	`pending` → `completed` / `expired` / `cancelled`

Parameters

Parameter	Type	Description
`amount_cents`	integer, required	Amount in cents (e.g. 5000 = $50.00)
`currency`	string	Currency code, default `"usd"`
`success_url`	string, required	URL to redirect to after successful payment
`cancel_url`	string, required	URL to redirect to if customer cancels
`customer_email`	string	Pre-fill customer email. Skips the info collection form on the hosted checkout page.
`customer_name`	string	Pre-fill customer name.
`customer_phone`	string	Pre-fill customer phone number.
`customer_address`	string	Pre-fill customer shipping address.
`metadata`	object	Arbitrary key-value pairs (max 50 keys). Attached to the session and propagated to the order.

Create a Checkout Session

POST /api/v1/checkout_sessions with a Bearer token (secret key or publishable key).

💡 Publishable keys (pk_live_ / pk_test_) can only create checkout sessions. They cannot access any other API endpoint.

curl

curl -X POST https://satsrail.com/api/v1/checkout_sessions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "checkout_session": {
      "amount_cents": 5000,
      "currency": "usd",
      "success_url": "https://yoursite.com/success",
      "cancel_url": "https://yoursite.com/cancel",
      "customer_email": "buyer@example.com",
      "customer_name": "Alice Smith",
      "metadata": { "order_ref": "MY-123" }
    }
  }'

Node.js

const session = await sr.checkoutSessions.create({
  amount_cents: 5000,
  currency: 'usd',
  success_url: 'https://yoursite.com/success',
  cancel_url: 'https://yoursite.com/cancel',
  customer_email: 'buyer@example.com',  // optional
  customer_name: 'Alice Smith',          // optional
  metadata: { order_ref: 'MY-123' }      // optional
});
// Redirect customer to session.checkout_url

Python

session = sr.checkout_sessions.create(
    amount_cents=5000,
    currency="usd",
    success_url="https://yoursite.com/success",
    cancel_url="https://yoursite.com/cancel",
    customer_email="buyer@example.com",  # optional
    customer_name="Alice Smith",          # optional
    metadata={"order_ref": "MY-123"}      # optional
)
# Redirect customer to session.checkout_url

Ruby

session = SatsRail::CheckoutSession.create(
  amount_cents: 5000,
  currency: "usd",
  success_url: "https://yoursite.com/success",
  cancel_url: "https://yoursite.com/cancel",
  customer_email: "buyer@example.com",  # optional
  customer_name: "Alice Smith",          # optional
  metadata: { order_ref: "MY-123" }      # optional
)
# Redirect customer to session.checkout_url

Redirect vs. Popup Mode

Redirect Mode

Redirect the customer's browser to the checkout URL. After payment (or cancellation), SatsRail redirects them back to your success_url or cancel_url.

Embedded Mode

Checkout opens in an overlay iframe on your page. No popup blockers, works on desktop and mobile. When payment completes, the overlay closes automatically.

The Embed Button uses embedded mode by default.

Developer Docs