Quickstart
From a new account to a paid test order, in three API calls.
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.
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.
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.
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.
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.
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.
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.