Quickstart

From a new account to a paid test order, in three API calls.

1

Create your account

Sign up for a free SatsRail merchant account.

Then finish setup in the dashboard: your business details, the agreements and a Lightning Address. Until then every call, with a test key too, answers 403 merchant_not_operational.

Create an account →
2

Get a test key

In your dashboard, go to Settings → API Keys and make a new key: a secret key, with the mode set to Test. The key is shown once. Keep it for the next steps:

export SATSRAIL_KEY=sk_test_...

A secret key (sk_test_…, sk_live_…) stays on your server; a publishable key (pk_…) is safe in a web page and only reads the catalog and opens checkouts. Secret keys end after 90 days (up to a year if you choose), with an email a week before: make the new key, switch, then revoke the old one.

Start with a test key. A test key works on every plan, makes test data only and never reaches a wallet. A live secret key takes real payments and works on the Pro plan.
3

Create your first order

One call makes an order and the Lightning invoice that pays it. Amounts are whole numbers in the smallest unit of your merchant's currency: for a USD merchant, 2500 is $25.00.

curl -X POST https://app.satsrail.com/api/v1/m/orders \
  -H "Authorization: Bearer $SATSRAIL_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1234" \
  -d '{
    "order": {
      "total_amount_cents": 2500,
      "metadata": { "reference": "1234" }
    },
    "generate_invoice": true
  }'

The answer is 201: the order with its invoice (most fields are left out here).

{
  "object": "order",
  "livemode": false,
  "id": "dd1c6bd3-bf9f-48ce-a115-f28132c5ec59",
  "order_number": "ORD-E28180906BFE9D28",
  "total_amount_cents": 2500,
  "total_amount_sats": 25000,
  "status": "invoice_generated",
  "currency": "usd",
  "metadata": { "reference": "1234" },
  "receipt_url": null,
  "invoice": {
    "object": "invoice",
    "livemode": false,
    "id": "313e96c1-57f1-4325-b8b1-ab5d25421079",
    "payment_method": "lightning",
    "amount_sats": 25000,
    "status": "pending",
    "expires_at": "2026-11-16T19:10:29.695Z",
    "order_id": "dd1c6bd3-bf9f-48ce-a115-f28132c5ec59",
    "payment_request": "lntb25000n1test_...",
    "expired": false
  }
}

invoice.payment_request is the string a customer's Lightning wallet pays, shown as a QR code. In test mode it is not a real invoice, and no wallet can pay it. Keep invoice.id for the next step. To sell products from your catalog, send items and leave the total to SatsRail: see Ring up a sale. To find the order again by your own reference, ask for GET /api/v1/m/orders?metadata[reference]=1234.

4

Pay it, in test mode

A test invoice is never paid by itself. One call pays it, exactly as a real payment would:

curl -X POST https://app.satsrail.com/api/v1/m/invoices/INVOICE_ID/simulate_payment \
  -H "Authorization: Bearer $SATSRAIL_KEY"

It works with test keys only: for a live invoice the answer is 403 with the code test_mode_only. POST /api/v1/m/invoices/:id/simulate_expiry makes a test invoice run out instead. More in Testing.

5

Check the payment

This is the call your integration makes while a customer is paying:

curl https://app.satsrail.com/api/v1/m/invoices/INVOICE_ID/status \
  -H "Authorization: Bearer $SATSRAIL_KEY"
{
  "object": "invoice_status",
  "id": "313e96c1-57f1-4325-b8b1-ab5d25421079",
  "order_id": "dd1c6bd3-bf9f-48ce-a115-f28132c5ec59",
  "livemode": false,
  "status": "paid",
  "paid": true,
  "expired": false,
  "wallet_reachable": true,
  "paid_at": "2026-11-16T18:12:30.588Z",
  "expires_at": "2026-11-16T19:10:29.695Z",
  "payment_method": "lightning",
  "amount_sats": 25000,
  "amount_paid_sats": 25000,
  "receipt_url": "https://www.satsrail.com/receipt/dd1c6bd3-bf9f-48ce-a115-f28132c5ec59",
  "payment": {
    "object": "payment",
    "livemode": false,
    "id": "65e9eea2-64e1-4df4-bf5d-367a9f01a8a6",
    "amount_sats": 25000,
    "order": {
      "id": "dd1c6bd3-bf9f-48ce-a115-f28132c5ec59",
      "status": "paid",
      "metadata": { "reference": "1234" }
    }
  }
}

Deliver only when paid is true; before that the call answers "paid": false with no payment. receipt_url is the customer's receipt. If wallet_reachable is false, the wallet couldn't be asked just now: ask again.

6

Listen for webhooks

A webhook posts each event (a payment received, a refund, an order's change) to your server as it happens, so it doesn't have to keep asking: see Webhooks.

7

Go live

Make a key with the mode set to Live (the Pro plan) and use it in place of the test key. The calls are the same; a live invoice comes from your wallet and only a real payment pays it.

Changes to the API

The API's version is in its path: /api/v1. Fields, endpoints and error codes are added to it without a new version. So ignore a field you don't know, and decide what to do from error.code and the HTTP status.