Tizondocs

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

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.

On this page