Testing

Build with confidence using fully isolated test data.

Developer Docs

Test Mode Overview

Every SatsRail merchant gets two sets of API keys: live and test. Keys prefixed with sk_test_ and pk_test_ create resources in a completely isolated test environment.

💡 No special test card numbers needed. Lightning invoices in test mode are fully simulated — they complete automatically so you can test your entire flow without spending real sats.

Test vs. Live Data Isolation

SatsRail enforces strict separation between test and live data:

  Test Mode Live Mode
Key prefix sk_test_ / pk_test_ sk_live_ / pk_live_
Data access Only test resources Only live resources
Payment providers Simulated (no real payments) Real Lightning / Bitcoin
Webhooks Fired for test events only Fired for live events only

This is enforced at the model level via LiveModeScoped — test resources never interact with real payment providers, and a test key can never read or modify live data (and vice versa).

How to Get Test Keys

  1. Log in to your merchant dashboard
  2. Navigate to API Keys
  3. Toggle Test Mode on
  4. Copy your sk_test_ secret key and pk_test_ publishable key

Test keys are available immediately — no approval needed.

What You Can Test

Use test keys to exercise every part of your integration:

  • Checkout Sessions — Create sessions, test embedded/redirect flows, verify success/cancel URLs
  • Orders — Create, list, and retrieve orders; watch status transitions
  • Invoices — Generate invoices and see them auto-complete in test mode
  • Payments — Simulated payments appear with realistic data and status updates
  • Webhooks — Receive webhook events for test resources on your test webhook endpoints

When everything works in test mode, switch to live keys — the API is identical.

Start testing now

Follow the quickstart to get your test keys and make your first API call.

Quickstart Guide →