Quickstart
From sign-up to an installable eSIM, on test credentials and without real money.
The goal of this page: an eSIM you could install on a handset, bought with a test key, in a few minutes. No application, no funding, nothing real.
It buys with payment_source: lightning rather than from a wallet balance, because that
is the path that needs no float — the quote mints an invoice for its own price, and
paying it settles the purchase. It is also how you would sell to a real customer at a
real checkout. See selling without a float.
Test keys are issued as soon as you sign up. Live keys unlock once your go-live application is approved — see going live at the end.
Get a test key
Sign up in the dashboard and copy the test key. It
looks like tz_test_…, and it goes in the Authorization header on every request:
export TIZON_KEY="tz_test_..."
curl https://api.tizon.mobile/v1/account \
-H "Authorization: Bearer $TIZON_KEY"The prefix is what selects the mode, so there is no separate sandbox host to remember.
Would rather click than curl? Every request below is also in the
Postman collection: import it and paste the key
into its apiKey variable.
Find an offer
GET /v1/offers is the catalog. Filter it by category and country:
curl -G https://api.tizon.mobile/v1/offers \
-H "Authorization: Bearer $TIZON_KEY" \
-d category=esim \
-d country=JP \
-d limit=5{
"object": "list",
"data": [
{
"id": "off_jp_5gb_30d",
"object": "offer",
"category": "esim",
"name": "Japan 5GB 30 days",
"coverage": { "type": "country", "countries": ["JP"] },
"data": { "amount": 5, "unit": "GB", "unlimited": false },
"validity_days": 30,
"price": { "amount": 1450, "currency": "USD" },
"requires_destination": false,
"status": "active"
}
],
"has_more": false,
"next_cursor": null
}price is the binding amount a quote will debit — $14.50 here, since amounts are
integer cents. Pass display_currency=NGN to get an extra indicative display amount
for presentation; it is never used for settlement.
To build a country picker, GET /v1/countries lists every country with something on
sale, A to Z, with how many offers each has:
curl -G https://api.tizon.mobile/v1/countries \
-H "Authorization: Bearer $TIZON_KEY" \
-d category=esim{
"object": "list",
"data": [
{ "country": "JP", "offer_count": 12 },
{ "country": "US", "offer_count": 8 }
]
}Pass a country back to GET /v1/offers for its offers. A regional bundle covers no
single country, so it is not counted here; it is still in GET /v1/offers, with
coverage: null.
Buy it with a Lightning invoice
The shortest path to a real purchase is to let the quote mint its own invoice, so there is nothing to fund first:
curl https://api.tizon.mobile/v1/quotes \
-H "Authorization: Bearer $TIZON_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"offer_id": "off_jp_5gb_30d",
"payment_source": "lightning"
}'The quote comes back awaiting_funds, and payment.lightning.bolt11 is the whole
instruction — an invoice for exactly this quote's price, which expires and cannot be
reused:
{
"id": "qt_01J9Z8M9S346Q3D25VT4F5V37E",
"object": "quote",
"status": "awaiting_funds",
"offer_id": "off_jp_5gb_30d",
"payment_source": "lightning",
"price": { "amount": 1450, "currency": "USD" },
"payment": {
"rail": "lightning",
"amount": { "amount": 1450, "currency": "USD" },
"asset": null,
"asset_amount": null,
"destinations": [],
"lightning": {
"id": "lni_01J9Z8MB0S2V8Q4X6W3Y5T7R9P",
"bolt11": "lnbc144u1p...",
"payment_hash": "9f2a...",
"amount_sats": 22656,
"expires_at": "2026-10-02T12:05:00Z"
}
},
"expires_at": "2026-10-02T12:07:00Z",
"order_id": null
}The payer sends satoshis; the wallet is credited the USD amount whatever the rate does
in between. amount_sats is indicative only.
The invoice can be paid for five minutes, until payment.lightning.expires_at: that is
the deadline to show your customer, ideally as a countdown. The quote's own expires_at is
two minutes later, so a payment made in the last seconds still settles it, but nothing can
pay the invoice in that time. An expired invoice is never reissued; create a new quote.
Every timestamp is UTC, so convert before showing a clock time.
Every POST that moves money needs an Idempotency-Key. Retrying with the same key
returns the original response instead of buying twice. See
idempotency.
Pay it, without paying it
A test key cannot receive a real Lightning payment, so ask the sandbox to pretend one
arrived. Pay it by the invoice's id, payment.lightning.id on the quote. The bolt11
and payment_hash are not ids, and either one is 404 invoice_not_found:
curl -X POST \
https://api.tizon.mobile/v1/test_helpers/lightning_invoices/lni_01J9Z8MB0S2V8Q4X6W3Y5T7R9P/pay \
-H "Authorization: Bearer $TIZON_KEY"This runs the same ingestion path a real payment would: the wallet is credited, the
quote settles, and an order is created. Test helpers refuse a live key with
403 test_mode_only, so this can never touch real money.
Collect the eSIM
Fulfillment happens in the background. Poll the order, or — better — wait for the
order.fulfilled webhook:
curl https://api.tizon.mobile/v1/orders/{order_id} \
-H "Authorization: Bearer $TIZON_KEY"{
"id": "ord_01J9Z83S3E28JT97KB6CQ643DZ",
"object": "order",
"quote_id": "qt_01J9Z8M9S346Q3D25VT4F5V37E",
"offer_id": "off_jp_5gb_30d",
"status": "fulfilled",
"price": { "amount": 1450, "currency": "USD" },
"deliverable": {
"type": "esim_profile",
"iccid": "8910300000012345678",
"lpa": "LPA:1$smdp.example.com$MBGNW-2IMOY-XAKHK-CPNCJ",
"activation_code": "MBGNW-2IMOY-XAKHK-CPNCJ",
"smdp_address": "smdp.example.com",
"install_links": {
"ios": { "url": "https://esimsetup.apple.com/esim_qrcode_provisioning?carddata=LPA:1$smdp.example.com$MBGNW-2IMOY-XAKHK-CPNCJ", "device": "iPhone or iPad", "requires": "iOS 17.4 or later" },
"android": { "url": "https://esimsetup.android.com/esim_qrcode_provisioning?carddata=LPA:1$smdp.example.com$MBGNW-2IMOY-XAKHK-CPNCJ", "device": "Android phone", "requires": "Android 10 or later with current Google Play services; still rolling out" }
}
},
"failure_reason": null,
"resolved_at": "2026-10-02T11:47:12Z"
}On a phone, install_links gives an install button: ios for an iPhone or iPad, android
for an Android phone, each opening the phone's own install screen with the profile filled
in. On a desktop, render lpa as a QR code to scan instead. activation_code and
smdp_address are the same thing for a customer typing it in by hand. See
installing an eSIM.
If fulfillment fails the order is failed, failure_reason says why, and the price is
already back in the wallet. You are never charged for an eSIM you did not get.
What to build next
Register a webhook
Stop polling: take order.fulfilled as it happens, and verify the signature.
Fund the wallet
Fund once, then every purchase is a single call that cannot wait.
Errors
One error shape, and the codes worth handling by name.
Test mode
Every sandbox tool, including deposits and forced failures.
Going live
Send the go-live form in the dashboard: a few
questions about the business. That is the whole application. Tizon reviews it and emails
you when it is done, and live keys unlock on approval. The dashboard shows the account as
Sandbox only, then In review, then Live, and sandbox keeps working throughout.
The form asks you to turn on two-factor authentication first, because a live key moves real money.
Post-pay and overdraft are a separate approval on top of live; see overdraft.
Switching to live is a change of key, not of code: same base URL, same endpoints.