Testing
Build and test your integration without money.
Test mode
A key that starts with
sk_test_
or
pk_test_
is a test key. What it makes is test data, kept apart from the merchant's live data, and it never reaches a wallet:
no invoice it makes can be paid with money. You pay a test invoice with simulate_payment, below.
A backend uses a test key from the dashboard (Quickstart, step 2);
a device signs in for test with "mode": "test"
(Sign a cashier in).
The merchant finishes setup in the dashboard first: business details, the agreements and a Lightning Address.
Until then every call, a test key's too, answers 403 merchant_not_operational.
Test and live, side by side
| Test mode | Live mode | |
|---|---|---|
| Key prefix | sk_test_ / pk_test_ |
sk_live_ / pk_live_ |
| Plan | Every plan | Secret keys work on the Pro plan |
| Orders, invoices, payments | Test ones only: "livemode": false |
Live ones only: "livemode": true |
| Invoice | Made by no wallet; lasts an hour | A real Lightning invoice from the merchant's wallet |
| How it is paid | simulate_payment |
The customer's wallet |
| Emails | To the person who holds the key that made the order, never to its customer_email |
To the customer |
| Webhooks | Test events, to test endpoints only | Live events, to live endpoints only |
| On-chain | No test mode | Where the merchant has it |
A key finds the orders, invoices and payments of its own mode only: a test key asking for a live order's id gets
404, and a live key the same for a test one. What keeps a merchant from taking a live payment
(its plan's monthly limit, a verification still pending) does not hold back a test one.
Pay a test invoice
Make an order with an invoice, then pay the invoice by its id:
curl -X POST https://app.satsrail.com/api/v1/m/orders \
-H "Authorization: Bearer $SATSRAIL_KEY" \
-H "Content-Type: application/json" \
-d '{ "order": { "total_amount_cents": 2500 }, "generate_invoice": true }'
curl -X POST https://app.satsrail.com/api/v1/m/invoices/INVOICE_ID/simulate_payment \
-H "Authorization: Bearer $SATSRAIL_KEY"
The answer is what GET /api/v1/m/invoices/:id/status gives for a paid invoice: "paid": true,
with the payment and its order, now paid with a receipt_url. payment.received goes to your test
webhook endpoints. Calling it twice pays nothing twice.
| Status | Code | What it means |
|---|---|---|
| 403 | test_mode_only |
The invoice is a live one. Only a real payment pays it. |
| 403 | forbidden |
The key may read invoices but not manage them. |
| 404 | not_found |
No such invoice in the key's mode. |
| 422 | invoice_not_payable |
The invoice ran out. Ask for a new one for its order with POST /api/v1/m/invoices/generate, and pay that. |
Make a test invoice run out
A test invoice lasts an hour. To try what your integration does when a customer takes too long, end it now:
curl -X POST https://app.satsrail.com/api/v1/m/invoices/INVOICE_ID/simulate_expiry \
-H "Authorization: Bearer $SATSRAIL_KEY"
{
"object": "invoice_status",
"id": "fb31556a-a2c0-406b-99ca-f65958711346",
"order_id": "e8da24c6-dca4-4da7-8d29-aa6e1e174c05",
"livemode": false,
"status": "expired",
"paid": false,
"expired": true,
"wallet_reachable": true,
"paid_at": null,
"expires_at": "2026-11-16T19:11:18.995Z",
"payment_method": "lightning",
"amount_sats": 9720,
"amount_paid_sats": null,
"receipt_url": null
}
Then ask for the order's next invoice as you would in live mode
(When the invoice runs out), and pay that one: a new test invoice has
another hour. For a live invoice, simulate_expiry answers 403 with the code
test_mode_only.
Test a hosted checkout
A checkout session takes the mode of the key that makes it: one made with an sk_test_ key, or by
pay.js with a pk_test_ key, is a test session ("livemode": false), and its order and
invoice are test ones. To pay one:
- Open its
checkout_urland go on to the payment step, where the checkout makes the order and its invoice. - Read the session with a test secret key: its
invoice_idis set from then on. - Pay that invoice with
simulate_payment. The session readscompleted, and the open checkout page shows its confirmation.
Making a session and reading it are on Hosted checkout.
What test mode covers
Everything an integration does with orders, invoices, payment requests, checkout sessions (the hosted checkout and pay.js), payments and webhooks: an endpoint made with a test key (POST /api/v1/m/webhooks) receives test events. An endpoint made on the dashboard's Webhooks page is a live one.
What it leaves out, to check once in live mode with a small payment:
- The wallet. No test invoice comes from it, so a wallet that is offline or set up wrongly, a provider's
502or503, and"wallet_reachable": falseshow only in live mode. Write those paths from their answers and description. - The store's catalog. A test secret key reads only test products made with a test key; a POS device's test key reads the store's real catalog.
- The business's own records. A test key reads no wallets, verification documents or other keys' usage (
403 live_key_required). - Unlocking live content. A test purchase unlocks test products and media keys only.