Sandbox & live mode
Every account has at least two tenants: a sandbox for development and a live tenant for production. They are completely isolated — separate data, separate keys, separate webhook endpoints, separate logs.
Pick the right base URL
| Environment | Base URL |
|---|---|
| Sandbox | https://api.sandbox.paylera.io |
| Live | https://api.paylera.io |
Each tenant’s API keys are prefixed so you can spot them at a glance:
| Prefix | Where it works |
|---|---|
sk_sandbox_… | Sandbox base URL only |
sk_live_… | Live base URL only |
Sending a sandbox key to the live URL (or vice-versa) returns
401 Unauthorized with problem: auth.wrong_environment.
What’s the same
- Every endpoint, every field, every event type.
- Idempotency, rate limits, error envelopes, versioning.
- Webhook signing and delivery semantics.
- Object IDs are interchangeable in shape (UUID v7).
If your code works in sandbox, it will work in live.
What’s different
- Payment provider — sandbox uses Paylera’s hosted test provider with the deterministic tokens listed below. Live uses the providers you’ve configured (Stripe, PayPal, Adyen).
- Tax engine — sandbox computes tax with a test ruleset that always charges 8% for any address. Live uses your configured tax provider (Stripe Tax, Avalara, TaxJar).
- Email & PDF delivery — sandbox emails are captured and shown in the dashboard; nothing is sent. PDFs render normally.
- Rate limits — sandbox limits are 1/10th of live; enough to develop and test, not enough to load-test. See Rate limits.
Test card tokens (sandbox)
| Token | Behaviour |
|---|---|
tok_visa_success | Charges immediately succeed. |
tok_visa_3ds | First charge requires payment.requires_action; second succeeds. |
tok_visa_decline | All charges return card_declined. |
tok_visa_insufficient_funds | All charges return insufficient_funds. |
tok_visa_chargeback | Charge succeeds, then a payment.charged_back event fires after 60 s. |
tok_visa_dispute_won | Charge succeeds, then chargeback then dispute won (90 s). |
tok_amex_success | Same as tok_visa_success but with Amex BIN data. |
tok_card_expired_2099 | A card that “expired” in 2099 — useful for SCA flows. |
To exercise specific decline codes, append a suffix:
tok_visa_decline?reason=stolen_card. The available reasons match the
provider’s standard set.
Test webhook receiver
The sandbox dashboard ships with a built-in Webhook tester: a hosted endpoint you can register against any sandbox tenant. Events sent to it are shown in the UI within seconds, with the raw envelope, the signature header, and the verification result. Useful when you don’t have a tunnel handy.
For local development with a tunnel, see Local testing.
Promoting from sandbox to live
There is no automatic data copy. Sandbox is for testing — your live catalog should be created against the live tenant. The recommended path:
- Build and verify everything in sandbox.
- Use the Catalog export in the sandbox dashboard to download your products and plans as JSON.
- Re-import them against the live tenant using
POST /v1/admin/catalog/import(also exposed in the live dashboard). - Generate live API keys, swap the base URL and the keys, and run your smoke tests.
- Step through the Going live checklist.