Sandbox Routing

Zyntem uses a Stripe-like test/live mode to route transactions to sandbox or production tax authority endpoints. For the Cloud API, the mode is determined per request by your API key prefix. For Embedded Local SDKs, you set the environment at initialization time. Both paths use the same zyn_test_ / zyn_live_ key distinction.

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, Zyntem 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

Embedded Local SDKs

The Embedded Local SDKs use the same test/live key distinction, but environment routing is configured at initialization rather than per-request. Set the environment field to "sandbox" or "production" in your config, and pass the matching API key.

Configuration

Field	Value	Effect
environment	"sandbox"	Routes to sandbox tax authority endpoints
environment	"production"	Routes to production tax authority endpoints
api_key	zyn_test_*	Must match "sandbox" environment
api_key	zyn_live_*	Must match "production" environment

The SDK rejects mismatched combinations (e.g. a zyn_test_* key with "production" environment) at init time.

Python

import zyntem_fiscal

# Sandbox mode -- uses test endpoints
zyntem_fiscal.init_with_config({
    "country": "ES",
    "tax_id": "B12345678",
    "environment": "sandbox",
    "api_key": "zyn_test_abc123",
})

# Switch to production -- change environment and key
zyntem_fiscal.init_with_config({
    "country": "ES",
    "tax_id": "B12345678",
    "environment": "production",
    "api_key": "zyn_live_abc123",
})

.NET

using Zyntem.Fiscalization;

// Sandbox mode
FiscalEngine.InitWithConfig(@"{
    ""country"": ""ES"",
    ""tax_id"": ""B12345678"",
    ""environment"": ""sandbox"",
    ""api_key"": ""zyn_test_abc123""
}");

// Production mode
FiscalEngine.InitWithConfig(@"{
    ""country"": ""ES"",
    ""tax_id"": ""B12345678"",
    ""environment"": ""production"",
    ""api_key"": ""zyn_live_abc123""
}");

YAML config file

You can also set the environment in a YAML config file:

# fiscalization.yaml
country: ES
tax_id: B12345678
environment: sandbox
api_key: zyn_test_abc123

Switch to production by changing environment and api_key:

environment: production
api_key: zyn_live_abc123

Or override via environment variables without changing the file:

export ZYNTEM_ENVIRONMENT=production
export ZYNTEM_API_KEY=zyn_live_abc123

See the Configuration Reference for the full list of fields and environment variable overrides.

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)
5. Embedded: use environment variables for production -- keep "sandbox" in your config file and override with ZYNTEM_ENVIRONMENT=production in production deployments