Selling without a float
No prefunding. The quote carries its own payment instruction, so your customer pays at the point of sale.
The wallet is not a prerequisite. Quote with a payment rail instead of wallet and the
quote waits in awaiting_funds, carrying everything needed to pay it. This is the model
for a partner who takes money from a customer at the moment of sale and has nothing
sitting in a float.
Lightning: an invoice per purchase
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" }'payment.lightning.bolt11 is the whole instruction — an invoice for exactly this quote's
price, minted for this quote alone, which expires and cannot be reused. Render it as a QR
code and let the customer pay.
{
"status": "awaiting_funds",
"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
}Paying it credits the wallet in USD and settles the quote in one move, so no funding step
is needed. The payer sends satoshis; you are credited the USD amount whatever the rate
does in between.
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.
Stablecoins and bank transfer
A usdt or usdc quote names the network your customer will send on:
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": "usdt", "network": "trc20" }'USDT is accepted on bep20, base and trc20; USDC on base and bep20. Ask your
customer which one their wallet sends on. Never default it for them: a stablecoin sent on
the wrong network is lost.
payment.destinations then holds the account's standing address on that network —
the same address funding returns, not a per-quote one. With
bank_transfer, it holds the bank account and network is not sent.
{
"payment": {
"rail": "usdt",
"amount": { "amount": 1450, "currency": "USD" },
"asset": "USDT",
"network": "trc20",
"asset_amount": "14.50",
"destinations": [
{
"type": "crypto_address",
"asset": "USDT",
"network": "trc20",
"address": "TQ5r8nKc2v1yH3mJ7pXa9eWd4sLb6uFz2N",
"memo": null,
"status": "active"
}
],
"lightning": null
}
}Read rail to know which fields matter: on Lightning, destinations is empty and the
invoice is everything; on a stablecoin, send asset_amount of asset on network to
the address; on a bank transfer, send amount to the account.
An address the account has never used may come back with address: null and
status: "pending" while it is being created. Poll the quote until it is active.
| Error | Means |
|---|---|
400 missing_network | A usdt or usdc quote without network. |
400 unsupported_network | That asset is not accepted on that network. |
400 invalid_request | network sent with wallet, lightning or bank_transfer. |
Because the destinations are standing, what arrives is credited to the wallet, not to the quote. There is no per-quote address to match a payment against.
When a rail or the catalog is down
Nothing is created or charged, and the error says which:
| Error | Means | What to do |
|---|---|---|
502 rail_unavailable | No address or invoice could be made right now. | Retry shortly, or offer another payment_source. |
502 fulfillment_unavailable | The offer could not be priced right now. | Retry shortly. |
How waiting quotes get paid
Every payment credits the wallet, and waiting quotes are then paid from the balance. The matching rule is deliberate and worth knowing:
- The quote priced exactly at what arrived goes first.
- Then the oldest quote that the balance can cover.
A quote is never paid at the moment you create it, even when the wallet already holds
enough: it always comes back awaiting_funds with somewhere to pay. To spend what is
already in the wallet, quote with payment_source: wallet.
Waiting quotes are paid from the balance only — never from an overdraft. An overdraft
is for payment_source: wallet.
Expiry
An unpaid quote expires at expires_at and becomes expired. Money that arrives after
that stays in the wallet; it is not lost, and it will pay the next thing that fits.
A Lightning quote's expires_at is two minutes after its invoice's, as
above; the other rails wait longer, for money sent
to a standing destination.
You can stop one early:
curl -X POST https://api.tizon.mobile/v1/quotes/{quote_id}/cancel \
-H "Authorization: Bearer $TIZON_KEY"Only awaiting_funds ever changes state. fulfilled, expired and cancelled are
final.
What to listen for
| Event | Means |
|---|---|
quote.awaiting_funds | The quote is waiting; the payment instruction is live. |
wallet.credited | Money arrived. A quote may settle on the back of it. |
quote.fulfilled | Paid and handed to fulfillment. An order now exists. |
quote.expired | Nobody paid in time. |
order.fulfilled | The eSIM or top-up is ready — read deliverable. |
Take order.fulfilled as the signal to hand something to your customer, not
quote.fulfilled: a fulfilled quote means paid, while the order carries the delivery
outcome.
Testing the whole flow
# Quote with lightning, then pretend the customer paid it, by payment.lightning.id:
curl -X POST \
https://api.tizon.mobile/v1/test_helpers/lightning_invoices/{invoice_id}/pay \
-H "Authorization: Bearer $TIZON_KEY"