Test mode
Every sandbox tool, so the whole flow is testable without real money.
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 application, no
checks.
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.
Every helper returns 403 test_mode_only for a live key.
Fund a wallet
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 invoice
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"invoice_id is the invoice's lni_ id: id on a minted invoice, or
payment.lightning.id on a quote. The bolt11 and payment_hash are not ids, and
either one is 404 invoice_not_found.
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 resolve
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.
eSIM usage in the sandbox
Nobody uses a sandbox eSIM, so GET /v1/esims/{iccid}/usage simulates it from what was
bought. The oldest plan still within its validity is active with a quarter of its data
used, and any plan topped up after it is queued and untouched. That gives your UI a
partly used plan and a waiting one to render.
Grant yourself credit
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 mode
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.