Sandbox Routing

FiscalAPI uses a Stripe-like test/live mode to route transactions to sandbox or production tax authority endpoints. The mode is determined per request by your API key prefix.

How it works

API Key Prefix	Environment	Tax Authority Endpoint
zyn_test_	test	Sandbox (test) endpoints
zyn_live_	live	Production endpoints

Every API request is routed based on the key used to authenticate it. There is no global configuration toggle -- you can send test and live requests simultaneously using different keys.

Test mode

Test mode (zyn_test_ keys) routes all fiscalization to sandbox tax authority endpoints. Use this for development and testing:

# This transaction goes to the sandbox tax authority
curl -X POST https://api.zyntem.dev/v1/transactions \
  -H "Authorization: Bearer zyn_test_abc123def456..." \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Transactions created with test keys have "environment": "test" in the response.

Live mode

Live mode (zyn_live_ keys) routes to production tax authority endpoints. Live mode requires the FISCALIZATION_LIVE_ENABLED environment variable to be set on the server.

# This transaction goes to the production tax authority
curl -X POST https://api.zyntem.dev/v1/transactions \
  -H "Authorization: Bearer zyn_live_abc123def456..." \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Live mode guard

If live mode is not enabled on the server, requests with zyn_live_ keys return:

HTTP/1.1 403 Forbidden

{
  "error": "live mode is not enabled"
}

This prevents accidental production submissions in development environments.

Environment field

Every transaction includes an environment field indicating whether it was processed in test or live mode:

{
  "id": "a1b2c3d4-...",
  "status": "success",
  "environment": "test",
  ...
}

Use this field to distinguish test data from production data in your systems.

Per-request routing

Unlike systems that use a global configuration toggle, FiscalAPI determines the environment per request based on the API key. This means:

• You can run integration tests against the real API using zyn_test_ keys without affecting production data
• Switching to production is as simple as changing which API key you use
• No server-side configuration changes needed for your application to go live
• Test and live transactions are isolated at the data layer

Best practices

1. Use test keys in development -- all zyn_test_ requests hit sandbox endpoints at no cost
2. Never hardcode live keys -- use environment variables to switch between test and live
3. Verify with test mode first -- ensure your integration works end-to-end before switching to live keys
4. Monitor the environment field -- alert if test transactions appear in production systems (or vice versa)