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:

  1. Open its checkout_url and go on to the payment step, where the checkout makes the order and its invoice.
  2. Read the session with a test secret key: its invoice_id is set from then on.
  3. Pay that invoice with simulate_payment. The session reads completed, 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 502 or 503, and "wallet_reachable": false show 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.