openapi: 3.1.1
info:
  title: Tizon Mobile API
  version: 0.4.0
  summary: eSIMs and mobile top-ups, paid from a closed-loop USD wallet.
  description: |
    Tizon Mobile is a B2B API for selling eSIMs and mobile top-ups. Every account has a
    closed-loop USD wallet: funding credits it, purchases debit it, and nothing else
    moves the balance. There are no withdrawals, and the balance is spendable only on
    products.

    This specification implements the Tizon Mobile API design v0.4 and is the contract
    for generated SDKs and the published reference.

    ## Money

    Settlement amounts are integer minor units of the settlement currency (USD cents)
    plus a currency code: `{ "amount": 1450, "currency": "USD" }` is $14.50. Amounts in
    another currency appear only as indicative `display` values for presentation and are
    never used for settlement.

    ## Test and live

    The API key selects the mode: `tz_test_…` or `tz_live_…`. Test and live data are
    fully isolated, including wallets, ledgers, provider credentials and webhook
    secrets.

    ## Idempotency

    Every `POST` that moves money requires an `Idempotency-Key`. Retrying with the same
    key returns the original response, marked `Idempotent-Replayed: true`, instead of
    repeating the effect. Reusing a key for a different request is rejected with
    `409 idempotency_key_reuse_mismatch`. A request that failed without effect (for
    example `402 insufficient_funds`) records nothing, so it may be retried with the
    same key once the problem is fixed.

    ## Webhooks

    Register an endpoint with `POST /v1/webhook_endpoints` and keep the `secret` it
    returns. Every delivery is a `POST` of an `Event` envelope, with
    `Tizon-Signature: t=<unix seconds>,v1=<hex hmac>`, where the signed material is
    `"<t>.<raw request body>"` under HMAC-SHA256 with your secret. Reject a delivery
    whose signature does not match, or whose `t` is more than five minutes old.

    Delivery is at-least-once, so the same `id` may arrive twice: dedupe on it. Order
    is not guaranteed; treat the resource's own `status` as the truth and fetch it if
    you need certainty. Answer `2xx` within ten seconds. Anything else is retried with
    backoff for about a day, after which the delivery is dead-lettered, and an endpoint
    that keeps failing is disabled.

    ## Errors

    Every error response is `{ "error": { "type", "code", "message", "request_id" } }`,
    with extra fields on some codes (`insufficient_funds` carries `shortfall`). The
    `type` is a stable category; `code` is the specific reason.

    ## Pagination

    Collections are cursor-paginated: pass `limit` (max 100) and `cursor`. A page is
    `{ "object": "list", "data": [...], "has_more": true, "next_cursor": "..." }`.

    ## Request ids

    Every response carries a `Request-Id` header, which also appears as `request_id` in
    error bodies. Quote it when reporting a problem.
servers:
  - url: https://api.tizon.mobile
    description: Production. Mode comes from the API key, not the URL.
security:
  - ApiKey: []
tags:
  - name: Offers
    description: |
      The catalog: eSIM plans and mobile top-ups, each with the price your wallet will
      be debited. Prices are USD; ask for a `display_currency` to show an indicative
      local amount alongside.
  - name: Wallet
    description: |
      The account's closed-loop USD balance: what it holds, what it can spend, and
      every movement. Funding credits it, purchases debit it, nothing else moves it.
  - name: Account
    description: |
      The account an API key belongs to, and its credit terms: how far below zero the
      wallet may go, and for how long.
  - name: Quotes
    description: |
      A quote prices an offer and pays for it. Paying from the wallet debits it
      immediately and creates an order, which is fulfilled in the background. Paying
      with stablecoins or a bank transfer returns where to send the money, and the
      quote waits in `awaiting_funds` until a payment lets the wallet cover it, even
      when the wallet already holds enough.
  - name: Orders
    description: The fulfillment of a paid quote, and its eSIM or top-up receipt.
  - name: Test helpers
    description: |
      Sandbox tools that make things happen without real money. Test keys only; a live
      key gets `403 test_mode_only`. Each one asks the sandbox provider for the signed
      webhook it would have sent and runs it through the real ingestion path.
  - name: Webhooks
    description: |
      Endpoints Tizon delivers events to. Register a URL, keep the secret it returns,
      and verify the `Tizon-Signature` header on every delivery.
  - name: Revenue
    description: |
      A partner's Revenue Centre: what they have earned on the orders they brought,
      and turning it into credit they can spend.
paths:
  /v1/offers:
    get:
      operationId: listOffers
      summary: List offers
      description: |
        The offers this key's mode can buy, paged. Filter by `category` and `country`.
        Prices already include Tizon's margin: `price` is what a quote will debit.

        An offer the provider has stopped selling is left out of this list, but can
        still be retrieved, so an old order can be explained.
      tags:
        - Offers
      parameters:
        - name: category
          in: query
          required: false
          schema:
            type: string
            enum:
              - esim
              - mobile_topup
        - name: country
          in: query
          required: false
          description: ISO 3166-1 alpha-2, case-insensitive.
          schema:
            type: string
            pattern: ^[A-Za-z]{2}$
            examples:
              - JP
        - name: display_currency
          in: query
          required: false
          description: |
            Adds an indicative `display` amount in this currency to every offer.
            Presentation only, never a settlement amount. `USD` adds nothing, since
            `price` is already USD. A currency with no rate is
            `400 unsupported_display_currency`.
          schema:
            type: string
            pattern: ^[A-Za-z]{3}$
            examples:
              - NGN
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Cursor"
      responses:
        "200":
          description: A page of offers.
          headers:
            Request-Id:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OfferPage"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /v1/offers/{offer_id}:
    get:
      operationId: getOffer
      summary: Retrieve an offer
      description: |
        One offer, including one the provider has withdrawn (`status: withdrawn`), which
        can no longer be bought.
      tags:
        - Offers
      parameters:
        - name: offer_id
          in: path
          required: true
          schema:
            type: string
        - name: display_currency
          in: query
          required: false
          schema:
            type: string
            pattern: ^[A-Za-z]{3}$
            examples:
              - NGN
      responses:
        "200":
          description: The offer.
          headers:
            Request-Id:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Offer"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /v1/countries:
    get:
      operationId: listCountries
      summary: List countries
      description: |
        Every country with an offer this key's mode can buy, A to Z, with how many
        offers it has. Build a country picker from it, then fetch a country's offers
        with `GET /v1/offers?country=`. Not paged: there are at most a few hundred.

        A regional or global bundle covers no single country, so it counts towards
        none here. It is still listed by `GET /v1/offers`, with `coverage: null`.
      tags:
        - Offers
      parameters:
        - name: category
          in: query
          required: false
          description: Count only offers in this category.
          schema:
            type: string
            enum:
              - esim
              - mobile_topup
            examples:
              - esim
      responses:
        "200":
          description: The countries, A to Z.
          headers:
            Request-Id:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CountryList"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /v1/wallet:
    get:
      operationId: getWallet
      summary: Retrieve the wallet
      description: |
        The wallet for the account the API key belongs to, in the key's mode. Every
        account has exactly one wallet per mode.
      tags:
        - Wallet
      responses:
        "200":
          description: The wallet.
          headers:
            Request-Id:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Wallet"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /v1/wallet/ledger:
    get:
      operationId: listWalletLedger
      summary: List wallet movements
      description: |
        Every credit and debit on the wallet, newest first, each with the balance it
        left behind. This is the customer-facing view of the ledger entries that are
        the source of truth for the balance.
      tags:
        - Wallet
      parameters:
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Cursor"
      responses:
        "200":
          description: A page of wallet movements.
          headers:
            Request-Id:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WalletLedgerPage"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /v1/wallet/aging:
    get:
      operationId: getWalletAging
      summary: Retrieve the wallet's aging
      description: |
        What the account owes and how old that debt is. Credits pay down debits oldest
        first (FIFO), so the oldest open debit is the first purchase the wallet's
        credits have not fully covered yet. It is due `net_terms_days` after it was
        made, and once it is past due the account is `overdue`. Paying down the
        oldest debits clears it, even if the balance is still negative.
      tags:
        - Wallet
      responses:
        "200":
          description: The wallet's FIFO aging.
          headers:
            Request-Id:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WalletAging"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /v1/wallet/addresses:
    get:
      operationId: listFundingDestinations
      summary: List funding destinations
      description: |
        The standing places this account pays into: a bank account and a stablecoin
        address per accepted asset and network. They are the same for every payment,
        and anything sent to them credits the wallet. Test and live destinations are
        different; never send real money to a test destination.

        Destinations are created on the first request. Naming an `asset` and a
        `network` asks for that one address alone and creates no other, which is the
        way to show a payer one address. If a destination cannot be created right
        now, the response is `502 rail_unavailable`: retry shortly.
      tags:
        - Wallet
      parameters:
        - name: asset
          in: query
          description: With `network`, list only this asset's address on it.
          schema:
            type: string
            enum:
              - USDT
              - USDC
        - name: network
          in: query
          description: |
            With `asset`. USDC is not accepted on `trc20` (`400
            unsupported_network`); one without the other is `400
            invalid_query_parameter`.
          schema:
            type: string
            enum:
              - bep20
              - base
              - trc20
      responses:
        "200":
          description: The account's funding destinations.
          headers:
            Request-Id:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FundingDestinationList"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "502":
          $ref: "#/components/responses/BadGateway"
  /v1/wallet/lightning_invoices:
    post:
      operationId: createLightningInvoice
      summary: Create a Lightning invoice
      description: |
        Mints a BOLT11 invoice to top the wallet up by any amount. Paying it credits the
        wallet in USD, and the credit then pays for whatever is waiting on it, exactly as
        a stablecoin deposit does.

        The invoice is denominated in USD by a USD-settling receiver: the payer sends
        satoshis, and the wallet is credited `amount` whatever the rate does in between.
        `amount_sats` is indicative only.

        Unlike a funding destination, an invoice is for one amount and expires, so this
        mints a new one each time and takes an `Idempotency-Key`. To pay for a single
        purchase without topping up first, use `payment_source: lightning` on a quote
        instead.

        If no invoice can be minted right now, nothing is created and the response is
        `502 rail_unavailable`: retry shortly.
      tags:
        - Wallet
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateLightningInvoiceRequest"
      responses:
        "200":
          description: The invoice to pay.
          headers:
            Request-Id:
              $ref: "#/components/headers/RequestId"
            Idempotent-Replayed:
              $ref: "#/components/headers/IdempotentReplayed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LightningInvoice"
        "400":
          description: |
            `amount_too_small` below one dollar, `unknown_parameter` for an unexpected
            field, or `invalid_request` for a malformed amount.
          headers:
            Request-Id:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "409":
          $ref: "#/components/responses/Conflict"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "502":
          $ref: "#/components/responses/BadGateway"
  /v1/wallet/deposits:
    get:
      operationId: listDeposits
      summary: List deposits
      description: |
        Money that arrived through a funding destination, newest first: stablecoin
        deposits and bank transfers. A stablecoin deposit is `detected` once the
        provider sees it and `credited` once it confirms; only then does it count
        toward the balance. Until then it shows in the wallet's `pending_credit`. A
        bank transfer is credited on arrival.
      tags:
        - Wallet
      parameters:
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Cursor"
      responses:
        "200":
          description: A page of deposits.
          headers:
            Request-Id:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DepositPage"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /v1/account:
    get:
      operationId: getAccount
      summary: Retrieve the account
      description: |
        The account the API key belongs to, with its credit terms in the key's mode.
        Credit terms are provisioned by Tizon, not through the API. An account that is
        `overdue` has its overdraft frozen until the debts past terms are paid down.
      tags:
        - Account
      responses:
        "200":
          description: The account.
          headers:
            Request-Id:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Account"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /v1/account/ledger:
    get:
      operationId: listAccountLedger
      summary: List the account's statement
      description: |
        Every movement on the account's two balances in the key's mode, newest first:
        the wallet, which it spends from, and the Revenue Centre, which holds what it
        has earned. Each line says which balance moved and what that balance was left
        at, so the statement reads the same way a bank statement does.

        A line that belongs to an order carries the order: what the account was
        charged, what it earned on it and the rate that earned it. `earned` is this
        account's own share of the price. What Tizon paid its supplier is not part of
        any response, here or anywhere else (adr/0033).
      tags:
        - Account
      parameters:
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Cursor"
      responses:
        "200":
          description: A page of the statement.
          headers:
            Request-Id:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AccountLedgerPage"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /v1/quotes:
    post:
      operationId: createQuote
      summary: Buy an offer
      description: |
        Prices the offer and pays for it.

        **`payment_source: wallet`.** If the wallet (including any overdraft) covers
        the price, it is debited at once, the quote is `fulfilled`, and an order is
        created and fulfilled in the background: poll the order or wait for its
        webhook. If not, nothing is charged and the response is `402`. While the
        account is overdue its overdraft is frozen, and the response is
        `403 account_overdue` until the debits past their terms are paid down.

        **`usdt`, `usdc` or `bank_transfer`.** The quote is `awaiting_funds` and
        `payment` says where to send `price`. A stablecoin quote names the `network`
        it will be paid on, and `payment` gives the account's address on that network.
        It waits even when the wallet already holds enough: money already there is
        spent only with `payment_source: wallet`. Every payment credits the wallet, and
        waiting quotes are then paid from the balance (never from an overdraft): the
        one priced exactly at what arrived first, then the oldest that fit.
        Unpaid by `expires_at`, it becomes `expired`; money that arrives later stays
        in the wallet.

        If the offer cannot be priced right now, nothing is created or charged and the
        response is `502 fulfillment_unavailable`: retry shortly. If the rail fails
        while the quote is being readied (giving the account a deposit address, or
        minting a Lightning invoice), the response is `502 rail_unavailable`: retry
        shortly, or pick another `payment_source`.
      tags:
        - Quotes
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateQuoteRequest"
      responses:
        "200":
          description: |
            The quote: `fulfilled` (paid, and the order is being fulfilled) or
            `awaiting_funds`.
          headers:
            Request-Id:
              $ref: "#/components/headers/RequestId"
            Idempotent-Replayed:
              $ref: "#/components/headers/IdempotentReplayed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Quote"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
        "422":
          $ref: "#/components/responses/Unprocessable"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "502":
          $ref: "#/components/responses/BadGateway"
  /v1/quotes/{quote_id}:
    get:
      operationId: getQuote
      summary: Retrieve a quote
      tags:
        - Quotes
      parameters:
        - name: quote_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: The quote.
          headers:
            Request-Id:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Quote"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /v1/quotes/{quote_id}/cancel:
    post:
      operationId: cancelQuote
      summary: Cancel a quote
      description: |
        Stops a quote waiting for funds. Money that arrives afterwards is credited to
        the wallet as usual and simply does not pay for this quote. Cancelling a
        cancelled quote returns it unchanged. A paid quote is `409 already_fulfilled`;
        a lapsed one is `409 quote_expired`.
      tags:
        - Quotes
      parameters:
        - name: quote_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: The cancelled quote.
          headers:
            Request-Id:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Quote"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /v1/revenue:
    get:
      operationId: retrieveRevenue
      summary: Retrieve the Revenue Centre
      description: |
        Every account earns a share of the price of every order it has fulfilled,
        accrued as it is fulfilled. The rate is the volume tier the last 30 days
        earned — under $5,000 is Standard at 15%, $5,000 to $50,000 is Growth at
        17.5%, above that is Scale at 20% — and nobody at Tizon sets it.

        `balance` is what is owed right now; moving it into the wallet turns it into
        credit that buys eSIMs like any other. An account that has bought nothing has
        a Revenue Centre with nothing in it, not a missing one.
      tags:
        - Revenue
      responses:
        "200":
          description: What this partner has earned.
          headers:
            Request-Id:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Revenue"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /v1/revenue/entries:
    get:
      operationId: listRevenueEntries
      summary: List what earned, and what was moved
      description: |
        Every accrual and every transfer out, newest first. An `earned` entry names
        the order that earned it and the rate in force at the time, so a past number
        explains itself.
      tags:
        - Revenue
      parameters:
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Cursor"
      responses:
        "200":
          description: A page of entries.
          headers:
            Request-Id:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RevenueEntryPage"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /v1/revenue/transfers:
    post:
      operationId: transferEarnings
      summary: Move earnings into the wallet
      description: |
        Turns earned commission into spendable wallet credit. Omit `amount` to move
        everything. What Tizon owed the partner stops being a payable and becomes
        credit the closed loop governs like any other: it buys eSIMs, and it does not
        come back out. To be paid in bitcoin instead, use `POST /v1/revenue/payouts`.
      tags:
        - Revenue
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TransferEarningsRequest"
      responses:
        "200":
          description: What moved, and what is left.
          headers:
            Request-Id:
              $ref: "#/components/headers/RequestId"
            Idempotent-Replayed:
              $ref: "#/components/headers/IdempotentReplayed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CommissionTransfer"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /v1/revenue/payout_address:
    put:
      operationId: setPayoutAddress
      summary: Set where earnings are paid
      description: |
        Where payouts go: a Lightning address such as `you@getalby.com`, a stablecoin
        address (`crypto_address`), or both. Send either to change only that one; the
        other is left as it is. A Lightning address is checked for shape and for
        pointing somewhere public, and a stablecoin address for the shape its network
        uses; whether anything answers there is found out by the first payout. A payout
        already asked for keeps the address it was asked for with. Moves no money, so
        it takes no `Idempotency-Key`.
      tags:
        - Revenue
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SetPayoutAddressRequest"
      responses:
        "200":
          description: The address payouts go to from now on.
          headers:
            Request-Id:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PayoutAddress"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /v1/revenue/payout_quote:
    get:
      operationId: retrievePayoutQuote
      summary: Preview a payout
      description: |
        What `POST /v1/revenue/payouts` would pay out by `method` right now: everything
        payable, the network fee taken from it, what arrives, and where. Asks the rail
        for the fee, so it can be `502 rail_unavailable`; it moves nothing and reserves
        nothing, and the fee is quoted again when the payout is asked for. No address
        for that method is `409 payout_address_required`.
      tags:
        - Revenue
      parameters:
        - $ref: "#/components/parameters/PayoutMethod"
      responses:
        "200":
          description: The payout as it would be asked for now.
          headers:
            Request-Id:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PayoutQuote"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "409":
          $ref: "#/components/responses/Conflict"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "502":
          $ref: "#/components/responses/BadGateway"
        "503":
          $ref: "#/components/responses/ServiceUnavailable"
  /v1/revenue/payouts:
    post:
      operationId: createPayout
      summary: Pay earnings out
      description: |
        Pays earnings out. Omit `amount` to pay out everything payable.

        `method` says where (adr/0056). `lightning`, the default, pays the account's
        Lightning address in satoshis worth the amount when the invoice is made; the
        routing fee is Tizon's, and the address receives the whole amount. `crypto`
        sends the stablecoin and network of the account's `crypto_address`, less the
        network fee, which is quoted when the payout is asked for and shown as
        `network_fee`; `GET /v1/revenue/payout_quote` shows it beforehand. Lightning
        payouts start at $1.00 and stablecoin payouts at $10.00.

        What is payable is the Revenue Centre's balance less any overdraft the wallet
        has drawn: Tizon never sends out money the account owes back.

        The payout is taken from the balance at once, so it cannot be spent twice, and
        comes back `awaiting_approval`: Tizon reviews every payout by hand and sends it
        within two business days (adr/0055). Once approved it is `pending` while it is
        sent, and ends `succeeded`, or `failed` with the money returned to the Revenue
        Centre; `payout.succeeded` and `payout.failed` say which. A payout turned down
        fails with `failure_reason` `rejected`, and its money is returned the same way.
        Payouts may be off on Tizon's side (`503 payouts_unavailable`), which never
        touches what has been earned.
      tags:
        - Revenue
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreatePayoutRequest"
      responses:
        "200":
          description: The payout, waiting for approval.
          headers:
            Request-Id:
              $ref: "#/components/headers/RequestId"
            Idempotent-Replayed:
              $ref: "#/components/headers/IdempotentReplayed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Payout"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "403":
          $ref: "#/components/responses/Forbidden"
        "409":
          $ref: "#/components/responses/Conflict"
        "422":
          $ref: "#/components/responses/Unprocessable"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "503":
          $ref: "#/components/responses/ServiceUnavailable"
    get:
      operationId: listPayouts
      summary: List payouts
      description: Every payout this account has asked for, newest first.
      tags:
        - Revenue
      parameters:
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Cursor"
      responses:
        "200":
          description: A page of payouts.
          headers:
            Request-Id:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PayoutPage"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /v1/revenue/payouts/{payout_id}:
    get:
      operationId: retrievePayout
      summary: Retrieve a payout
      tags:
        - Revenue
      parameters:
        - name: payout_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: The payout.
          headers:
            Request-Id:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Payout"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /v1/orders:
    get:
      operationId: listOrders
      summary: List orders
      description: |
        Every order this account has placed, newest first, with its deliverable once it
        is fulfilled.
      tags:
        - Orders
      parameters:
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Cursor"
      responses:
        "200":
          description: A page of orders.
          headers:
            Request-Id:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OrderPage"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /v1/orders/{order_id}:
    get:
      operationId: getOrder
      summary: Retrieve an order
      description: |
        An order starts `pending` and ends `fulfilled`, with its deliverable, or
        `failed`, in which case the price has been credited back to the wallet.
      tags:
        - Orders
      parameters:
        - name: order_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: The order.
          headers:
            Request-Id:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Order"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /v1/esims/{iccid}/usage:
    get:
      operationId: getEsimUsage
      summary: Retrieve an eSIM's data usage
      description: |
        How much data is left on each active and queued plan on an eSIM, measured when
        you ask. Nothing is pushed when usage changes, so call this when you need the
        figure, such as when a customer opens their eSIM, rather than on a timer.

        The eSIM must have been issued by one of this account's own orders. Any other
        ICCID, including one this account has only topped up, is `404 esim_not_found`.
        If usage cannot be read right now the answer is `502 fulfillment_unavailable`:
        retry shortly.

        In sandbox the figures are simulated from what was bought: the oldest plan
        still within its validity is `active` with a quarter of its data used, and any
        bought after it are `queued`.
      tags:
        - Orders
      parameters:
        - name: iccid
          in: path
          required: true
          description: The `iccid` from the order's eSIM profile.
          schema:
            type: string
            examples:
              - "8931440400000000123"
      responses:
        "200":
          description: The eSIM's plans and what each has left.
          headers:
            Request-Id:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EsimUsage"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "502":
          $ref: "#/components/responses/BadGateway"
  /v1/test_helpers/deposits:
    post:
      operationId: simulateDeposit
      summary: Simulate a stablecoin deposit
      description: |
        Pretends a stablecoin deposit arrived at this account's address. By default it
        is confirmed at once and credits the wallet; with `status: detected` it waits,
        counted in `pending_credit`, until you confirm it.
      tags:
        - Test helpers
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SimulateDepositRequest"
      responses:
        "200":
          description: The deposit, `credited` or `detected`.
          headers:
            Request-Id:
              $ref: "#/components/headers/RequestId"
            Idempotent-Replayed:
              $ref: "#/components/headers/IdempotentReplayed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Deposit"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /v1/test_helpers/deposits/{deposit_id}/confirm:
    post:
      operationId: confirmDeposit
      summary: Confirm a detected deposit
      description: |
        The chain confirms a deposit that was only detected, which credits the wallet.
        A deposit that is already credited is `409 deposit_already_credited`.
      tags:
        - Test helpers
      parameters:
        - name: deposit_id
          in: path
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "200":
          description: The credited deposit.
          headers:
            Request-Id:
              $ref: "#/components/headers/RequestId"
            Idempotent-Replayed:
              $ref: "#/components/headers/IdempotentReplayed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Deposit"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /v1/test_helpers/bank_transfers:
    post:
      operationId: simulateBankTransfer
      summary: Simulate a bank transfer
      description: |
        Pretends a bank transfer landed in this account's virtual account. Bank
        transfers are final on arrival, so the wallet is credited at once.
      tags:
        - Test helpers
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SimulateBankTransferRequest"
      responses:
        "200":
          description: The credited deposit.
          headers:
            Request-Id:
              $ref: "#/components/headers/RequestId"
            Idempotent-Replayed:
              $ref: "#/components/headers/IdempotentReplayed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Deposit"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /v1/test_helpers/lightning_invoices/{invoice_id}/pay:
    post:
      operationId: payLightningInvoice
      summary: Pay a Lightning invoice
      description: |
        Pretends a customer's wallet paid this invoice. The wallet is credited the
        invoice's USD amount and any quote it was minted for is settled, exactly as a
        real payment would. Only a `pending` invoice can be paid.

        `invoice_id` is the invoice's `lni_` id: `id` on an invoice from
        `POST /v1/wallet/lightning_invoices`, or `payment.lightning.id` on a quote with
        `payment_source: lightning`. A `bolt11` or `payment_hash` is
        `404 invoice_not_found`.
      tags:
        - Test helpers
      parameters:
        - name: invoice_id
          in: path
          required: true
          schema:
            type: string
            pattern: ^lni_[0-9A-HJKMNP-TV-Z]{26}$
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "200":
          description: The credited deposit.
          headers:
            Request-Id:
              $ref: "#/components/headers/RequestId"
            Idempotent-Replayed:
              $ref: "#/components/headers/IdempotentReplayed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Deposit"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: |
            `invoice_not_payable`: the invoice is already paid, or has expired.
          headers:
            Request-Id:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /v1/test_helpers/orders/{order_id}/complete:
    post:
      operationId: completeOrder
      summary: Resolve a pending order
      description: |
        The provider resolves an order that is still `pending`, as the sandbox offer
        `off_test_stays_pending` always is. `failed` credits the price back to the
        wallet. An order that is already resolved is `409 order_already_resolved`.
      tags:
        - Test helpers
      parameters:
        - name: order_id
          in: path
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CompleteOrderRequest"
      responses:
        "200":
          description: The resolved order.
          headers:
            Request-Id:
              $ref: "#/components/headers/RequestId"
            Idempotent-Replayed:
              $ref: "#/components/headers/IdempotentReplayed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Order"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /v1/test_helpers/credit:
    post:
      operationId: setSandboxCredit
      summary: Set sandbox credit terms
      description: |
        Grants this account test-mode credit, as Tizon would in live: an overdraft
        limit up to $10,000, and net terms (kept as they are when omitted, 30 days for
        an account with none). Zero net terms make any debt overdue at once, so the
        overdraft freeze can be tried without waiting. Every change is announced as
        `credit.updated`. Moves no money, so it takes no `Idempotency-Key`.
      tags:
        - Test helpers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SandboxCreditRequest"
      responses:
        "200":
          description: The account with its new test-mode credit terms.
          headers:
            Request-Id:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Account"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /v1/webhook_endpoints:
    post:
      operationId: registerWebhookEndpoint
      summary: Register a webhook endpoint
      description: |
        Registers an HTTPS URL for this account and mode, and returns its signing
        `secret` once. Store the secret: it is never shown again, and every delivery is
        signed with it.

        The URL must be `https://` and publicly reachable, in test mode as well as live;
        `localhost` and private ranges are refused (`400 invalid_webhook_url`). Use a
        tunnel to receive sandbox events on a laptop. Registering the same URL twice for
        one account is `409 webhook_url_in_use`.
      tags:
        - Webhooks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RegisterWebhookEndpointRequest"
      responses:
        "200":
          description: The endpoint, with its secret.
          headers:
            Request-Id:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookEndpoint"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "409":
          $ref: "#/components/responses/Conflict"
        "429":
          $ref: "#/components/responses/TooManyRequests"
    get:
      operationId: listWebhookEndpoints
      summary: List webhook endpoints
      description: This account's endpoints in this mode. Secrets are never listed.
      tags:
        - Webhooks
      responses:
        "200":
          description: The endpoints.
          headers:
            Request-Id:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookEndpointList"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /v1/webhook_endpoints/{webhook_endpoint_id}:
    get:
      operationId: getWebhookEndpoint
      summary: Retrieve a webhook endpoint
      tags:
        - Webhooks
      parameters:
        - name: webhook_endpoint_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: The endpoint.
          headers:
            Request-Id:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookEndpoint"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/TooManyRequests"
    delete:
      operationId: deleteWebhookEndpoint
      summary: Delete a webhook endpoint
      description: |
        Stops delivery to this endpoint. Its delivery history stays readable, and the
        same URL can be registered again afterwards.
      tags:
        - Webhooks
      parameters:
        - name: webhook_endpoint_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: The endpoint, now `deleted`.
          headers:
            Request-Id:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookEndpoint"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /v1/webhook_endpoints/{webhook_endpoint_id}/rotate_secret:
    post:
      operationId: rotateWebhookEndpointSecret
      summary: Rotate a webhook endpoint secret
      description: |
        Issues a new signing secret and returns it once. Deliveries are signed with the
        new secret immediately, so deploy it before rotating.
      tags:
        - Webhooks
      parameters:
        - name: webhook_endpoint_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: The endpoint, with its new secret.
          headers:
            Request-Id:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookEndpoint"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /v1/webhook_endpoints/{webhook_endpoint_id}/deliveries:
    get:
      operationId: listWebhookDeliveries
      summary: List deliveries to an endpoint
      description: |
        What Tizon tried to send this endpoint and what it answered, newest first, with
        the last ten attempts of each. Use it when an event did not arrive.
      tags:
        - Webhooks
      parameters:
        - name: webhook_endpoint_id
          in: path
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Cursor"
      responses:
        "200":
          description: A page of deliveries.
          headers:
            Request-Id:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookDeliveryPage"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /v1/webhook_endpoints/{webhook_endpoint_id}/ping:
    post:
      operationId: pingWebhookEndpoint
      summary: Send a test event
      description: |
        Delivers a `ping` event to this endpoint, whatever it subscribes to, so a new
        integration can prove its receiver and its signature check work. Returns the
        event; delivery happens in the background.
      tags:
        - Webhooks
      parameters:
        - name: webhook_endpoint_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: The event queued for delivery.
          headers:
            Request-Id:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Event"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /v1/events:
    get:
      operationId: listEvents
      summary: List events
      description: |
        Everything that happened on this account in this mode, newest first, whether or
        not an endpoint was subscribed at the time. Filter by `type`.
      tags:
        - Webhooks
      parameters:
        - name: type
          in: query
          required: false
          description: One event type, for example `order.fulfilled`.
          schema:
            type: string
            examples:
              - order.fulfilled
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Cursor"
      responses:
        "200":
          description: A page of events.
          headers:
            Request-Id:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EventPage"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /v1/events/{event_id}:
    get:
      operationId: getEvent
      summary: Retrieve an event
      description: The event as it was delivered, including its `data.object`.
      tags:
        - Webhooks
      parameters:
        - name: event_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: The event.
          headers:
            Request-Id:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Event"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /v1/events/{event_id}/replay:
    post:
      operationId: replayEvent
      summary: Replay an event
      description: |
        Sends a stored event again. The event keeps its id, so a receiver that already
        processed it will recognise it; the deliveries are new. It goes to every
        endpoint subscribed now, so an endpoint registered after the fact can catch up,
        or to one endpoint if you name it.
      tags:
        - Webhooks
      parameters:
        - name: event_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ReplayEventRequest"
      responses:
        "200":
          description: The deliveries queued.
          headers:
            Request-Id:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookDeliveryPage"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/TooManyRequests"
components:
  securitySchemes:
    ApiKey:
      type: http
      scheme: bearer
      description: |
        An account API key, sent as `Authorization: Bearer tz_live_…`. The prefix
        selects the mode: `tz_test_` for sandbox, `tz_live_` for real money.
  headers:
    RequestId:
      description: Unique id for this request, for support and log correlation.
      required: true
      schema:
        type: string
        pattern: ^req_[0-9a-f]{32}$
    IdempotentReplayed:
      description: Present, with `true`, when this is a replay of an earlier request.
      required: false
      schema:
        const: "true"
    RateLimitLimit:
      description: How many requests this bucket allows per window.
      required: false
      schema:
        type: string
        pattern: ^[0-9]+$
    RateLimitRemaining:
      description: How many more requests the current window allows.
      required: false
      schema:
        type: string
        pattern: ^[0-9]+$
    RateLimitReset:
      description: Seconds until the current window ends and the count restarts.
      required: false
      schema:
        type: string
        pattern: ^[0-9]+$
    RetryAfter:
      description: Whole seconds to wait before retrying.
      required: true
      schema:
        type: string
        pattern: ^[0-9]+$
  parameters:
    PayoutMethod:
      name: method
      in: query
      required: false
      description: Which way to pay out; `lightning` when left out.
      schema:
        type: string
        enum:
          - lightning
          - crypto
        default: lightning
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      description: |
        A client-generated key, unique per intended operation, that makes this request
        safe to retry. The same key returns the original response; the same key with a
        different request is rejected. Missing: `400 idempotency_key_required`.
      schema:
        type: string
        minLength: 1
        maxLength: 255
    Limit:
      name: limit
      in: query
      required: false
      description: Maximum items to return.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
    Cursor:
      name: cursor
      in: query
      required: false
      description: The `next_cursor` from a previous page.
      schema:
        type: string
  schemas:
    Money:
      type: object
      description: A settlement amount in integer minor units.
      properties:
        amount:
          type: integer
          format: int64
          description: Minor units. `1450` with currency `USD` is $14.50.
          examples:
            - 1450
        currency:
          type: string
          description: ISO 4217 code. Settlement is always `USD`.
          pattern: ^[A-Z]{3}$
          examples:
            - USD
      required:
        - amount
        - currency
      additionalProperties: false
    DisplayMoney:
      type: object
      description: |
        An indicative amount in a requested display currency. Presentation only: never
        a settlement amount, and never used to move money.
      properties:
        amount:
          type: integer
          format: int64
          examples:
            - 2320000
        currency:
          type: string
          pattern: ^[A-Z]{3}$
          examples:
            - NGN
        rate:
          type: string
          description: Decimal string for the rate used.
          examples:
            - "1600.00"
        indicative:
          const: true
      required:
        - amount
        - currency
        - indicative
      additionalProperties: false
    ListPage:
      type: object
      description: |
        Shared fields of a cursor-paginated page. Each collection response combines
        these with its own `data` array.
      properties:
        object:
          const: list
        has_more:
          type: boolean
          description: Whether another page follows.
        next_cursor:
          type:
            - string
            - "null"
          description: Pass as `cursor` to fetch the next page. Null on the last page.
      required:
        - object
        - has_more
        - next_cursor
    ErrorType:
      type: string
      description: Stable error category.
      enum:
        - invalid_request_error
        - authentication_error
        - payment_required
        - permission_error
        - not_found
        - conflict
        - unprocessable
        - rate_limit_error
        - api_error
        - upstream_error
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              $ref: "#/components/schemas/ErrorType"
            code:
              type: string
              description: The specific reason, stable per `type`.
              examples:
                - insufficient_funds
            message:
              type: string
              description: Human-readable explanation. Not for programmatic use.
            request_id:
              type: string
              pattern: ^req_[0-9a-f]{32}$
            shortfall:
              $ref: "#/components/schemas/Money"
            retry_after:
              type: integer
              description: |
                Seconds to wait before retrying, on `too_many_requests` and
                `too_many_attempts`. The same value as the `Retry-After` header.
              examples:
                - 60
            unsettled:
              type: array
              description: |
                On `account_not_settled`: every live condition that stops the account
                closing, in this order. `wallet_balance` (the wallet is not at exactly
                zero, either way), `commission_balance` (unpaid earnings),
                `payouts_in_flight`, `pending_orders`, `awaiting_quotes`,
                `uncredited_deposits` (detected, not yet credited).
              items:
                type: string
                enum:
                  - wallet_balance
                  - commission_balance
                  - payouts_in_flight
                  - pending_orders
                  - awaiting_quotes
                  - uncredited_deposits
              minItems: 1
          required:
            - type
            - code
            - message
            - request_id
      required:
        - error
      additionalProperties: false
    Offer:
      type: object
      description: |
        Something buyable, priced in USD. The wholesale cost is never exposed.
      properties:
        id:
          type: string
          description: The id to quote with.
          examples:
            - off_jp_5gb_30d
        object:
          const: offer
        category:
          type: string
          enum:
            - esim
            - mobile_topup
          description: More categories may be added; treat this as an open enum.
        name:
          type: string
          examples:
            - Japan 5GB 30 days
        coverage:
          type:
            - object
            - "null"
          description: Where the offer works. Null when the provider does not say.
          properties:
            type:
              const: country
            countries:
              type: array
              items:
                type: string
                pattern: ^[A-Z]{2}$
          required:
            - type
            - countries
          additionalProperties: false
        data:
          type:
            - object
            - "null"
          description: The data allowance, for eSIM offers.
          properties:
            amount:
              type: number
            unit:
              const: GB
            unlimited:
              type: boolean
          required:
            - amount
            - unit
            - unlimited
          additionalProperties: false
        validity_days:
          type:
            - integer
            - "null"
        price:
          allOf:
            - $ref: "#/components/schemas/Money"
          description: The binding amount a quote will debit.
        display:
          allOf:
            - $ref: "#/components/schemas/DisplayMoney"
          description: |
            Present only when `display_currency` was requested. Indicative, for
            presentation.
        requires_destination:
          type: boolean
          description: |
            When true, quoting this offer needs a `destination` phone number
            (`400 missing_destination` otherwise).
        status:
          type: string
          enum:
            - active
            - withdrawn
          description: |
            `withdrawn` means the provider no longer sells it; quoting it fails with
            `400 offer_unavailable`.
      required:
        - id
        - object
        - category
        - name
        - coverage
        - data
        - validity_days
        - price
        - requires_destination
        - status
      additionalProperties: false
    OfferPage:
      allOf:
        - $ref: "#/components/schemas/ListPage"
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: "#/components/schemas/Offer"
          required:
            - data
    CountryList:
      type: object
      properties:
        object:
          const: list
        data:
          type: array
          items:
            $ref: "#/components/schemas/Country"
      required:
        - object
        - data
      additionalProperties: false
    Country:
      type: object
      description: A country with at least one offer on sale.
      properties:
        country:
          type: string
          pattern: ^[A-Z]{2}$
          description: ISO 3166-1 alpha-2. Pass it as `country` to `GET /v1/offers`.
          examples:
            - JP
        offer_count:
          type: integer
          minimum: 1
          description: How many offers it has, in `category` when one was given.
          examples:
            - 12
      required:
        - country
        - offer_count
      additionalProperties: false
    Wallet:
      type: object
      description: |
        A closed-loop USD balance. It may go negative for accounts with an overdraft;
        there are no withdrawals, and it is spendable only on products.
      properties:
        id:
          type: string
          pattern: ^wlt_[0-9A-HJKMNP-TV-Z]{26}$
        object:
          const: wallet
        currency:
          const: USD
        balance:
          $ref: "#/components/schemas/Money"
        available_to_spend:
          allOf:
            - $ref: "#/components/schemas/Money"
          description: |
            Balance plus any overdraft limit. While the account is overdue its
            overdraft is frozen, so this is the balance alone, and below zero.
        overdraft:
          type: object
          properties:
            limit:
              allOf:
                - $ref: "#/components/schemas/Money"
              description: How far below zero the balance may go. Zero unless granted.
            used:
              allOf:
                - $ref: "#/components/schemas/Money"
              description: How much of that limit is currently drawn.
          required:
            - limit
            - used
          additionalProperties: false
        pending_credit:
          allOf:
            - $ref: "#/components/schemas/Money"
          description: |
            Stablecoin deposits the provider has detected but not yet confirmed. Not
            spendable, and not part of `balance`, until they are credited.
        status:
          type: string
          enum:
            - active
            - suspended
            - closed
          description: |
            `suspended` while the account is: the wallet can be read but not spent
            from. `closed` is only ever seen by ops reading an anonymised account's
            live wallet. See `Account.status`.
      required:
        - id
        - object
        - currency
        - balance
        - available_to_spend
        - overdraft
        - pending_credit
        - status
      additionalProperties: false
    WalletLedgerEntry:
      type: object
      description: One movement on the wallet, and the balance it left behind.
      properties:
        id:
          type: string
          pattern: ^le_[0-9A-HJKMNP-TV-Z]{26}$
        object:
          const: ledger_entry
        type:
          type: string
          enum:
            - credit
            - debit
          description: A credit raises the balance; a debit lowers it.
        source:
          type: string
          enum:
            - deposit
            - topup
            - refund
            - purchase
            - commission
            - adjustment
          description: |
            What caused the movement. `commission` is a partner moving earnings from
            their Revenue Centre into spendable credit. `adjustment` is Tizon
            crediting or debiting the wallet by hand, to make good or to correct;
            `description` says why. `commission` and `adjustment` are additions to the
            sources listed in the API design.
        amount:
          allOf:
            - $ref: "#/components/schemas/Money"
          description: Always positive; `type` carries the direction.
        balance_after:
          allOf:
            - $ref: "#/components/schemas/Money"
          description: The wallet balance immediately after this movement.
        description:
          type:
            - string
            - "null"
        created_at:
          type: string
          format: date-time
      required:
        - id
        - object
        - type
        - source
        - amount
        - balance_after
        - description
        - created_at
      additionalProperties: false
    WalletLedgerPage:
      allOf:
        - $ref: "#/components/schemas/ListPage"
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: "#/components/schemas/WalletLedgerEntry"
          required:
            - data
    WalletAging:
      type: object
      description: |
        FIFO aging of what the account owes. Every credit pays down the oldest debits
        first; the oldest open debit is the first one not yet fully covered.
      properties:
        object:
          const: wallet_aging
        wallet_id:
          type: string
          pattern: ^wlt_[0-9A-HJKMNP-TV-Z]{26}$
        outstanding:
          allOf:
            - $ref: "#/components/schemas/Money"
          description: What is owed. Zero unless the balance is negative.
        oldest_open_debit:
          description: The oldest purchase not yet paid down, or null when nothing is owed.
          oneOf:
            - type: "null"
            - type: object
              properties:
                id:
                  type: string
                  pattern: ^le_[0-9A-HJKMNP-TV-Z]{26}$
                  description: The debit's entry in the wallet ledger.
                amount:
                  allOf:
                    - $ref: "#/components/schemas/Money"
                  description: The whole debit.
                open_amount:
                  allOf:
                    - $ref: "#/components/schemas/Money"
                  description: The part of it credits have not covered yet.
                created_at:
                  type: string
                  format: date-time
                age_days:
                  type: integer
                  minimum: 0
                  description: Whole days since the debit.
                due_at:
                  type: string
                  format: date-time
                  description: |
                    `created_at` plus `net_terms_days`. After this, the account is
                    `overdue`.
              required:
                - id
                - amount
                - open_amount
                - created_at
                - age_days
                - due_at
              additionalProperties: false
        net_terms_days:
          type: integer
          minimum: 0
          description: How long a debit may stay open before it is overdue.
        status:
          type: string
          enum:
            - current
            - overdue
          description: |
            `overdue` once the oldest open debit is past `due_at`; otherwise `current`,
            including when nothing is owed.
      required:
        - object
        - wallet_id
        - outstanding
        - oldest_open_debit
        - net_terms_days
        - status
      additionalProperties: false
    Credit:
      type: object
      description: |
        Credit terms in one mode. Provisioned by Tizon; an account without them has no
        overdraft and the default net terms. The overdraft is the whole of the credit:
        there is no separate collateral, and a deposit pays down what has been drawn
        before it adds to the balance (adr/0032).
      properties:
        overdraft_limit:
          allOf:
            - $ref: "#/components/schemas/Money"
          description: How far below zero the wallet may go. Zero unless granted.
        net_terms_days:
          type: integer
          minimum: 0
          description: How long a debit may stay open before the account is overdue.
        status:
          type: string
          enum:
            - active
            - overdue
          description: |
            `overdue` when the oldest open debit is past its terms. An overdue
            account's overdraft is frozen until those debits are paid down.
      required:
        - overdraft_limit
        - net_terms_days
        - status
      additionalProperties: false
    AccountLedgerPage:
      allOf:
        - $ref: "#/components/schemas/ListPage"
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: "#/components/schemas/AccountLedgerEntry"
          required:
            - data
    AccountLedgerEntry:
      type: object
      description: |
        One movement on the wallet or the Revenue Centre, and what it left that balance
        at. Moving earnings into the wallet is one event with two lines: a debit on the
        Revenue Centre and a `commission` credit on the wallet.
      properties:
        id:
          type: string
          pattern: ^le_[0-9A-HJKMNP-TV-Z]{26}$
          description: |
            The posting. A wallet line has the same id here as in
            `GET /v1/wallet/ledger`.
        object:
          const: account_ledger_entry
        balance:
          type: string
          enum:
            - wallet
            - revenue
          description: Which of the account's balances moved.
        type:
          type: string
          enum:
            - credit
            - debit
          description: A credit raises that balance; a debit lowers it.
        source:
          type: string
          enum:
            - deposit
            - topup
            - refund
            - purchase
            - commission
            - earned
            - taken_as_credit
            - paid_out
            - payout_returned
            - adjustment
          description: |
            What caused the movement. Wallet lines use the sources of
            `GET /v1/wallet/ledger`. On the Revenue Centre, `earned` is an order's share
            accruing, `taken_as_credit` is earnings moved into the wallet, `paid_out` is
            a Lightning payout, and `payout_returned` is a failed one coming back.
        amount:
          allOf:
            - $ref: "#/components/schemas/Money"
          description: Always positive; `type` carries the direction.
        balance_after:
          allOf:
            - $ref: "#/components/schemas/Money"
          description: |
            The balance named by `balance`, immediately after this movement. A negative
            wallet balance is overdraft drawn.
        order:
          oneOf:
            - $ref: "#/components/schemas/AccountLedgerOrder"
            - type: "null"
          description: The order this movement belongs to, or null if none does.
        description:
          type:
            - string
            - "null"
        created_at:
          type: string
          format: date-time
      required:
        - id
        - object
        - balance
        - type
        - source
        - amount
        - balance_after
        - order
        - description
        - created_at
      additionalProperties: false
    AccountLedgerOrder:
      type: object
      description: |
        The order behind a statement line, as it stands now: a purchase line shows what
        its order went on to earn.
      properties:
        id:
          type: string
          pattern: ^ord_[0-9A-HJKMNP-TV-Z]{26}$
        status:
          type: string
          enum:
            - pending
            - fulfilled
            - failed
        price:
          allOf:
            - $ref: "#/components/schemas/Money"
          description: What the account was charged for it.
        earned:
          oneOf:
            - $ref: "#/components/schemas/Money"
            - type: "null"
          description: |
            The account's share of the price, credited to its Revenue Centre when the
            order was fulfilled. Null until then, and for an order that failed, which
            earns nothing because it was refunded.
        commission_rate_bps:
          type:
            - integer
            - "null"
          description: |
            The rate that earned it, in basis points of the price, as it was when the
            order was fulfilled. Null when nothing was earned.
      required:
        - id
        - status
        - price
        - earned
        - commission_rate_bps
      additionalProperties: false
    Account:
      type: object
      properties:
        id:
          type: string
          pattern: ^acct_[0-9A-HJKMNP-TV-Z]{26}$
        object:
          const: account
        livemode:
          type: boolean
          description: Which mode `credit` describes; the key's own.
        name:
          type:
            - string
            - "null"
          description: What Tizon calls this account, if anything.
        status:
          type: string
          enum:
            - active
            - suspended
            - closed
          description: |
            A suspended account can still read: wallet, orders and the eSIMs it has
            already paid for. Anything that moves money is `403 account_suspended`.
            A closed account is final and can do nothing at all
            (`403 account_closed`); only ops still see it.
        kyb_state:
          type: string
          enum:
            - none
            - pending
            - approved
            - rejected
          description: |
            How far along the business checks are. Test access never waits on them;
            live access does.
        live_enabled:
          type: boolean
          description: |
            False when Tizon has switched this account's live access off. Live
            requests may then only read (`403 live_access_disabled`); the sandbox is
            unaffected and the KYB approval stands.
        live_access:
          type: boolean
          description: |
            Whether live money is allowed yet: `kyb_state` is `approved`, the account
            is not suspended and `live_enabled` is true. Live keys are only issued once
            it is true.
        credit:
          $ref: "#/components/schemas/Credit"
        created_at:
          type: string
          format: date-time
      required:
        - id
        - object
        - livemode
        - name
        - status
        - kyb_state
        - live_enabled
        - live_access
        - credit
        - created_at
      additionalProperties: false
    SandboxCreditRequest:
      type: object
      properties:
        overdraft_limit:
          allOf:
            - $ref: "#/components/schemas/Money"
          description: How far below zero the test wallet may go. At most $10,000.
          examples:
            - amount: 50000
              currency: USD
        net_terms_days:
          type: integer
          minimum: 0
          maximum: 365
          description: |
            How long a debit may stay open before the account is overdue. Zero makes
            any debt overdue at once.
      required:
        - overdraft_limit
      additionalProperties: false
    Revenue:
      type: object
      description: |
        A partner's Revenue Centre in one mode (adr/0030): what they have earned on the
        orders they brought, and what has become of it.
      properties:
        object:
          type: string
          const: revenue
        tier:
          type: string
          enum:
            - standard
            - growth
            - scale
          description: |
            Which rung of the volume ladder the last 30 days earned. Derived, never
            set by hand.
        commission_bps:
          type: integer
          description: |
            The rate that tier pays, in basis points of each order's price. 1500 is
            15%.
        negotiated:
          type: boolean
          description: |
            True when an agreed rate is overriding the ladder, so `commission_bps` is
            not the rate `tier` would pay. Rare; almost every account is on the ladder.
        volume:
          allOf:
            - $ref: "#/components/schemas/Money"
          description: Fulfilled purchases over the last 30 days, which decide the tier.
        next_tier:
          type:
            - object
            - "null"
          description: The next rung and what it takes to reach it; null at the top.
          properties:
            tier:
              type: string
              enum:
                - growth
                - scale
            from:
              $ref: "#/components/schemas/Money"
            commission_bps:
              type: integer
          required:
            - tier
            - from
            - commission_bps
          additionalProperties: false
        balance:
          allOf:
            - $ref: "#/components/schemas/Money"
          description: Earned and not yet moved or paid out; what Tizon owes right now.
        lifetime_earned:
          allOf:
            - $ref: "#/components/schemas/Money"
          description: Everything ever earned, whatever became of it.
        taken_as_credit:
          allOf:
            - $ref: "#/components/schemas/Money"
          description: How much has been moved into the wallet as spendable credit.
        paid_out:
          allOf:
            - $ref: "#/components/schemas/Money"
          description: |
            How much has been paid out, is on its way, or is waiting for approval. A
            failed or rejected payout comes back and stops counting.
        payable:
          allOf:
            - $ref: "#/components/schemas/Money"
          description: |
            What could be paid out right now: `balance` less any overdraft the wallet
            has drawn, never below zero.
        payout_address:
          type:
            - string
            - "null"
          description: The Lightning address payouts go to; null until one is set.
        crypto_payout_address:
          description: The stablecoin address payouts go to; null until one is set.
          oneOf:
            - type: "null"
            - $ref: "#/components/schemas/CryptoPayoutAddress"
        orders_earning:
          type: integer
          description: How many fulfilled orders have earned something.
      required:
        - object
        - tier
        - commission_bps
        - negotiated
        - volume
        - next_tier
        - balance
        - lifetime_earned
        - taken_as_credit
        - paid_out
        - payable
        - payout_address
        - crypto_payout_address
        - orders_earning
      additionalProperties: false
    RevenueEntry:
      type: object
      description: |
        One accrual, one move into the wallet, one payout, or a failed payout coming
        back.
      properties:
        id:
          type: string
          pattern: ^le_[0-9A-HJKMNP-TV-Z]{26}$
        object:
          type: string
          const: revenue_entry
        kind:
          type: string
          enum:
            - earned
            - taken_as_credit
            - paid_out
            - payout_returned
        amount:
          allOf:
            - $ref: "#/components/schemas/Money"
          description: Always positive; `kind` carries the direction.
        order_id:
          type:
            - string
            - "null"
          description: The order that earned it; null for anything else.
        payout_id:
          type:
            - string
            - "null"
          description: The payout it went to, or came back from; null otherwise.
        rate_bps:
          type:
            - integer
            - "null"
          description: |
            The rate in force when it was earned, so a past entry explains its own
            number. Null for a move into the wallet.
        created_at:
          type: string
          format: date-time
      required:
        - id
        - object
        - kind
        - amount
        - order_id
        - payout_id
        - rate_bps
        - created_at
      additionalProperties: false
    RevenueEntryPage:
      allOf:
        - $ref: "#/components/schemas/ListPage"
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: "#/components/schemas/RevenueEntry"
          required:
            - data
    TransferEarningsRequest:
      type: object
      properties:
        amount:
          allOf:
            - $ref: "#/components/schemas/Money"
          description: |
            How much to move. Omit to move everything that has been earned. More than
            has been earned is `402 amount_above_balance`, and moving from an empty
            Revenue Centre is `402 nothing_to_transfer`.
      additionalProperties: false
    CreatePayoutRequest:
      type: object
      properties:
        amount:
          allOf:
            - $ref: "#/components/schemas/Money"
          description: |
            How much to pay out. Omit to pay out everything payable. More than is
            payable is `402 amount_above_payable`, nothing payable is
            `402 nothing_to_pay_out`, under the method's minimum ($1.00 over Lightning,
            $10.00 in stablecoin) is `422 payout_below_minimum`, and no address set for
            the method is `409 payout_address_required`.
        method:
          type: string
          enum:
            - lightning
            - crypto
          default: lightning
          description: |
            `lightning` pays the Lightning address; `crypto` sends the stablecoin
            address, less the network fee.
      additionalProperties: false
    SetPayoutAddressRequest:
      type: object
      description: At least one of the two; whichever is left out stays as it is.
      properties:
        lightning_address:
          type: string
          minLength: 3
          maxLength: 320
          description: |
            A Lightning address (LUD-16), `name@domain`. Anything else is
            `400 invalid_lightning_address`.
          examples:
            - earnings@getalby.com
        crypto_address:
          $ref: "#/components/schemas/CryptoPayoutAddress"
      minProperties: 1
      additionalProperties: false
    CryptoPayoutAddress:
      type: object
      description: |
        A stablecoin address on one network (adr/0056): USDT on `bep20`, `base` or
        `trc20`, or USDC on `base` or `bep20`. A `trc20` address is a Tron address
        (`T…`, 34 characters); `bep20` and `base` take an `0x` address of 40 hex
        digits. A pair that is not offered, or an address of the wrong shape for its
        network, is `400 invalid_crypto_address`. Funds sent on the wrong network are
        lost, so the network is never guessed from the address.
      properties:
        asset:
          type: string
          enum:
            - USDT
            - USDC
        network:
          type: string
          enum:
            - bep20
            - base
            - trc20
        address:
          type: string
          minLength: 26
          maxLength: 64
          examples:
            - TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf
      required:
        - asset
        - network
        - address
      additionalProperties: false
    PayoutAddress:
      type: object
      properties:
        object:
          type: string
          const: payout_address
        lightning_address:
          type:
            - string
            - "null"
        crypto_address:
          oneOf:
            - type: "null"
            - $ref: "#/components/schemas/CryptoPayoutAddress"
        updated_at:
          type: string
          format: date-time
      required:
        - object
        - lightning_address
        - crypto_address
        - updated_at
      additionalProperties: false
    Payout:
      type: object
      description: |
        Earnings paid out to a Lightning address (adr/0034) or a stablecoin address
        (adr/0056). What it cost Tizon to send is not part of it; a stablecoin
        payout's network fee is the partner's, and is.
      properties:
        id:
          type: string
          pattern: ^pyo_[0-9A-HJKMNP-TV-Z]{26}$
        object:
          type: string
          const: payout
        livemode:
          type: boolean
        status:
          type: string
          enum:
            - awaiting_approval
            - pending
            - succeeded
            - failed
          description: |
            `awaiting_approval` until Tizon has reviewed it, within two business days
            (adr/0055); then `pending` until the payment settles. `failed` returns the
            amount to the Revenue Centre.
        amount:
          allOf:
            - $ref: "#/components/schemas/Money"
          description: |
            What was taken from earnings. A Lightning address is paid all of it; a
            stablecoin address is paid it less `network_fee`.
        method:
          type: string
          enum:
            - lightning
            - crypto
        lightning_address:
          type:
            - string
            - "null"
          description: |
            Where a Lightning payout was sent, as the address was when it was asked
            for; null for a stablecoin payout.
        crypto_address:
          description: |
            Where a stablecoin payout was sent, as the address was when it was asked
            for; null for a Lightning payout.
          oneOf:
            - type: "null"
            - $ref: "#/components/schemas/CryptoPayoutAddress"
        network_fee:
          description: |
            The network fee taken from a stablecoin payout before it is sent, quoted
            when it was asked for; null for a Lightning payout, whose fee is Tizon's.
          oneOf:
            - type: "null"
            - $ref: "#/components/schemas/Money"
        transaction_hash:
          type:
            - string
            - "null"
          description: |
            The on-chain transaction of a stablecoin payout, once it has been sent.
            Null for a Lightning payout, which has `payment_hash` instead.
        payment_hash:
          type:
            - string
            - "null"
          description: |
            The Lightning payment hash, once the address has given an invoice. What a
            receiving wallet shows for the payment.
        amount_sats:
          type:
            - integer
            - "null"
          description: The satoshis the invoice was for; null until there is one.
        failure_reason:
          type:
            - string
            - "null"
          description: |
            Why it failed: `rejected` (Tizon turned it down before sending anything),
            `address_refused` (the address gave no usable invoice, or the network would
            not take the address), `payment_failed` or `no_route` (the payment did not
            go through), `payment_refused`, `invoice_expired`, or `send_rejected` (the
            stablecoin send was refused). Null unless `failed`.
        rejection_reason:
          type:
            - string
            - "null"
          description: |
            What Tizon said when it turned the payout down, if it said anything; null
            unless `failure_reason` is `rejected`.
        created_at:
          type: string
          format: date-time
        resolved_at:
          type:
            - string
            - "null"
          format: date-time
      required:
        - id
        - object
        - livemode
        - status
        - amount
        - method
        - lightning_address
        - crypto_address
        - network_fee
        - transaction_hash
        - payment_hash
        - amount_sats
        - failure_reason
        - rejection_reason
        - created_at
        - resolved_at
      additionalProperties: false
    PayoutPage:
      allOf:
        - $ref: "#/components/schemas/ListPage"
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: "#/components/schemas/Payout"
          required:
            - data
    PayoutQuote:
      type: object
      description: |
        A payout as it would be asked for now, by one method (adr/0056). Nothing is
        reserved: the amount can change as the account earns or spends, and the fee
        is quoted again when the payout is asked for.
      properties:
        object:
          type: string
          const: payout_quote
        livemode:
          type: boolean
        method:
          type: string
          enum:
            - lightning
            - crypto
        amount:
          allOf:
            - $ref: "#/components/schemas/Money"
          description: Everything payable now, which a payout with no amount takes.
        network_fee:
          allOf:
            - $ref: "#/components/schemas/Money"
          description: What the network fee takes from it; zero over Lightning.
        amount_received:
          allOf:
            - $ref: "#/components/schemas/Money"
          description: "`amount` less `network_fee`, never below zero."
        minimum:
          allOf:
            - $ref: "#/components/schemas/Money"
          description: The smallest payout this method takes.
        lightning_address:
          type:
            - string
            - "null"
        crypto_address:
          oneOf:
            - type: "null"
            - $ref: "#/components/schemas/CryptoPayoutAddress"
      required:
        - object
        - livemode
        - method
        - amount
        - network_fee
        - amount_received
        - minimum
        - lightning_address
        - crypto_address
      additionalProperties: false
    CommissionTransfer:
      type: object
      description: Earnings turned into wallet credit.
      properties:
        object:
          type: string
          const: commission_transfer
        id:
          type: string
          pattern: ^cmt_[0-9A-HJKMNP-TV-Z]{26}$
        amount:
          allOf:
            - $ref: "#/components/schemas/Money"
          description: What moved.
        balance:
          allOf:
            - $ref: "#/components/schemas/Money"
          description: What is left in the Revenue Centre.
      required:
        - object
        - id
        - amount
        - balance
      additionalProperties: false
    OrderPage:
      allOf:
        - $ref: "#/components/schemas/ListPage"
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: "#/components/schemas/Order"
          required:
            - data
    EsimUsage:
      type: object
      description: |
        The plans on an eSIM and how much data each has left, measured when you asked.
      properties:
        object:
          const: esim_usage
        iccid:
          type: string
          examples:
            - "8931440400000000123"
        installed_at:
          type:
            - string
            - "null"
          format: date-time
          description: |
            When the profile was first installed on a device. Null until it has been.
        plans:
          type: array
          description: |
            The eSIM's active and queued plans. Empty when it has nothing left to run.
          items:
            $ref: "#/components/schemas/EsimPlan"
      required:
        - object
        - iccid
        - installed_at
        - plans
      additionalProperties: false
    EsimPlan:
      type: object
      properties:
        offer_id:
          type: string
          description: The offer this plan was bought as.
        status:
          type: string
          enum:
            - active
            - queued
            - ended
          description: |
            `active` is in use now. `queued` has not started yet, so it has no dates: a
            plan bought on top of another waits for that one to run out, and a new
            eSIM's plan can wait until the eSIM is first used. `ended` has run its
            course; plans that have are normally left out altogether.
        starts_at:
          type:
            - string
            - "null"
          format: date-time
          description: Null until the plan starts.
        ends_at:
          type:
            - string
            - "null"
          format: date-time
          description: |
            When the plan expires, however much data is left. Null until it starts.
        data:
          type: object
          properties:
            unit:
              const: GB
            unlimited:
              type: boolean
            total:
              type:
                - number
                - "null"
              description: The plan's allowance. Null when unlimited or not reported.
              examples:
                - 5
            remaining:
              type:
                - number
                - "null"
              description: |
                What is left, to two decimal places. Null when unlimited or not
                reported.
              examples:
                - 3.75
            used:
              type:
                - number
                - "null"
              description: "`total` less `remaining`. Null when either is."
              examples:
                - 1.25
          required:
            - unit
            - unlimited
            - total
            - remaining
            - used
          additionalProperties: false
      required:
        - offer_id
        - status
        - starts_at
        - ends_at
        - data
      additionalProperties: false
    CryptoAddressDestination:
      type: object
      properties:
        id:
          type: string
          pattern: ^addr_[0-9A-HJKMNP-TV-Z]{26}$
        object:
          const: funding_destination
        type:
          const: crypto_address
        asset:
          type: string
          enum:
            - USDT
            - USDC
        network:
          type: string
          enum:
            - bep20
            - base
            - trc20
          description: USDT on bep20, base and trc20; USDC on base and bep20.
        address:
          type:
            - string
            - "null"
          description: |
            Null while the provider is still generating it (`status` pending). A sandbox
            address is made up and nobody holds its key, so real money sent to it is
            lost. An EVM one deliberately fails its EIP-55 checksum so that wallets refuse
            it, which means a checksum check in your own code rejects it too.
        memo:
          type:
            - string
            - "null"
        status:
          type: string
          enum:
            - pending
            - active
      required:
        - id
        - object
        - type
        - asset
        - network
        - address
        - memo
        - status
      additionalProperties: false
    BankAccountDestination:
      type: object
      properties:
        id:
          type: string
          pattern: ^vac_[0-9A-HJKMNP-TV-Z]{26}$
        object:
          const: funding_destination
        type:
          const: bank_account
        bank_name:
          type: string
        account_number:
          type: string
        account_name:
          type: string
      required:
        - id
        - object
        - type
        - bank_name
        - account_number
        - account_name
      additionalProperties: false
    FundingDestinationList:
      allOf:
        - $ref: "#/components/schemas/ListPage"
        - type: object
          properties:
            data:
              type: array
              items:
                oneOf:
                  - $ref: "#/components/schemas/BankAccountDestination"
                  - $ref: "#/components/schemas/CryptoAddressDestination"
          required:
            - data
    CreateLightningInvoiceRequest:
      type: object
      properties:
        amount:
          type: integer
          format: int64
          minimum: 100
          maximum: 500000
          description: |
            USD cents to credit the wallet when the invoice is paid. At least 100, since
            Lightning cannot carry a sub-cent payment.
          examples:
            - 2000
        currency:
          const: USD
          description: Optional and USD-only; the wallet is closed-loop USD.
      required:
        - amount
      additionalProperties: false
    LightningInvoice:
      type: object
      description: |
        A BOLT11 invoice denominated in USD. Pay `bolt11` and the wallet is credited
        `amount`; the invoice cannot be paid after `expires_at` and is never reissued.
      properties:
        id:
          type: string
          pattern: ^lni_[0-9A-HJKMNP-TV-Z]{26}$
        object:
          const: lightning_invoice
        bolt11:
          type: string
          description: The invoice to pay. Render it as a QR code.
          examples:
            - lnbc200u1p...
        payment_hash:
          type: string
          description: |
            The Lightning payment hash, echoed by the `deposit.confirmed` event. Not the
            invoice's `id`.
        amount:
          $ref: "#/components/schemas/Money"
        amount_sats:
          type:
            - integer
            - "null"
          format: int64
          description: |
            What the payer sends, as denominated at issue. Indicative only: settlement is
            the USD `amount`, never this.
        status:
          type: string
          enum:
            - pending
            - paid
            - expired
        quote_id:
          type:
            - string
            - "null"
          pattern: ^qt_[0-9A-HJKMNP-TV-Z]{26}$
          description: |
            The quote this invoice pays for, when it was minted by
            `payment_source: lightning`. Null for a wallet top-up.
        expires_at:
          type: string
          format: date-time
          description: |
            When the invoice stops being payable, exactly as encoded in `bolt11`: five
            minutes after it is minted.
        created_at:
          type: string
          format: date-time
        paid_at:
          type:
            - string
            - "null"
          format: date-time
      required:
        - id
        - object
        - bolt11
        - payment_hash
        - amount
        - amount_sats
        - status
        - quote_id
        - expires_at
        - created_at
        - paid_at
      additionalProperties: false
    CreateQuoteRequest:
      type: object
      properties:
        offer_id:
          type: string
          examples:
            - off_jp_5gb_30d
        payment_source:
          type: string
          enum:
            - wallet
            - usdt
            - usdc
            - lightning
            - bank_transfer
          description: |
            `wallet` pays from the balance and any overdraft, now or `402`. The others
            wait for funds sent to the destinations in the quote's `payment`, even when
            the balance would already cover the price.

            `lightning` mints a BOLT11 invoice for exactly this quote, returned in
            `payment.lightning`. Paying it credits the wallet in USD and settles the
            quote, so no account funding is needed first.
        network:
          type:
            - string
            - "null"
          enum:
            - bep20
            - base
            - trc20
            - null
          description: |
            The network the stablecoin will be sent on. Required with `usdt` or `usdc`
            (`400 missing_network`) and refused with any other `payment_source`: the
            quote's `payment.destinations` is the account's one address on this
            network. USDT is accepted on `bep20`, `base` and `trc20`; USDC on `base`
            and `bep20` (`400 unsupported_network`).
        iccid:
          type:
            - string
            - "null"
          pattern: ^\d{18,22}$
          description: Top up an existing eSIM instead of issuing a new one.
        destination:
          type:
            - string
            - "null"
          pattern: ^\+[1-9]\d{6,14}$
          description: |
            The phone number to top up, in E.164 form. Required for `mobile_topup`
            offers (`400 missing_destination`); malformed: `422 invalid_msisdn`.
        metadata:
          type: object
          maxProperties: 20
          additionalProperties:
            type: string
            maxLength: 500
          description: Your own key-value data, echoed back on the quote.
      required:
        - offer_id
        - payment_source
      additionalProperties: false
    Quote:
      type: object
      properties:
        id:
          type: string
          pattern: ^qt_[0-9A-HJKMNP-TV-Z]{26}$
        object:
          const: quote
        status:
          type: string
          enum:
            - awaiting_funds
            - fulfilled
            - expired
            - cancelled
          description: |
            `fulfilled` means paid and handed to fulfillment; the order carries the
            delivery outcome. `awaiting_funds` waits for the wallet to cover the price,
            until `expires_at`, then `expired`. `cancelled` was stopped by you. Only
            `awaiting_funds` ever changes.
        offer_id:
          type: string
        payment_source:
          type: string
          enum:
            - wallet
            - usdt
            - usdc
            - lightning
            - bank_transfer
        price:
          $ref: "#/components/schemas/Money"
        wallet:
          type:
            - object
            - "null"
          description: What the purchase took from the wallet, in cents.
          properties:
            debited:
              type: integer
              format: int64
            balance_after:
              type: integer
              format: int64
          required:
            - debited
            - balance_after
          additionalProperties: false
        payment:
          description: Where to send the money. Present only while `awaiting_funds`.
          oneOf:
            - $ref: "#/components/schemas/QuotePayment"
            - type: "null"
        expires_at:
          type:
            - string
            - "null"
          format: date-time
          description: |
            When an unpaid quote expires. Null for `wallet` quotes, which never wait.
            A `lightning` quote expires two minutes after its invoice's
            `payment.lightning.expires_at`: nothing can pay the invoice in that time,
            but a payment made just before it still pays the quote.
        order_id:
          type:
            - string
            - "null"
          pattern: ^ord_[0-9A-HJKMNP-TV-Z]{26}$
        metadata:
          type: object
          additionalProperties:
            type: string
        created_at:
          type: string
          format: date-time
      required:
        - id
        - object
        - status
        - offer_id
        - payment_source
        - price
        - wallet
        - payment
        - expires_at
        - order_id
        - metadata
        - created_at
      additionalProperties: false
    QuotePayment:
      type: object
      description: |
        How to pay for an awaiting quote. `rail` says which of the fields below to read.

        On `usdt` and `usdc`, send `asset_amount` of `asset` on `network` to the address
        in `destinations`; on `bank_transfer`, send `amount` to the bank account there.
        They are the account's standing destinations, so what you send is credited to
        the wallet whichever quote it was meant for.

        On `lightning`, `destinations` is empty and `lightning.bolt11` is the whole
        instruction: an invoice minted for this quote alone, for exactly `amount`, which
        cannot be reused. It can be paid until `lightning.expires_at`, five minutes after
        it is minted; show that as the deadline, not the quote's `expires_at`.
      properties:
        rail:
          type: string
          enum:
            - usdt
            - usdc
            - lightning
            - bank_transfer
          description: Which rail this quote is waiting on; matches `payment_source`.
        amount:
          $ref: "#/components/schemas/Money"
        asset:
          type:
            - string
            - "null"
          enum:
            - USDT
            - USDC
            - null
          description: The stablecoin to send. Null on Lightning and bank transfer.
        network:
          type:
            - string
            - "null"
          enum:
            - bep20
            - base
            - trc20
            - null
          description: |
            The network to send `asset` on, as the quote asked for. Null on Lightning
            and bank transfer.
        asset_amount:
          type:
            - string
            - "null"
          description: |
            `amount` in the stablecoin, which is 1:1 with USD. Null on Lightning and
            bank transfer.
          examples:
            - "14.40"
        destinations:
          type: array
          description: Empty on Lightning, which has no standing destination.
          items:
            oneOf:
              - $ref: "#/components/schemas/BankAccountDestination"
              - $ref: "#/components/schemas/CryptoAddressDestination"
        lightning:
          description: The invoice to pay. Present only when `rail` is `lightning`.
          oneOf:
            - $ref: "#/components/schemas/LightningPayment"
            - type: "null"
      required:
        - rail
        - amount
        - asset
        - network
        - asset_amount
        - destinations
        - lightning
      additionalProperties: false
    LightningPayment:
      type: object
      description: |
        A BOLT11 invoice for exactly the quote's price, denominated in USD by a
        USD-settling receiver. You pay satoshis; the wallet is credited the USD
        `amount`, whatever the rate does between issue and payment.
      properties:
        id:
          type: string
          pattern: ^lni_[0-9A-HJKMNP-TV-Z]{26}$
          description: |
            The invoice's id. In test mode, pay it with
            `POST /v1/test_helpers/lightning_invoices/{invoice_id}/pay`.
        bolt11:
          type: string
          description: The invoice to pay. Render it as a QR code.
          examples:
            - lnbc144u1p...
        payment_hash:
          type: string
          description: |
            The Lightning payment hash, which a `deposit.confirmed` event echoes. Not
            the invoice's `id`.
        amount_sats:
          type:
            - integer
            - "null"
          format: int64
          description: |
            What the payer sends, as denominated at issue. Indicative only, exactly like
            `display`: settlement is the USD `amount`, never this.
          examples:
            - 22656
        expires_at:
          type: string
          format: date-time
          description: |
            When the invoice lapses. Re-quote after that; an expired invoice cannot be
            paid and is never reissued.
      required:
        - id
        - bolt11
        - payment_hash
        - amount_sats
        - expires_at
      additionalProperties: false
    EsimProfile:
      type: object
      description: Everything needed to install the eSIM; render `lpa` as a QR code.
      properties:
        type:
          const: esim_profile
        iccid:
          type: string
        lpa:
          type: string
          description: |
            The activation string a handset installs from. Carries the SM-DP+ host and
            the matching id, in that order.
          examples:
            - LPA:1$smdp.example.com$MBGNW-2IMOY-XAKHK-CPNCJ
        activation_code:
          type: string
          description: |
            The matching id, for a customer typing the profile in by hand beside
            `smdp_address`. The same value the `lpa` carries.
        smdp_address:
          type: string
          description: |
            The SM-DP+ host for manual entry, never scheme-prefixed. Absent where the
            provider does not report one.
          examples:
            - smdp.example.com
        confirmation_code:
          type: string
          description: |
            A provider's own redemption code for its portal, where it issues one. For
            support only: it installs nothing and does not belong in an `lpa`.
        install_links:
          type: object
          description: |
            One link per device type, each opening that phone's own eSIM install
            screen with this profile filled in, for an install button. Each says which
            device it is for and what the device needs, because they differ: iOS has
            handled its link since 17.4, while Android's depends on Google Play
            services and is still rolling out.

            Open the link for the device the eSIM is going on, outside any in-app
            browser. On a desktop there is no install screen: show `lpa` as a QR code
            instead. Keep the QR code and manual entry as a fallback, and note a
            profile installs only once.

            Built from `lpa` whenever an order is retrieved, so the format may change.
            Webhook events carry the profile without them: retrieve the order.
          properties:
            ios:
              allOf:
                - $ref: "#/components/schemas/EsimInstallLink"
              description: For an iPhone or iPad.
              examples:
                - 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:
              allOf:
                - $ref: "#/components/schemas/EsimInstallLink"
              description: For an Android phone.
              examples:
                - 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
          required:
            - ios
            - android
          additionalProperties: false
      required:
        - type
        - iccid
        - lpa
        - activation_code
      additionalProperties: false
    EsimInstallLink:
      type: object
      description: A link that installs an eSIM on one type of device.
      properties:
        url:
          type: string
          format: uri
          description: Open on the device itself, outside any in-app browser.
        device:
          type: string
          description: The device type the link is for, as a label you can show.
        requires:
          type: string
          description: What that device needs for the link to work, for support.
      required:
        - url
        - device
        - requires
      additionalProperties: false
    TopupReceipt:
      type: object
      properties:
        type:
          const: topup_receipt
        destination:
          type: string
        reference:
          type: string
      required:
        - type
        - destination
        - reference
      additionalProperties: false
    Order:
      type: object
      properties:
        id:
          type: string
          pattern: ^ord_[0-9A-HJKMNP-TV-Z]{26}$
        object:
          const: order
        quote_id:
          type: string
          pattern: ^qt_[0-9A-HJKMNP-TV-Z]{26}$
        offer_id:
          type: string
        status:
          type: string
          enum:
            - pending
            - fulfilled
            - failed
        price:
          $ref: "#/components/schemas/Money"
        deliverable:
          description: Present once the order is fulfilled.
          oneOf:
            - $ref: "#/components/schemas/EsimProfile"
            - $ref: "#/components/schemas/TopupReceipt"
            - type: "null"
        failure_reason:
          type:
            - string
            - "null"
          description: |
            Why a failed order failed, as one of Tizon's own codes (`upstream_failed`
            when the provider could not deliver it). Its price is back in the wallet.
        upstream:
          type: object
          properties:
            transaction_id:
              type: string
              description: The id sent to the provider, which is the quote id.
          required:
            - transaction_id
          additionalProperties: false
        created_at:
          type: string
          format: date-time
        resolved_at:
          type:
            - string
            - "null"
          format: date-time
      required:
        - id
        - object
        - quote_id
        - offer_id
        - status
        - price
        - deliverable
        - failure_reason
        - upstream
        - created_at
        - resolved_at
      additionalProperties: false
    Deposit:
      type: object
      description: |
        Money that arrived through one of the account's funding destinations. Credited
        in USD: stablecoins 1:1, bank transfers at the amount the bank provider reports.
      properties:
        id:
          type: string
          pattern: ^dep_[0-9A-HJKMNP-TV-Z]{26}$
        object:
          const: deposit
        rail:
          type: string
          enum:
            - crypto
            - lightning
            - bank_transfer
        status:
          type: string
          enum:
            - detected
            - credited
          description: |
            `detected`: seen but not yet confirmed, counted in the wallet's
            `pending_credit`. `credited`: in the balance. Bank transfers and Lightning
            payments arrive credited.
        amount:
          $ref: "#/components/schemas/Money"
        asset:
          type:
            - string
            - "null"
          enum:
            - USDT
            - USDC
            - null
          description: Null for bank transfers.
        network:
          type:
            - string
            - "null"
          enum:
            - bep20
            - base
            - trc20
            - null
          description: Null for bank transfers.
        raw_amount:
          type:
            - string
            - "null"
          description: The on-chain amount as a decimal string. Null for bank transfers.
          examples:
            - "50.00"
        tx_hash:
          type:
            - string
            - "null"
        reference:
          type:
            - string
            - "null"
          description: The narration the sender gave a bank transfer, if any.
        received:
          description: |
            What actually arrived when a bank transfer was not in USD, for display. The
            credit is `amount`.
          oneOf:
            - $ref: "#/components/schemas/ReceivedAmount"
            - type: "null"
        created_at:
          type: string
          format: date-time
          description: When the deposit was first seen.
        credited_at:
          type:
            - string
            - "null"
          format: date-time
      required:
        - id
        - object
        - rail
        - status
        - amount
        - asset
        - network
        - raw_amount
        - tx_hash
        - reference
        - received
        - created_at
        - credited_at
      additionalProperties: false
    ReceivedAmount:
      type: object
      properties:
        amount:
          type: string
          description: Decimal string in `currency`.
          examples:
            - "80000.00"
        currency:
          type: string
          pattern: ^[A-Z]{3}$
          examples:
            - NGN
        rate:
          type: string
          description: The provider's rate, as a decimal string.
          examples:
            - "1600.00"
      required:
        - amount
        - currency
        - rate
      additionalProperties: false
    DepositPage:
      allOf:
        - $ref: "#/components/schemas/ListPage"
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: "#/components/schemas/Deposit"
          required:
            - data
    SimulateDepositRequest:
      type: object
      properties:
        amount:
          type: integer
          minimum: 1
          maximum: 10000000
          description: Cents. Stablecoins credit 1:1, so 5000 is 50.00 USDT.
          examples:
            - 5000
        asset:
          type: string
          enum:
            - USDT
            - USDC
        network:
          type: string
          enum:
            - bep20
            - base
            - trc20
          description: USDC is not accepted on `trc20` (`400 unsupported_network`).
        status:
          type: string
          enum:
            - detected
            - confirmed
          default: confirmed
          description: |
            `confirmed` credits the wallet now. `detected` leaves the deposit pending
            until `POST /v1/test_helpers/deposits/{deposit_id}/confirm`.
      required:
        - amount
        - asset
        - network
      additionalProperties: false
    SimulateBankTransferRequest:
      type: object
      properties:
        amount:
          type: integer
          minimum: 1
          maximum: 10000000
          description: USD cents credited.
          examples:
            - 5000
        reference:
          type: string
          minLength: 1
          maxLength: 140
          description: The sender's narration.
      required:
        - amount
      additionalProperties: false
    CompleteOrderRequest:
      type: object
      properties:
        outcome:
          type: string
          enum:
            - fulfilled
            - failed
        failure_reason:
          type: string
          pattern: ^[a-z][a-z0-9_]{0,63}$
          description: Only with `failed`. Defaults to `upstream_declined`.
      required:
        - outcome
      additionalProperties: false
    RegisterWebhookEndpointRequest:
      type: object
      properties:
        url:
          type: string
          description: An https URL, publicly reachable, at most 2048 characters.
          examples:
            - https://api.example.com/tizon/webhooks
        description:
          type: string
          maxLength: 500
          description: Your own label for this endpoint.
        enabled_events:
          type: array
          minItems: 1
          maxItems: 50
          default:
            - "*"
          description: |
            Event types to deliver, or `['*']` for every type, including ones added
            later. An unknown type is `400 unknown_event_type`.
          items:
            type: string
            examples:
              - order.fulfilled
      required:
        - url
      additionalProperties: false
    WebhookEndpoint:
      type: object
      properties:
        id:
          type: string
          pattern: ^we_[0-9A-HJKMNP-TV-Z]{26}$
        object:
          const: webhook_endpoint
        url:
          type: string
        description:
          type:
            - string
            - "null"
        enabled_events:
          type: array
          items:
            type: string
        status:
          type: string
          enum:
            - active
            - disabled
            - deleted
          description: |
            `disabled` means Tizon stopped delivering after sustained failures;
            `disabled_reason` says why.
        disabled_reason:
          type:
            - string
            - "null"
        secret:
          type: string
          pattern: ^whsec_[A-Za-z0-9_-]+$
          description: |
            Present only in the response that created or rotated it. Never stored in a
            readable form and never returned again.
        last_success_at:
          type:
            - string
            - "null"
          format: date-time
        last_failure_at:
          type:
            - string
            - "null"
          format: date-time
        created_at:
          type: string
          format: date-time
      required:
        - id
        - object
        - url
        - description
        - enabled_events
        - status
        - disabled_reason
        - last_success_at
        - last_failure_at
        - created_at
      additionalProperties: false
    WebhookEndpointList:
      allOf:
        - $ref: "#/components/schemas/ListPage"
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: "#/components/schemas/WebhookEndpoint"
          required:
            - data
    Event:
      type: object
      description: |
        The envelope delivered to your endpoint, and what the event log returns.
      properties:
        id:
          type: string
          pattern: ^evt_[0-9A-HJKMNP-TV-Z]{26}$
          description: Stable across retries and replays. Dedupe on it.
        object:
          const: event
        type:
          type: string
          description: |
            `ping`, `deposit.detected`, `deposit.confirmed`, `wallet.credited`,
            `wallet.debited`, `wallet.overdraft_used`, `wallet.overdue`,
            `quote.awaiting_funds`, `quote.fulfilled`, `quote.expired`,
            `order.fulfilled`, `order.failed`, `credit.updated`, `payout.succeeded`,
            `payout.failed`. More types may be added; treat this as an open enum.
          examples:
            - order.fulfilled
        created_at:
          type: string
          format: date-time
        livemode:
          type: boolean
          description: False for events from a test key.
        data:
          type: object
          description: |
            `object` is the resource as it was when the event happened: an `Order` for
            `order.*`, a `Quote` for `quote.*`, a `Deposit` for `deposit.*`, a wallet
            `ledger_entry` for the other `wallet.*` events, the `WalletAging` for
            `wallet.overdue`, the `Account` for `credit.updated`, the `Payout` for
            `payout.*`, and the endpoint itself for `ping`. `wallet.overdue` fires once when the oldest open debit
            passes its terms; `credit.updated` fires when terms change and when the
            account falls overdue or recovers.
          properties:
            object:
              type: object
          required:
            - object
      required:
        - id
        - object
        - type
        - created_at
        - livemode
        - data
      additionalProperties: false
    EventPage:
      allOf:
        - $ref: "#/components/schemas/ListPage"
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: "#/components/schemas/Event"
          required:
            - data
    ReplayEventRequest:
      type: object
      properties:
        webhook_endpoint_id:
          type: string
          pattern: ^we_[0-9A-HJKMNP-TV-Z]{26}$
          description: |
            Replay to this endpoint only. Omit to replay to every endpoint subscribed
            to the event's type.
      additionalProperties: false
    WebhookDelivery:
      type: object
      description: One endpoint's copy of one event, and how it went.
      properties:
        id:
          type: string
          pattern: ^whd_[0-9A-HJKMNP-TV-Z]{26}$
        object:
          const: webhook_delivery
        event_id:
          type: string
          pattern: ^evt_[0-9A-HJKMNP-TV-Z]{26}$
        event_type:
          type: string
        webhook_endpoint_id:
          type: string
          pattern: ^we_[0-9A-HJKMNP-TV-Z]{26}$
        status:
          type: string
          enum:
            - pending
            - succeeded
            - failed
            - cancelled
          description: |
            `pending` is still being retried; `failed` gave up after about a day and is
            a dead letter; `cancelled` means the endpoint was deleted or disabled before
            the delivery landed.
        attempts:
          type: integer
          description: How many times it has been tried.
        last_status_code:
          type:
            - integer
            - "null"
          description: |
            Null when nothing answered at all: a timeout, a refusal, bad TLS.
        last_error:
          type:
            - string
            - "null"
        recent_attempts:
          type: array
          description: Newest first, up to ten.
          items:
            type: object
            properties:
              attempt:
                type: integer
              outcome:
                type: string
                enum:
                  - succeeded
                  - failed
              status_code:
                type:
                  - integer
                  - "null"
              error:
                type:
                  - string
                  - "null"
              latency_ms:
                type: integer
              at:
                type: string
                format: date-time
            required:
              - attempt
              - outcome
              - status_code
              - error
              - latency_ms
              - at
            additionalProperties: false
        created_at:
          type: string
          format: date-time
        completed_at:
          type:
            - string
            - "null"
          format: date-time
      required:
        - id
        - object
        - event_id
        - event_type
        - webhook_endpoint_id
        - status
        - attempts
        - last_status_code
        - last_error
        - recent_attempts
        - created_at
        - completed_at
      additionalProperties: false
    WebhookDeliveryPage:
      allOf:
        - $ref: "#/components/schemas/ListPage"
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: "#/components/schemas/WebhookDelivery"
          required:
            - data
  responses:
    BadRequest:
      description: |
        The request is malformed or refers to something unusable. Codes include
        `invalid_request`, `unknown_parameter`, `missing_destination`,
        `offer_unavailable`, `unsupported_payment_source`, `missing_network`,
        `unsupported_network`, `idempotency_key_required`, `invalid_idempotency_key`,
        `invalid_token`, `invalid_query_parameter`, `invalid_webhook_payload`,
        `unsupported_display_currency`, `invalid_webhook_url`, `unknown_event_type`,
        `unknown_journal_entry`, `invalid_lightning_address`, `invalid_crypto_address`,
        `adjustment_too_large`,
        `confirmation_mismatch` (closing an account whose `confirm_account_id` does not
        repeat the one in the path).
      headers:
        Request-Id:
          $ref: "#/components/headers/RequestId"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    Unauthorized:
      description: |
        The API key is missing or invalid (`invalid_api_key`), a webhook's signature
        did not verify (`invalid_signature`), an internal route was called without the
        ops key (`invalid_admin_key`), or a dashboard session is missing, expired or
        signed out (`invalid_session`). `invalid_credentials` answers a failed
        dashboard sign-in. A closed account's keys and sessions are all revoked, and
        are refused the same way should one ever be presented.
      headers:
        Request-Id:
          $ref: "#/components/headers/RequestId"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    PaymentRequired:
      description: |
        The wallet cannot cover the purchase, or a hand debit: `insufficient_funds`
        (with `shortfall`) or `overdraft_limit_exceeded`. Or the Revenue Centre cannot
        cover what was asked of it: `nothing_to_transfer`, `amount_above_balance`,
        `nothing_to_pay_out`, `amount_above_payable`.
      headers:
        Request-Id:
          $ref: "#/components/headers/RequestId"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    Forbidden:
      description: |
        The account may not do this. Codes include `test_mode_only`,
        `overdraft_not_enabled`, `withdrawal_not_supported`, `account_overdue`, and
        `account_suspended`, which answers every non-read request while an account is
        suspended, `live_access_disabled`, which answers every non-read live request
        (a live key, or a dashboard request with `mode=live`) while Tizon has switched
        the account's live access off, and `live_access_required` when a live key is
        asked for before KYB is approved or while live access is switched off.
      headers:
        Request-Id:
          $ref: "#/components/headers/RequestId"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    NotFound:
      description: |
        No such resource, or not yours: `not_found`, `quote_not_found`,
        `order_not_found`, `wallet_not_found`, `deposit_not_found`,
        `offer_not_found`, `webhook_endpoint_not_found`, `event_not_found`,
        `break_not_found`, `close_not_found`, `account_not_found`,
        `api_key_not_found`, `payout_not_found`, `zendit_send_not_found`,
        `esim_not_found`.
      headers:
        Request-Id:
          $ref: "#/components/headers/RequestId"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    Conflict:
      description: |
        The request conflicts with current state: `quote_expired`, `already_fulfilled`,
        `idempotency_key_reuse_mismatch`, `deposit_already_credited`,
        `order_already_resolved`, `webhook_url_in_use`, `break_already_resolved`,
        `close_already_signed_off`, `day_not_over`, `overdraft_limit_below_used`,
        `kyb_already_pending`, `no_kyb_to_decide`, `email_taken`,
        `payout_address_required`, `payout_not_awaiting_approval`, `payout_unfunded` (ops approving a payout
        Tizon cannot yet pay from what it holds), `zendit_send_unfunded`,
        `treasury_reference_conflict`, `account_closed` (the account is closed, which
        is final: it cannot be closed again, suspended, restored, switched or given
        keys), and `account_not_settled` (an account cannot close while it has live
        money or live business outstanding; `unsettled` says what).
      headers:
        Request-Id:
          $ref: "#/components/headers/RequestId"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    Unprocessable:
      description: |
        Well-formed but not actionable: `iccid_not_topup_eligible`, `invalid_msisdn`,
        `payout_below_minimum`.
      headers:
        Request-Id:
          $ref: "#/components/headers/RequestId"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    TooManyRequests:
      description: |
        Too many requests: `too_many_requests` from a rate limit, or
        `too_many_attempts` while a dashboard sign-in lock is in force. Wait for
        `Retry-After` seconds. Limits are per API key or session where there is one,
        and per address on sign-up, sign-in and the password and verification links.
        Provider webhooks are never rate limited.
      headers:
        Request-Id:
          $ref: "#/components/headers/RequestId"
        Retry-After:
          $ref: "#/components/headers/RetryAfter"
        RateLimit-Limit:
          $ref: "#/components/headers/RateLimitLimit"
        RateLimit-Remaining:
          $ref: "#/components/headers/RateLimitRemaining"
        RateLimit-Reset:
          $ref: "#/components/headers/RateLimitReset"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    ServiceUnavailable:
      description: |
        Temporarily unable to serve the request (`service_unavailable`), payouts by
        that method are switched off on Tizon's side (`payouts_unavailable`), or there
        is no Quidax treasury sub-account to send to Zendit from
        (`zendit_sends_unavailable`).
      headers:
        Request-Id:
          $ref: "#/components/headers/RequestId"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    BadGateway:
      description: |
        An upstream provider failed, and nothing was created or charged:
        `fulfillment_unavailable` (offers cannot be priced or bought, or an eSIM's
        usage read, right now),
        `rail_unavailable` (a payment rail cannot give an address or an invoice right
        now, or quote a payout's network fee), `topup_provider_error`.
      headers:
        Request-Id:
          $ref: "#/components/headers/RequestId"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
