Test mode

A tz_test_ key runs against sandbox providers and testnet rails. Test and live data are fully isolated, and you get test access the moment you sign up — no KYC.

The sandbox would be useless if you had to send real money to exercise it, so Tizon exposes helpers that make things happen. Each one asks the sandbox provider for the signed webhook it would have sent, then runs it through the real ingestion path — so you are testing the code that will run in production, not a shortcut around it.

Fund a walletCopy Anchor Link

Pretend a stablecoin deposit landed at the account's address:

curl https://api.tizon.mobile/v1/test_helpers/deposits \
  -H "Authorization: Bearer $TIZON_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 5000, "asset": "USDT", "network": "base" }'

By default it is confirmed at once and credits the wallet. Pass status: "detected" to leave it in pending_credit instead, then confirm it when you want to test that gap:

curl -X POST \
  https://api.tizon.mobile/v1/test_helpers/deposits/{deposit_id}/confirm \
  -H "Authorization: Bearer $TIZON_KEY"

There is a bank-transfer equivalent at POST /v1/test_helpers/bank_transfers.

Pay a Lightning invoiceCopy Anchor Link

For an invoice minted by POST /v1/wallet/lightning_invoices, or by a quote with payment_source: lightning:

curl -X POST \
  https://api.tizon.mobile/v1/test_helpers/lightning_invoices/{invoice_id}/pay \
  -H "Authorization: Bearer $TIZON_KEY"

The wallet is credited the invoice's USD amount and any quote it was minted for settles, exactly as a real payment would. Only a pending invoice can be paid.

Force an order to resolveCopy Anchor Link

Sandbox fulfillment is quick but not instant. To drive an order to its end state on demand — including the failure path, which is the one most integrations never test:

curl https://api.tizon.mobile/v1/test_helpers/orders/{order_id}/complete \
  -H "Authorization: Bearer $TIZON_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "outcome": "failed" }'

outcome is fulfilled or failed; with failed you may also set failure_reason, which defaults to upstream_declined.

Check that a failed order puts its price back in the wallet and that your code reads failure_reason rather than assuming an eSIM is there.

Grant yourself creditCopy Anchor Link

To exercise overdraft and overdue behaviour without waiting on a commercial approval:

curl https://api.tizon.mobile/v1/test_helpers/credit \
  -H "Authorization: Bearer $TIZON_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "overdraft_limit": { "amount": 50000, "currency": "USD" } }'

See overdraft for what that changes.

Webhooks in test modeCopy Anchor Link

Test endpoints are registered separately from live ones and get their own secret. The URL must still be public HTTPS — localhost and private ranges are refused with 400 invalid_webhook_url, in test mode as well as live — so use a tunnel to receive sandbox events on a laptop. POST /v1/webhook_endpoints/{id}/ping sends a ping event whenever you want one.

The full referenceCopy Anchor Link