Tizondocs
Guides

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.

ErrorMeans
400 missing_networkA usdt or usdc quote without network.
400 unsupported_networkThat asset is not accepted on that network.
400 invalid_requestnetwork 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:

ErrorMeansWhat to do
502 rail_unavailableNo address or invoice could be made right now.Retry shortly, or offer another payment_source.
502 fulfillment_unavailableThe 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:

  1. The quote priced exactly at what arrived goes first.
  2. 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

EventMeans
quote.awaiting_fundsThe quote is waiting; the payment instruction is live.
wallet.creditedMoney arrived. A quote may settle on the back of it.
quote.fulfilledPaid and handed to fulfillment. An order now exists.
quote.expiredNobody paid in time.
order.fulfilledThe 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"

On this page