@tuwaio/payments-sdk 0.0.0-stage → 0.0.1

package/dist/checkout-C05-kSiE.d.cts

@@ -0,0 +1,1616 @@
+import { StoreApi } from 'zustand/vanilla';
+
+/**
+ * @file Request and response types of the Payments API (`/v1/payments`): invoices, refunds, documents, quotes,
+ * payment methods and subscriptions, as the Quasar engine takes and returns them.
+ */
+/** Fiat currency of an invoice or a subscription plan. */
+type PaymentsCurrency = 'USD' | 'EUR';
+/** Language of an invoice, its documents and its emails. */
+type InvoiceLocale = 'en' | 'uk' | 'zh-CN' | 'es' | 'it' | 'de';
+/**
+ * VAT category of a line (EN 16931 UNCL5305): `S` standard rate, `Z` zero rated, `E` exempt (needs
+ * `taxExemptionReason`), `AE` reverse charge, `K` intra-community supply, `G` export outside the EU, `O` outside the
+ * scope of VAT.
+ */
+type TaxCategory = 'S' | 'Z' | 'E' | 'AE' | 'K' | 'G' | 'O';
+/**
+ * State of an invoice: `open` until paid, `processing` while a payment is being confirmed, then `paid`, `underpaid`
+ * (the buyer may top it up), `held` (the merchant releases or refunds it), `partially_refunded`, `refunded`, or
+ * `expired`/`cancelled` without a payment.
+ */
+type InvoiceStatus = 'open' | 'processing' | 'paid' | 'underpaid' | 'held' | 'partially_refunded' | 'refunded' | 'expired' | 'cancelled';
+/** Whether an invoice or subscription belongs to the live or the test app: the key that issued it decides. */
+type PaymentsEnvironment = 'live' | 'test';
+/**
+ * The buyer of an invoice (EN 16931 BT-44 to BT-55). Every field is optional; an e-invoice is issued only when the
+ * fields it needs are there (otherwise the invoice says what was missing in `eInvoiceSkipped`).
+ */
+interface Buyer {
+    /** Name of the person or the company. */
+    name?: string;
+    /** Email address; Quasar Cloud sends the invoice, receipt and credit notes to it. */
+    email?: string;
+    /** First address line. */
+    addressLine1?: string;
+    /** Second address line. */
+    addressLine2?: string;
+    /** Postal code. */
+    postalCode?: string;
+    /** City. */
+    city?: string;
+    /** Region or state. */
+    region?: string;
+    /** ISO 3166-1 alpha-2 country code, for example `DE`. */
+    country?: string;
+    /** Company registration number. */
+    registrationNumber?: string;
+    /** VAT or other tax ID; required for a reverse-charge invoice. */
+    taxId?: string;
+    /** Your ID of the buyer; filter invoices by it with `externalId`. */
+    externalId?: string;
+}
+/** How a refund is priced: at today's price of the invoice amount, or the whole payment as received. */
+type RefundMode = 'fiat_value' | 'exact_received';
+/** What {@link PaymentsModule.refund} takes. */
+interface RefundParams {
+    /** Amount in the invoice currency; everything left when omitted. Leave it out with `exact_received`. */
+    amount?: string;
+    /** `fiat_value` (default) or `exact_received`. */
+    mode?: RefundMode;
+    /** Why; printed on the credit note. */
+    reason?: string;
+}
+/** A refund. You send it from your wallet; Quasar verifies the transaction and issues the credit note. */
+interface Refund {
+    /** Refund ID. */
+    id: string;
+    /** Always `refund`. */
+    object: 'refund';
+    /** The invoice. */
+    invoiceId: string;
+    /** `requested` (waits for its transaction), `submitted`, `confirmed` or `failed`. */
+    status: 'requested' | 'submitted' | 'confirmed' | 'failed';
+    /** Amount in the invoice currency. */
+    amount: string;
+    /** Invoice currency. */
+    currency: string;
+    /** How it was priced. */
+    mode: RefundMode;
+    /** Token amount to send, in base units. */
+    cryptoAmount: string;
+    /** CAIP-19 asset to send. */
+    assetId: string;
+    /** CAIP-2 chain to send on. */
+    chainId: string;
+    /** The payer's address: refunds go back to it. */
+    to: string;
+    /** The refund transaction, once submitted. */
+    txHash: string | null;
+    /** The address it was sent from. */
+    from: string | null;
+    /** Why. */
+    reason: string | null;
+    /** Why it failed. */
+    failureReason: string | null;
+    /** The transaction that took the place of a cancelled one, when Quasar knows it. */
+    replacedBy?: string | null;
+    /** Its credit note, once confirmed; none for a held transfer or a payment that stayed on a corrected invoice. */
+    creditNoteNumber: string | null;
+    /** The held transfer it returns to its sender ({@link HeldTransfer}), or `null` for a refund of the invoice. */
+    heldTransfer: string | null;
+    /** When it was asked for. */
+    createdAt: string;
+    /** When it last changed; absent from an engine that does not send it yet. */
+    updatedAt?: string | null;
+    /** When it was confirmed. */
+    confirmedAt: string | null;
+}
+/** The answer of {@link PaymentsModule.refund}: the refund and what to send where. */
+interface RefundStart {
+    /** The refund, `requested`. */
+    refund: Refund;
+    /** The transfer to make from your wallet, then pass its hash to {@link PaymentsModule.submitRefund}. */
+    instructions: {
+        /** CAIP-2 chain. */
+        chainId: string;
+        /** CAIP-19 asset. */
+        assetId: string;
+        /** Recipient: the payer. */
+        to: string | null;
+        /** Amount in base units. */
+        amount: string;
+        /** Decimals of the token. */
+        decimals: number;
+        /** Symbol of the token. */
+        symbol: string;
+    };
+}
+/**
+ * What a refund would send, as {@link PaymentsModule.previewRefund} returns it. A requested refund holds its amount until
+ * it is sent, so look before asking: the same amount in the invoice currency sends a different number of tokens once a
+ * volatile asset has moved.
+ */
+interface RefundPreview {
+    /** The amount in the invoice currency. */
+    amount: string;
+    /** The invoice currency. */
+    currency: string;
+    /** What the refund would send now, in base units. */
+    cryptoAmount: string;
+    /** Symbol of the token. */
+    symbol: string;
+    /** Decimals of the token. */
+    decimals: number;
+    /** What the payment brought, in base units. */
+    received: string | null;
+    /** What this amount was worth in tokens at the rate of the payment, in base units; `null` for `exact_received`. */
+    atPaymentRate: string | null;
+    /** Whether `exact_received` would be taken now: it returns the whole invoice, so nothing may be refunded yet. */
+    exactPossible: boolean;
+}
+/** What {@link PaymentsModule.submitRefund} takes. */
+interface SubmitRefundParams {
+    /** The refund transaction (hash or Solana signature). */
+    txHash: string;
+    /** Your wallet it was sent from. */
+    from: string;
+}
+/** The billing period unit of a subscription. */
+type SubscriptionInterval = 'day' | 'week' | 'month' | 'year';
+/**
+ * State of a subscription: `trialing`, `incomplete` (its first or resumed period is unpaid), `active`, `past_due`,
+ * `paused`, `canceled`, `ended`.
+ */
+type SubscriptionStatus = 'trialing' | 'incomplete' | 'active' | 'past_due' | 'paused' | 'canceled' | 'ended';
+/** The automatic-charge permission a buyer granted (ERC-7715), without its context. */
+interface SubscriptionPermission {
+    /** Whether it can still be charged. */
+    status: 'active' | 'revoked' | 'expired';
+    /** CAIP-2 chain. */
+    chainId: string | null;
+    /** The payment method. */
+    methodId: string | null;
+    /** The buyer's CAIP-10 account. */
+    payer: string | null;
+    /** The token. */
+    tokenAddress: string | null;
+    /** Amount per window, in base units. */
+    periodAmount: string | null;
+    /** Window length. */
+    periodSeconds: number;
+    /** When the first window starts. */
+    startsAt: string | null;
+    /** When it expires. */
+    expiresAt: string | null;
+    /** When it was granted. */
+    grantedAt: string | null;
+    /** When it was revoked. */
+    revokedAt: string | null;
+}
+
+/**
+ * @file Errors of the Quasar SDK: the error a failed request throws, and how an `ofetch` error becomes one.
+ */
+/** A field of a request the API refused, and why: `path` names it with dots (`buyer.country`). */
+interface QuasarRequestIssue {
+    /** The field, for example `buyer.country`. */
+    path: string;
+    /** Why it was refused. */
+    message: string;
+}
+
+/**
+ * @file Types of the checkout API (`/v1/payments/checkout/:token`): what the buyer's page reads and sends.
+ */
+
+/** A line of the invoice as the checkout shows it; amounts are decimal strings, `netMinor` in cents. */
+interface CheckoutLine {
+    /** What is sold. */
+    name: string;
+    /** Details under the name. */
+    description?: string;
+    /** Quantity. */
+    quantity: string;
+    /** Price of one unit. */
+    unitPrice: string;
+    /** VAT category. */
+    taxCategory: TaxCategory;
+    /** VAT rate in percent. */
+    taxRate: string;
+    /** Net amount of the line in minor units (cents). */
+    netMinor: string;
+}
+/** The invoice the checkout token opens. */
+interface CheckoutInvoice {
+    /** Invoice ID. */
+    id: string;
+    /** Series number; `null` while its document waits for the buyer details. */
+    number: string | null;
+    /** State of the invoice. */
+    status: InvoiceStatus;
+    /** Live or test: a test invoice is paid on test networks. */
+    environment: PaymentsEnvironment | null;
+    /** Currency. */
+    currency: PaymentsCurrency;
+    /** Total to pay, as a decimal. */
+    total: string | number;
+    /** Total in minor units (cents). */
+    totalMinor: string | null;
+    /** The lines. */
+    lineItems: CheckoutLine[];
+    /** Language of the page and of the documents still to be issued. */
+    locale: InvoiceLocale | null;
+    /** When it stops being payable. */
+    dueAt: string | null;
+    /** Where to send the buyer after paying (http(s) only). */
+    successUrl: string | null;
+    /** Where to send a buyer who gives up (http(s) only). */
+    cancelUrl: string | null;
+    /** Base units of the quoted asset received so far: an underpaid invoice asks for the rest. */
+    amountPaid: string | null;
+    /**
+     * Whether the rest of an underpaid invoice can be quoted now ({@link CheckoutQuote.amountDue}): its method is still on,
+     * something is left and it is not past the due date. `false` for an invoice in any other state.
+     */
+    restPayable: boolean;
+    /** The seller closed the invoice before its due date, with part of its payment received. */
+    closed?: boolean;
+    /**
+     * The wallet that paid an underpaid invoice first, the only one that pays the rest: an address, or a CAIP-10 account.
+     * `null` for an invoice in any other state.
+     */
+    originWallet: string | null;
+    /**
+     * Why a payment waits for, or was flagged to, the seller ({@link CheckoutReview}); `null` when none does.
+     */
+    review: CheckoutReview | null;
+    /** What was refunded, in minor units (cents) of the invoice currency. */
+    refundedTotalMinor: string | null;
+    /** When the invoice was paid; `null` until then, and absent from an engine that does not send it yet. */
+    paidAt?: string | null;
+    /**
+     * Payments of the invoice handed over and still on their way, whoever handed them over: tracked transactions
+     * settlement has not verified or rejected yet (recorded within the last 25 minutes: Quasar stops counting a stuck
+     * one), gasless relays still sending (within 35 minutes), and claims of this invoice on a transaction another invoice
+     * handed over first that Quasar has not decided yet (within 25 minutes). Quasar versions before the payment grace
+     * (October 2026) leave it out.
+     */
+    pendingPayments?: number;
+    /**
+     * Every key the page may know a failed payment by, latest first: the `txKey` of a rejected transaction, the hash the
+     * checkout handed over when a sped-up transaction replaced it, and the `userOpHash` of a gasless relay. Left out like
+     * `pendingPayments`; read {@link CheckoutInvoice.rejectedPayments} for why they failed.
+     */
+    rejectedTxKeys?: string[];
+    /**
+     * The payments that failed, latest first (at most 10), with the reason and whether the buyer may pay again. Quasar
+     * versions before October 28, 2026 leave it out.
+     */
+    rejectedPayments?: CheckoutRejectedPayment[];
+    /**
+     * While the invoice is payable and a payment Quasar learned of before `dueAt` is on its way: until when the invoice
+     * waits for it (`dueAt` plus 30 minutes), so the page can say that the payment was sent in time. `null` otherwise;
+     * left out like `rejectedPayments`.
+     */
+    paymentCountsUntil?: string | null;
+    /**
+     * Payments of the invoice that may still arrive, with no time limit: tracked transactions neither confirmed nor
+     * rejected for good (also one stuck past the 25 minutes `pendingPayments` counts, and one whose tracker lost sight of
+     * it, `not_found`, `timeout` or `replaced`, which Quasar reads again for 24 hours), gasless relays still sending, and
+     * claims of this invoice on a transaction another invoice handed over first that Quasar has not decided yet. While it
+     * is above `0` the page offers no plain second payment and never says that nothing was charged. Quasar versions
+     * before October 29, 2026 leave it out.
+     */
+    unresolvedPayments?: number;
+    /**
+     * Every key (`txKey`, hash, the hash a sped-up transaction replaced, a relay's `userOpHash`) of the payments that
+     * count as sent in time: Quasar learned of them before `dueAt` (all of them when the invoice has none); at most the
+     * latest 20 transactions and 10 relays. Match the page's own keys against it instead of the browser clock. Left out
+     * like `unresolvedPayments`.
+     */
+    onTimeTxKeys?: string[];
+    /**
+     * The invoice that replaced this one after the seller corrected it: its number and, while it can be paid, its
+     * checkout token.
+     */
+    replacedBy: {
+        number: string | null;
+        checkoutToken: string | null;
+    } | null;
+    /** The subscription period this invoice bills; `null` for a one-off invoice. */
+    subscription: CheckoutSubscription | null;
+}
+/**
+ * Why a payment of a `held` (or flagged) invoice waits for the seller, as {@link CheckoutInvoice.review} says it:
+ *
+ * - `screening`: the sender did not pass the seller's AML check after paying; no details reach the buyer.
+ * - `late`: it arrived after the invoice expired or was cancelled; the seller accepts or returns it.
+ * - `overpaid`: more arrived than the invoice asks for, and the seller looks at it.
+ * - `quote_expired`: it arrived after its locked quote expired, in an asset whose price moved; the seller accepts or
+ *   returns it.
+ *
+ * A transfer Quasar could tie to no invoice never holds the invoice: it is a rejected payment with `held`
+ * ({@link CheckoutRejectedPayment.held}), which the seller returns to the wallet that sent it.
+ */
+type CheckoutReview = {
+    reason: 'screening' | 'late' | 'overpaid' | 'quote_expired';
+};
+/** A payment of the invoice that failed, as the checkout lists it ({@link CheckoutInvoice.rejectedPayments}). */
+interface CheckoutRejectedPayment {
+    /** The transaction's `txKey`, or the `userOpHash` of a gasless relay that failed before it had a transaction. */
+    txKey: string;
+    /**
+     * Why: `reverted`, `cancelled`, `expired` (a Solana blockhash), `no_matching_transfer` (a wrong amount, asset or
+     * recipient), `tx_already_used` (the transaction pays another invoice of the merchant: the one the wallet that sent
+     * it confirmed, or whose mark it carries, also when this invoice's page handed it over first or claimed it; with
+     * `held`, another invoice holds it for a refund only and it pays none),
+     * `reference_missing`, `too_early`, `not_found` (the network never returned the transaction), `timeout` (no receipt
+     * in time), `replaced`, `payer_mismatch` (a transfer from another wallet to an invoice paid or held already; one to a
+     * payable invoice is held for a refund only: {@link CheckoutReview}), `payer_unconfirmed` (the same from a wallet that
+     * never confirmed the invoice: it pays no invoice; final; a refund only when held, a transfer credited to another
+     * invoice is `tx_already_used`), `native_from_contract_unverifiable`, `invoice_not_payable` (a transfer to an invoice paid, held or refunded
+     * already), `below_minimum` (worth less than one minor unit of the invoice currency), `too_many_transfers` (the
+     * invoice holds 10 transfers for the merchant already), `too_many_parts` (it took 10 parts already) and
+     * `quote_changed` (a relay landed after it was quoted another way), both with `held`, `settlement_failed` (the network confirmed the transaction, but Quasar has not recorded it yet: not final,
+     * never a second payment, the buyer contacts the merchant; Quasar settles it again daily for 30 days after it learned
+     * of it, while `rechecked`), `unresolved_after_24h` (no result seen on chain within 24 hours: only a transaction
+     * Quasar read again after that day and the network does not have), a relay's reason (`user_operation_lost`…), or
+     * `transaction_failed` when Quasar does not know.
+     */
+    reason: string;
+    /**
+     * Whether the transaction can never pay the invoice, so the buyer may pay again. When `false` (`not_found`,
+     * `timeout`, `replaced`…) the money may still be on its way or already with the merchant: the buyer checks the wallet
+     * before paying again. A final rejection may still have moved money: read `movedMoney`.
+     */
+    final: boolean;
+    /** The relay operation the transaction came from, which the page knows when the relay answered `sending`. */
+    userOpHash?: string;
+    /** The transaction the checkout handed over, when this one replaced it (a payment sped up in the wallet). */
+    original?: string;
+    /**
+     * `true` when the transaction succeeded on chain without paying the invoice (`no_matching_transfer`,
+     * `reference_missing`, `too_early`, `tx_already_used`, `payer_mismatch`, `payer_unconfirmed`,
+     * `native_from_contract_unverifiable`, `invoice_not_payable`), or Quasar has not recorded it yet
+     * (`settlement_failed`): it may have moved money. Never say that it did not go through or that nothing was charged:
+     * say that it does not pay the invoice (for `settlement_failed`: that Quasar has not recorded it yet; for
+     * `payer_mismatch` and `payer_unconfirmed`: promise a refund only on a held invoice), and whom to contact if money
+     * left the wallet. Quasar versions before October 29, 2026 leave it out.
+     */
+    movedMoney?: true;
+    /**
+     * `true` while Quasar still reads the transaction again: a rejection for `not_found`, `timeout` or `replaced` of a
+     * payment Quasar learned of within the last 24 hours that nothing has resolved since (a payment still unresolved
+     * after the 24 hours is closed with the final reason `unresolved_after_24h`), or a `settlement_failed` one Quasar
+     * still settles again daily (for 30 days after it learned of the payment; Quasar versions before the payer proof,
+     * October 29, 2026, never mark it). Only then may the page promise that Quasar checks the payment again. Any other
+     * reason that is not `final` (a relay operation lost, `transaction_failed`, a transfer from another wallet…) is never
+     * read again: if money left the wallet, the buyer contacts the merchant with the transaction hash. Quasar versions
+     * before October 29, 2026 leave it out.
+     */
+    rechecked?: true;
+    /**
+     * `true` when Quasar records the transfer as a held transfer, which the merchant returns to the wallet that sent it:
+     * a `payer_mismatch` or `payer_unconfirmed` rejection (the invoice stays payable from the wallet that confirmed it),
+     * or a `tx_already_used` one whose transfer is held at another invoice of the merchant (`otherInvoice`; say that it is
+     * tied to another invoice, never that it pays one). Quasar versions before October 29, 2026 leave it out.
+     */
+    held?: true;
+    /** The invoice of the merchant the transaction is credited to or held on, when Quasar names it. */
+    otherInvoice?: string;
+}
+/** The subscription period an invoice bills, as the checkout shows it. */
+interface CheckoutSubscription {
+    /** State of the subscription. */
+    status: SubscriptionStatus;
+    /** Unit of a period. */
+    interval: SubscriptionInterval;
+    /** Units in a period (`3` with `month` is a quarter). */
+    intervalCount: number;
+    /** The period this invoice bills, from 1. */
+    period: number;
+    /**
+     * When the period starts; `null` for a period before the subscription was last resumed, as resuming counts the periods
+     * again from that moment.
+     */
+    periodStart: string | null;
+    /** When it ends, which is when the next one is billed; `null` like {@link CheckoutSubscription.periodStart}. */
+    periodEnd: string | null;
+    /** How many periods the subscription runs; `null` until it is cancelled. */
+    cycles: number | null;
+    /** When it ends at the latest, if set. */
+    endsAt: string | null;
+    /** Whether it ends with the current period. */
+    cancelAtPeriodEnd: boolean;
+}
+/** Who is paid and on what terms, as the checkout shows it. */
+interface CheckoutMerchant {
+    /** The name buyers know. */
+    name: string;
+    /** Website, as an http(s) link. */
+    website: string | null;
+    /** Where buyers ask for help. */
+    supportEmail: string | null;
+    /** Whether the merchant has a logo: read it from the `logo` route ({@link CheckoutState.logoUrl}). */
+    logo: boolean;
+    /** The seller as the invoice document names them. */
+    seller: {
+        legalName: string | null;
+        tradingName: string | null;
+        address: string | null;
+        country: string | null;
+        registrationNumber: string | null;
+        taxId: string | null;
+    } | null;
+    /** The merchant's terms, refund policy and privacy notice (http(s) links only). */
+    links: {
+        terms: string | null;
+        refundPolicy: string | null;
+        privacy: string | null;
+    };
+    /** A page where buyers get the token to pay, shown when the wallet has too little. */
+    fundingUrl: string | null;
+}
+/**
+ * A line the merchant asks the buyer to tick before paying, such as a request to start a service at once. The quote
+ * records the tick in the invoice's ledger and the receipt email repeats the text.
+ */
+interface CheckoutConsent {
+    /** The merchant's words, up to 500 characters, shown as they are. */
+    text: string;
+    /** Whether the buyer cannot pay without ticking it: Quasar refuses the quote with `consent_required`. */
+    required: boolean;
+}
+/** The look of the checkout the merchant chose. */
+interface CheckoutTheme {
+    /** `system` follows the buyer's device. */
+    mode: 'system' | 'light' | 'dark';
+    /** Main button and selection color (`#rrggbb`); `null` for the default. */
+    accentColor: string | null;
+}
+/** A payment method the invoice can be paid with. */
+interface CheckoutMethod {
+    /** Method ID, for {@link CheckoutState.selectMethod}. */
+    id: string;
+    /** Its name. */
+    name: string;
+    /** Token symbol. */
+    symbol: string;
+    /** CAIP-2 chain (`eip155:8453`, `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`). */
+    chainId: string;
+    /** CAIP-19 asset. */
+    assetId: string | null;
+    /** Decimals of the token. */
+    decimals: number;
+    /** `auto` when the merchant may sponsor the gas, `off` otherwise. */
+    gasless: string | null;
+    /** Marked "Popular" by the merchant. */
+    featured: boolean;
+    /** How much more the method costs than the invoice total, in basis points (`150` is 1.5 %). */
+    markupBps: number;
+    /** How much less the method costs than the invoice total, in basis points. */
+    discountBps: number;
+    /**
+     * When a payment with the method needs the paying wallet's confirmation of the invoice
+     * ({@link CheckoutState.confirmPayer}): `before_quote` (an EVM method: before the price; the quote answers
+     * `409 payer_proof_required` without it), `unless_relayed` (an EVM method the gasless relay may pay: the price comes
+     * first, the relay's EIP-3009 authorization confirms the wallet, and a transfer or a paymaster payment of it needs
+     * the confirmation first), `none` (Solana: the quote's reference ties the transfer to the invoice). Quasar versions
+     * before October 29, 2026 leave it out: no confirmation.
+     */
+    payerProof?: PayerProofNeed;
+}
+/** When a payment with a method needs the paying wallet's confirmation ({@link CheckoutMethod.payerProof}). */
+type PayerProofNeed = 'before_quote' | 'unless_relayed' | 'none';
+/**
+ * How a wallet confirmed the invoice: `eoa` (an EIP-191 signature of Quasar's message, which counts on every EVM
+ * network), `eip1271` and `eip6492` (a smart wallet's signature its contract accepted, deployed or not yet, which
+ * counts on that network only), `authorization` (the EIP-3009 authorization of the invoice's gasless relay, on every
+ * EVM network).
+ */
+type PayerProofKind = 'eoa' | 'eip1271' | 'eip6492' | 'authorization';
+/** A wallet that confirmed the invoice ({@link CheckoutView.payerProofs}). */
+interface CheckoutPayerProof {
+    /** The wallet, as a CAIP-10 account on the network it confirmed on (the EVM address checksummed). */
+    payer: string;
+    /** How it confirmed. */
+    kind: PayerProofKind;
+    /** The CAIP-2 network it confirmed on: the only one where an `eip1271` or `eip6492` confirmation counts. */
+    chainId: string;
+    /** When. */
+    confirmedAt: string;
+}
+/**
+ * What `POST payer-proof/message` answers: the exact EIP-4361 (Sign-In with Ethereum) message the wallet signs, for
+ * free and without moving funds, to confirm that it pays this invoice. Quasar builds it from the page's site (its
+ * `Origin`), the wallet, the invoice number, the seller and the total, the network, a nonce derived from the invoice and
+ * the wallet, the invoice's creation (`Issued At`) and due date (`Expiration Time`); asked twice, it is the same.
+ */
+interface PayerProofMessage {
+    /** Always `payer_proof_message`. */
+    object: 'payer_proof_message';
+    /** The wallet, as a CAIP-10 account (the EVM address checksummed). */
+    payer: string;
+    /** `true` when the wallet confirmed this invoice already (on this network, for a smart wallet): nothing to sign. */
+    proven: boolean;
+    /** The message to sign as it is, with `personal_sign` (EIP-191). */
+    message: string;
+    /** The site the message names: the host of the page that asked. */
+    domain: string;
+    /** The CAIP-2 network of the wallet. */
+    chainId: string;
+    /** The nonce of the message. */
+    nonce: string;
+    /** When the invoice was created (`Issued At`). */
+    issuedAt: string;
+    /** The invoice's due date (`Expiration Time`), `null` without one. */
+    expiresAt: string | null;
+}
+/** What `POST payer-proof` answers: the wallet's confirmation of the invoice, as Quasar recorded it. */
+interface PayerProofConfirmation {
+    /** Always `payer_proof`. */
+    object: 'payer_proof';
+    /** The wallet, as a CAIP-10 account. */
+    payer: string;
+    /** Always `true`. */
+    proven: true;
+    /** How it confirmed. */
+    kind: PayerProofKind;
+    /** The CAIP-2 network it confirmed on. */
+    chainId: string;
+    /** When. */
+    confirmedAt: string;
+}
+/** What a wallet needs to pay a locked quote: the exact amount in base units, never rounded again. */
+type PaymentInstructions = {
+    /** An EVM chain. */
+    family: 'eip155';
+    /** EVM chain ID. */
+    chainId: number;
+    /** The merchant's wallet. */
+    to: string;
+    /** The token contract, or `native`. */
+    token: string;
+    /** Amount to send, in base units. */
+    amount: string;
+    /** Decimals of the token. */
+    decimals: number;
+    /** Token symbol. */
+    symbol: string;
+} | {
+    /** Solana. */
+    family: 'solana';
+    /** CAIP-2 chain ID. */
+    chainId: string;
+    /** The merchant's wallet. */
+    to: string;
+    /** The mint, or `native` for SOL. */
+    token: string;
+    /** Amount to send, in base units. */
+    amount: string;
+    /** Decimals of the token. */
+    decimals: number;
+    /** Token symbol. */
+    symbol: string;
+    /** The Solana Pay reference key of the quote: the transfer must carry it. */
+    reference: string;
+    /** A Solana Pay transfer request, for a QR code a mobile wallet scans. */
+    solanaPayUrl: string;
+};
+/** EIP-712 typed data of an EIP-3009 transfer authorization, ready for `eth_signTypedData_v4`. */
+interface TransferAuthorizationTypedData {
+    /** The token's EIP-712 domain. */
+    domain: Record<string, unknown>;
+    /** The types, with `EIP712Domain`. */
+    types: Record<string, {
+        name: string;
+        type: string;
+    }[]>;
+    /** `TransferWithAuthorization`. */
+    primaryType: string;
+    /** The authorization: from the payer to the merchant, the quoted amount, a validity window and a nonce. */
+    message: Record<string, string>;
+}
+/**
+ * What the merchant sponsors for a quote: `relay`, an EIP-3009 authorization any wallet signs (Quasar sends the
+ * transfer), and `paymaster`, the calls a smart wallet sends with the checkout's ERC-7677 paymaster
+ * (`paymasterUrl` of the store).
+ */
+interface GaslessOffer {
+    /** Sign `typedData` and pass the signature to {@link CheckoutState.relay}. */
+    relay?: {
+        typedData: TransferAuthorizationTypedData;
+    };
+    /** Send these calls with `wallet_sendCalls` and the `paymasterService` capability set to the paymaster URL. */
+    paymaster?: {
+        calls: {
+            to: string;
+            value: string;
+            data: string;
+        }[];
+    };
+}
+/** A locked quote: the price for this payer, valid until `expiresAt`. */
+interface CheckoutQuote {
+    /** Always `checkout_quote`. */
+    object: 'checkout_quote';
+    /** The payment method. */
+    methodId: string;
+    /** CAIP-10 account the quote was locked to; `null` for a Solana Pay QR quote. */
+    payer: string | null;
+    /** Token amount the whole invoice costs at the quoted rate, in base units. */
+    cryptoAmountExpected: string;
+    /**
+     * Token amount that must still arrive, in base units: {@link CheckoutQuote.cryptoAmountExpected}, or on an underpaid
+     * invoice what is left of it after what arrived, at the same rate.
+     */
+    amountDue: string;
+    /** Token amount the buyer sends: {@link CheckoutQuote.amountDue} grossed up for a transfer fee, in base units. */
+    amountToSend: string;
+    /**
+     * On the quote of a rest in an asset that moves against the invoice currency: until when its rate holds. The quote may
+     * run longer; a payment after this time waits for the merchant to accept or refund it (`review.reason`
+     * `quote_expired`). `null` otherwise.
+     */
+    rateHeldUntil: string | null;
+    /** The token's transfer fee, when it takes one. */
+    transferFee: {
+        bps: number;
+        maxFee: string | null;
+        source: 'contract' | 'method';
+    } | null;
+    /** Decimals of the token. */
+    decimals: number;
+    /** Token symbol. */
+    symbol: string;
+    /** When it was locked. */
+    lockedAt: string | null;
+    /** When it expires; ask for a new quote after that. */
+    expiresAt: string | null;
+    /** The Solana Pay reference key. */
+    reference: string | null;
+    /** Price rounds used, as evidence. */
+    rates: unknown;
+    /** Markup of the method in basis points. */
+    markupBps: number;
+    /** Discount of the method in basis points. */
+    discountBps: number;
+    /** What the wallet sends. */
+    instructions: PaymentInstructions;
+    /** What the merchant sponsors, or `null`: the buyer pays the gas. */
+    gasless: GaslessOffer | null;
+    /**
+     * Whether the quoted wallet confirmed the invoice ({@link CheckoutState.confirmPayer}): `required` on an EVM method,
+     * `proven` once it did (`kind` says how). An EVM quote without the confirmation exists only for a method the gasless
+     * relay may pay: a transfer or a paymaster payment from that wallet needs the confirmation first, or Quasar credits it
+     * to no invoice and the merchant returns it. Quasar versions before October 29, 2026 leave it out.
+     */
+    payerProof?: {
+        required: boolean;
+        proven: boolean;
+        kind: PayerProofKind | null;
+    };
+}
+/** The ERC-7715 `wallet_grantPermissions` request of a subscription with automatic charges. */
+interface PermissionRequest {
+    /** Chain as hex. */
+    chainId: string;
+    /** The app's collector account, which redeems the permission. */
+    to: string;
+    /** A periodic ERC-20 allowance. */
+    permission: {
+        type: 'erc20-token-periodic';
+        isAdjustmentAllowed: boolean;
+        data: {
+            tokenAddress: string;
+            periodAmount: string;
+            periodDuration: number;
+            startTime: number;
+            justification: string;
+        };
+    };
+    /** Expiry, payee and redeemer rules. */
+    rules: {
+        type: string;
+        data: unknown;
+    }[];
+}
+/** For a subscription with automatic charges: whether the page should ask the wallet for the permission. */
+type AutoChargeOffer = {
+    /** Ask the wallet with `request`, then pass its answer to `grantPermission` of the checkout store. */
+    status: 'available';
+    /** The method the charges use. */
+    methodId: string;
+    /** The request for `wallet_grantPermissions`. */
+    request: PermissionRequest;
+} | {
+    /** Already granted. */
+    status: 'active';
+    /** The permission. */
+    permission: SubscriptionPermission | null;
+    /**
+     * The transaction that revokes it, for the wallet that granted it to send and pay for; then
+     * {@link CheckoutState.permissionRevoked}. `null` when it cannot be built.
+     */
+    revocation: {
+        to: string;
+        data: string;
+    } | null;
+    /**
+     * What another wallet asks for to take over, when this permission's wallet cannot pay, nothing under it has moved money and
+     * its last charge failed, or it expired: it confirms the invoice and gives its own (`POST permission`). Only on an open
+     * invoice of a scheduled subscription.
+     */
+    replacement?: {
+        methodId: string;
+        request: PermissionRequest;
+    };
+} | {
+    /** Not possible now; the buyer pays each invoice. */
+    status: 'unavailable';
+    /** Why, as a stable code. */
+    reason: string;
+};
+/** What the checkout token opens, as {@link CheckoutState.checkout} holds it. */
+interface CheckoutView {
+    /** Always `checkout`. */
+    object: 'checkout';
+    /** Who is paid and on what terms. */
+    merchant: CheckoutMerchant;
+    /** The look the merchant chose. */
+    theme: CheckoutTheme;
+    /** The invoice. */
+    invoice: CheckoutInvoice;
+    /**
+     * Whether the page collects the buyer: `collect` is `off`, `email` or `full`; `required` while the invoice document
+     * waits for them; `companyInvoice` when the page may offer an invoice for a company.
+     */
+    buyer: {
+        collect: 'off' | 'email' | 'full';
+        required: boolean;
+        companyInvoice: boolean;
+    };
+    /** The line the buyer ticks before paying; `null` when the merchant asks none. */
+    consent: CheckoutConsent | null;
+    /**
+     * `true` when the merchant checks paying wallets before payment (its AML mode is `block` or `flag`); the checkout
+     * says so to the buyer only then.
+     */
+    amlScreening: boolean;
+    /** The methods that take this invoice. */
+    methods: CheckoutMethod[];
+    /**
+     * The wallets that confirmed this invoice ({@link CheckoutState.confirmPayer}), oldest first: a page reopened with
+     * one of them asks for no new signature. Quasar versions before October 29, 2026 leave it out.
+     */
+    payerProofs?: CheckoutPayerProof[];
+    /** How long a quote holds once locked, in seconds (never past the invoice deadline). */
+    quoteTtlSeconds: number;
+    /** The locked quote, if any. */
+    quote: CheckoutQuote | null;
+    /** The automatic-charge offer of a subscription invoice; `null` otherwise. */
+    autoCharge: AutoChargeOffer | null;
+}
+/**
+ * The calls a checkout store makes, one per checkout route. {@link createCheckoutStore} makes them over HTTP; pass
+ * your own as `api` to drive the store without a network, as tests and the TUWA docs Playground do. A call rejects with
+ * a `QuasarSDKError` that carries the Payments `code` when Quasar refuses it.
+ */
+interface CheckoutApi {
+    /** Reads the checkout (`GET`). */
+    view: () => Promise<CheckoutView>;
+    /** Locks a quote for a method and, when connected, the payer, with the buyer's consent when given (`POST quote`). */
+    quote: (body: {
+        methodId: string;
+        payer?: string;
+        consentGiven?: boolean;
+    }) => Promise<CheckoutQuote>;
+    /**
+     * The message the wallet signs to confirm the invoice (`POST payer-proof/message`). Optional for an `api` written
+     * before payer proofs: without it and {@link CheckoutApi.payerProof}, {@link CheckoutState.confirmPayer} fails.
+     */
+    payerProofMessage?: (body: {
+        payer: string;
+    }) => Promise<PayerProofMessage>;
+    /** Sends the signed message, which Quasar checks and records (`POST payer-proof`). Optional like `payerProofMessage`. */
+    payerProof?: (body: {
+        payer: string;
+        message: string;
+        signature: string;
+    }) => Promise<PayerProofConfirmation>;
+    /** Sends the buyer details (`POST buyer`) and answers with the checkout. */
+    buyer: (body: {
+        buyer: Buyer;
+        company?: boolean;
+    }) => Promise<CheckoutView>;
+    /** Sets the language of the page and the documents still to be issued (`POST locale`). */
+    locale: (locale: InvoiceLocale) => Promise<{
+        locale: InvoiceLocale;
+    }>;
+    /** Hands over the transaction the wallet sent (`POST submit`). */
+    submit: (body: {
+        txKey: string;
+        from?: string;
+        connectorType?: string;
+        methodId?: string;
+    }) => Promise<{
+        txKey: string;
+        status: string;
+    }>;
+    /** Relays the signed EIP-3009 authorization (`POST relay`). */
+    relay: (signature: string) => Promise<{
+        status: 'submitted' | 'sending';
+        userOpHash?: string;
+        txHash?: string;
+    }>;
+    /** Sends the ERC-7715 permission the wallet granted (`POST permission`). */
+    permission: (body: GrantPermissionParams) => Promise<{
+        permission: unknown;
+        autoCharge: AutoChargeOffer | null;
+    }>;
+    /** `POST permission/revoked`: Quasar asks the chain whether the permission was revoked. */
+    permissionRevoked: () => Promise<{
+        autoCharge: AutoChargeOffer | null;
+    }>;
+    /** The URL of a route that is read without the store: `receipt`, `logo`, `paymaster`, `events`. */
+    url: (route: string) => string;
+}
+/** The answer of the wallet to `wallet_grantPermissions`, as `grantPermission` of the checkout store takes it. */
+interface GrantPermissionParams {
+    /** CAIP-10 account that granted it, on the method's chain. */
+    payer: string;
+    /** The permission context the wallet returned. */
+    context: string;
+    /** The delegation manager it names. */
+    delegationManager: string;
+    /** Account deployments the delegator needs first (ERC-7715 `dependencies`). */
+    dependencies?: {
+        factory: string;
+        factoryData: string;
+    }[];
+}
+/** One `status` event of the checkout's event stream. */
+interface CheckoutStatusEvent {
+    /** State of the invoice. */
+    status: InvoiceStatus;
+    /** Number of ledger steps so far. */
+    ledgerSeq: number;
+    /** The payment transaction, once there is one. */
+    txHash: string | null;
+    /** Amount received, in base units. */
+    amountPaid: string | null;
+    /** When the locked quote expires. */
+    quoteExpiresAt: string | null;
+    /**
+     * Payments handed over and still on their way, as {@link CheckoutInvoice.pendingPayments}. Quasar keeps the stream of an
+     * `expired` or `cancelled` invoice open while it is above `0`.
+     */
+    pendingPayments?: number;
+    /** The keys of the payments that failed, latest first, as {@link CheckoutInvoice.rejectedTxKeys}. */
+    rejectedTxKeys?: string[];
+    /** The payments that failed and why, latest first, as {@link CheckoutInvoice.rejectedPayments}. */
+    rejectedPayments?: CheckoutRejectedPayment[];
+    /** Until when a payment sent before the due date counts, as {@link CheckoutInvoice.paymentCountsUntil}. */
+    paymentCountsUntil?: string | null;
+    /** Payments that may still arrive, with no time limit, as {@link CheckoutInvoice.unresolvedPayments}. */
+    unresolvedPayments?: number;
+    /** The keys of the payments that count as sent in time, as {@link CheckoutInvoice.onTimeTxKeys}. */
+    onTimeTxKeys?: string[];
+}
+
+/**
+ * @file The headless checkout store: the state of one invoice's payment in the buyer's browser.
+ */
+
+/**
+ * Where the payment stands:
+ *
+ * - `loading`: reading the checkout.
+ * - `buyer`: the buyer details come first ({@link CheckoutState.setBuyer}).
+ * - `selectMethod`: choose a method, connect a wallet, confirm it with {@link CheckoutState.confirmPayer} when
+ *   {@link CheckoutState.payerProof} is `required` (an EVM payment the buyer's wallet sends), tick the merchant's consent
+ *   when there is one, then {@link CheckoutState.requestQuote}.
+ * - `quoting`: Quasar screens the payer and locks the price.
+ * - `awaitingPayment`: send `quote.instructions` from the wallet (or sign `quote.gasless`), then
+ *   {@link CheckoutState.submit} or {@link CheckoutState.relay}.
+ * - `submitting`: handing the transaction to Quasar.
+ * - `confirming`: Quasar follows the transaction until it is final. Also while Quasar reports a payment of the
+ *   invoice on its way that this store did not hand over ({@link CheckoutState.invoicePaymentOnTheWay}: the page was
+ *   reopened, or Quasar found a Solana Pay transfer): the page does not offer to pay meanwhile.
+ * - `unconfirmed`: Quasar could not confirm the payment (the network never returned the transaction, no receipt in
+ *   time…), but it may still have gone through: the page asks the buyer to check the wallet before paying again, and
+ *   offers no payment; {@link CheckoutState.payAgain} goes back to it once the buyer did. `error` says why
+ *   (`payment_unconfirmed`, with the `reason`). Also where a reopened page finds the latest payment of the invoice
+ *   unconfirmed or still unresolved ({@link CheckoutState.invoicePaymentUnresolved}), while the store retries
+ *   handing over a transaction the wallet sent (`reason` `submit_retrying`, {@link CheckoutState.submit}), while
+ *   Quasar decides about a transaction another invoice handed over first (`reason` `tx_already_used`), and for a
+ *   payment the network confirmed that Quasar has not recorded yet (`reason` `settlement_failed`); for these two
+ *   {@link CheckoutState.payAgain} does nothing.
+ * - `paid`, `underpaid` (the buyer may top it up), `held` (the merchant looks at the payment), `refunded`, `expired`,
+ *   `cancelled`: the invoice's outcome. An invoice that expires or is cancelled while a payment is on its way (one this
+ *   store handed over with `submit` or `relay`, or one Quasar reports) is not over: the payment may still arrive, and
+ *   the invoice then becomes `paid` (Quasar lets a payment it learned of before `dueAt` confirm for up to 30 minutes)
+ *   or `held` (a late payment, or one to a cancelled invoice, that the merchant accepts or returns). The store keeps
+ *   following it while {@link CheckoutState.paymentOnTheWay} or {@link CheckoutState.invoicePaymentOnTheWay} is
+ *   `true`, for a limited time.
+ * - `blocked`: AML screening refused the payer's wallet.
+ * - `error`: the checkout could not be read (a wrong or retired link, the network).
+ */
+type CheckoutPhase = 'loading' | 'buyer' | 'selectMethod' | 'quoting' | 'awaitingPayment' | 'submitting' | 'confirming' | 'unconfirmed' | 'paid' | 'underpaid' | 'held' | 'refunded' | 'expired' | 'cancelled' | 'blocked' | 'error';
+/**
+ * Why the last action failed: the Payments `code` (`payer_blocked`, `quote_required`, `invoice_expired`…), or
+ * `method_required` (no method chosen), `consent_required` (the merchant's consent is not ticked),
+ * `payer_proof_required` (the wallet has not confirmed the invoice yet: {@link CheckoutState.confirmPayer}; also Quasar's
+ * `409` to a quote), `payer_required` (no wallet to confirm), `payer_proof_declined` (the wallet did not sign the
+ * confirmation; nothing was sent), the refusals of a confirmation (`payer_proof_invalid` with `reason`
+ * `message_mismatch` or `signature_invalid`, `payer_proof_unavailable` with `reason` `rpc_failed` when the network of a
+ * smart wallet cannot be asked now, `payer_chain_mismatch`, `origin_required`, `rate_limited`, `too_many_payers`),
+ * `payment_failed`
+ * (the transaction did not go through: it reverted, was cancelled, its Solana blockhash expired…; pay again),
+ * `payment_mismatch` (the transaction succeeded on chain but does not pay the invoice: a wrong amount, asset or
+ * recipient, no Solana Pay reference, sent before the quote, already used; it may have moved money, so never say that
+ * nothing was charged: say that it does not pay the invoice and to contact the merchant if money left the wallet; the
+ * buyer may pay again once it can never pay the invoice; one that may still pay it keeps `phase` `unconfirmed`, with no
+ * plain second payment), `payment_unconfirmed` (Quasar could not confirm the transaction, or has not received it yet,
+ * but it may still have gone through: check the wallet before paying again; `rechecked` says whether Quasar reads it
+ * again; `reason` `tx_already_used` and `settlement_failed` say more, see {@link CheckoutError.reason}) and
+ * `request_failed` (no answer).
+ */
+interface CheckoutError {
+    /** Stable code. */
+    code: string;
+    /** What to show or log. */
+    message: string;
+    /** HTTP status, when the API answered. */
+    status?: number;
+    /** What to show in the reader's language, when the app said it: a window prefers it to its own words for the code. */
+    text?: string;
+    /** The fields at fault of an invalid request. */
+    issues?: QuasarRequestIssue[];
+    /**
+     * Why Quasar refused an action, when it says (`details.reason` of the refusal: `signature_invalid` of
+     * `payer_proof_invalid`, `feed_unavailable` of `price_unavailable`…). Why Quasar rejected the payment, for
+     * `payment_failed`, `payment_mismatch` and `payment_unconfirmed`: a reason of
+     * {@link CheckoutRejectedPayment} (`reverted`, `no_matching_transfer`, `not_found`, `timeout`…), `submit_retrying`
+     * while the store retries handing over a transaction Quasar has not received yet ({@link CheckoutState.submit}), or
+     * `submit_failed` once it gave up after an hour; left out when Quasar did not say. Two reasons of
+     * `payment_unconfirmed` are about a payment that left the wallet, and the page offers no payment for them:
+     * - `tx_already_used` (with `status` `409`): Quasar tracks the transaction for another invoice whose page handed it
+     *   over first (anyone who saw the hash may have done so). Quasar recorded this invoice's claim on it and credits it
+     *   to the invoice the wallet that sent it confirmed ({@link CheckoutState.confirmPayer}): when that is this invoice,
+     *   it becomes `processing` or `paid` and the error clears; when it is not, Quasar rejects it here with
+     *   `tx_already_used` (`payment_mismatch`).
+     * - `settlement_failed`: the network confirmed the transaction, but Quasar has not recorded it yet. The money reached
+     *   the merchant's address: the buyer contacts the merchant with the transaction hash and does not pay again; never
+     *   say that it does not pay the invoice or that nothing was charged. Quasar settles it again daily for 30 days after
+     *   it learned of it, while `rechecked` is set; only then may the page say so.
+     *
+     * `payment_mismatch` with `payer_mismatch` or `payer_unconfirmed`: the transfer came from another wallet than the
+     * quoted one, or from one that never confirmed the invoice; it pays no invoice and the merchant returns it to the
+     * wallet that sent it.
+     */
+    reason?: string;
+    /**
+     * Set on `payment_unconfirmed` while Quasar still reads the payment again (for up to 24 hours after it learned of
+     * it; a `settlement_failed` one daily for 30 days): the rejection is `rechecked`
+     * ({@link CheckoutRejectedPayment.rechecked}), or there is no rejection and Quasar reports a payment that may still
+     * arrive (`unresolvedPayments` above `0`). Only then may the page promise that Quasar checks the payment again. Left
+     * out otherwise (`user_operation_lost`, `transaction_failed`, `submit_failed`, a `settlement_failed` past its 30 days,
+     * a Quasar that does not say): Quasar never reads that payment again, so the page asks the buyer to contact the
+     * merchant with the transaction hash if money left the wallet.
+     */
+    rechecked?: true;
+    /**
+     * Set on a `payment_mismatch` with the reason `tx_already_used` when another invoice holds the transfer for a refund
+     * only ({@link CheckoutRejectedPayment.held}): say that the transaction is tied to another invoice, never that it pays
+     * one.
+     */
+    held?: true;
+    /**
+     * The other invoice Quasar names: the one a rejected transaction is credited to or held on, or the one whose hold
+     * the merchant refunds instead (`payment_held_elsewhere` of a refund, its `details.invoice`).
+     */
+    otherInvoice?: string;
+    /**
+     * The wallet that paid the invoice first, on `payer_mismatch` (`409`) of {@link CheckoutState.requestQuote}: Quasar
+     * prices the rest of an underpaid invoice only for that wallet, so the buyer pays the rest from it.
+     */
+    originWallet?: string;
+    /** The transaction whose nonce nothing explains, on `nonce_spent_unexplained`: not always the one the page handed over last. */
+    txKey?: string;
+    /**
+     * Set on `payment_unconfirmed` for a payment past the first day Quasar still reads, as a node still shows it or nothing could
+     * read it: neither the promise of `rechecked` nor that Quasar stopped reading it holds.
+     */
+    stillRead?: true;
+}
+/**
+ * Whether the connected wallet must confirm the invoice before it pays (a transfer is
+ * credited only to an invoice it is tied to by proof):
+ *
+ * - `not_needed`: no method chosen, a Solana method (the quote's reference ties the transfer), or a Quasar before payer
+ *   proofs.
+ * - `required`: an EVM payment the buyer's wallet sends (paying the gas, or a smart wallet with or without the
+ *   merchant's paymaster): {@link CheckoutState.confirmPayer} before {@link CheckoutState.requestQuote}, which refuses
+ *   with `payer_proof_required` until then. Also when Quasar refused a quote with `409 payer_proof_required`.
+ * - `unless_relayed`: an EVM method the gasless relay may pay. The quote comes first; paying with
+ *   {@link CheckoutState.relay} needs nothing more (the signed EIP-3009 authorization confirms the wallet), while a
+ *   transfer from the wallet or a paymaster payment (`quote.gasless.paymaster`) needs
+ *   {@link CheckoutState.confirmPayer} before the wallet sends it: Quasar credits a transfer of an unconfirmed wallet to
+ *   no invoice and the merchant returns it.
+ * - `confirming`: {@link CheckoutState.confirmPayer} is under way for a wallet that confirms before the price. A
+ *   wallet the relay may confirm stays `unless_relayed` meanwhile, so a prompt that never answers blocks no new price.
+ * - `confirmed`: the wallet confirmed the invoice: on any EVM network for an ordinary wallet (or through the relay's
+ *   authorization), on the method's network for a smart wallet. One confirmation per invoice and wallet: a new quote,
+ *   another token or network needs none, also on a reopened page (`checkout.payerProofs`).
+ */
+type PayerProofStatus = 'not_needed' | 'required' | 'unless_relayed' | 'confirming' | 'confirmed';
+/**
+ * Signs the message of a payer proof with the connected wallet: `personal_sign` (EIP-191) of `message` exactly as it
+ * is, from `request.payer` (a smart wallet signs it through its own flow, ERC-1271 or ERC-6492). Rejects when the buyer
+ * refuses or the wallet cannot sign.
+ *
+ * @param message - The EIP-4361 message to sign.
+ * @param request - What Quasar answered: the message with its site, network, nonce and dates.
+ * @returns The signature, as hex.
+ */
+type PayerProofSigner = (message: string, request: PayerProofMessage) => Promise<string>;
+/** The state and actions of {@link createCheckoutStore}. */
+interface CheckoutState {
+    /** Where the payment stands. */
+    phase: CheckoutPhase;
+    /** What the checkout token opens; `null` until loaded. */
+    checkout: CheckoutView | null;
+    /** State of the invoice, as Quasar last reported it. */
+    invoiceStatus: InvoiceStatus | null;
+    /** The chosen payment method. */
+    methodId: string | null;
+    /** The connected wallet as a CAIP-10 account on the method's chain. */
+    payer: string | null;
+    /** Whether the buyer ticked the merchant's consent (`checkout.consent`). */
+    consentGiven: boolean;
+    /**
+     * Whether the connected wallet must confirm the invoice before it pays, for the chosen method ({@link PayerProofStatus}).
+     * Read-only: the store sets it from the method, the wallet and the confirmations Quasar and this page know of.
+     */
+    readonly payerProof: PayerProofStatus;
+    /**
+     * The wallets known to have confirmed the invoice in a way that counts for the chosen method, as CAIP-10 accounts: from
+     * Quasar (`checkout.payerProofs`), this page and the locked quote. Read-only: a buyer who changed wallets can be told
+     * which one needs no new signature.
+     */
+    readonly confirmedWallets: readonly string[];
+    /** The locked quote. */
+    quote: CheckoutQuote | null;
+    /** Language of the page and the documents still to be issued. */
+    locale: InvoiceLocale | null;
+    /**
+     * The transaction handed to Quasar: the hash or signature passed to {@link CheckoutState.submit}, or the hash of a
+     * relayed transfer when Quasar returns it. A relay Quasar answers with `sending` has none yet: read
+     * {@link CheckoutState.paymentOnTheWay} to know that a payment is on its way.
+     */
+    txKey: string | null;
+    /**
+     * Whether a payment this store handed to Quasar ({@link CheckoutState.submit}, {@link CheckoutState.relay}, also a
+     * relay still `sending`, without a `txKey`) is on its way: `true` from the hand-over until the payment settles
+     * (the invoice becomes `paid`, `underpaid`, `held`, `refunded` or `cancelled`) or ends. It ends when Quasar lists it
+     * among the rejected payments (`rejectedPayments` of the status events, by its `txKey`, the hash it replaced or the
+     * relay's `userOpHash`), on an `open` invoice too: with a final reason `error` is `payment_failed` (reverted,
+     * cancelled…) or `payment_mismatch` (a wrong amount or recipient…: it may have moved money) and the buyer may pay
+     * again; otherwise (not found, no receipt in time…) `error` is
+     * `payment_unconfirmed` and `phase` `unconfirmed`. The same when the invoice goes back to `open` after `processing`.
+     * On an `expired` or `cancelled` invoice it tells the page that the buyer's payment may still arrive: `false` again
+     * once Quasar reports no payment of the invoice on its way, or at {@link CheckoutState.followingUntil}, when the store
+     * stops following the invoice (`error` `payment_unconfirmed` then, or on a read without a payment on its way, while
+     * {@link CheckoutState.invoicePaymentUnresolved} is `true`). Also `true` while Quasar decides about a transaction
+     * another invoice handed over first (`error.reason` `tx_already_used`). Read-only: the store sets it.
+     */
+    readonly paymentOnTheWay: boolean;
+    /**
+     * Whether Quasar last reported a payment of the invoice on its way (`pendingPayments` above `0`), whoever handed it
+     * over: another tab, the page before it was reloaded, a Solana Pay transfer Quasar found, this invoice's claim on a
+     * transaction another invoice handed over first. While it is `true` on a payable invoice the phase is `confirming`,
+     * not a payment; on an `expired` or `cancelled` invoice the payment may still arrive, and the store follows it as it
+     * follows {@link CheckoutState.paymentOnTheWay}. `false` with a Quasar that does not report it, and once the store
+     * stops following an expired or cancelled invoice. Read-only: the store sets it.
+     */
+    readonly invoicePaymentOnTheWay: boolean;
+    /**
+     * Until when the invoice waits for a payment Quasar learned of before `dueAt` (`dueAt` plus 30 minutes), while one is
+     * on its way; `null` otherwise or with a Quasar that does not report it. The page can say from it, not from the
+     * browser's clock, that the payment was sent in time. Read-only: the store sets it.
+     */
+    readonly paymentCountsUntil: string | null;
+    /**
+     * Whether Quasar last reported a payment of the invoice that may still arrive (`unresolvedPayments` above `0`, with
+     * no time limit: also one stuck past the 25 minutes `pendingPayments` counts, and one whose tracker lost sight of it,
+     * which Quasar reads again for 24 hours); with a Quasar that does not report it, `pendingPayments` above `0`. While it
+     * is `true` the page never says that nothing was charged, and a reopened page that finds no payment on its way starts
+     * in `unconfirmed` (or `expired` with `payment_unconfirmed`). Read-only: the store sets it.
+     */
+    readonly invoicePaymentUnresolved: boolean;
+    /**
+     * Whether the payment this store handed over counts as sent before `dueAt`, as Quasar says (one of its keys is in
+     * `onTimeTxKeys`): `true` once Quasar lists it, `false` while Quasar lists the payments sent in time without it (one
+     * handed over after `dueAt`, which Quasar holds as late), `null` before Quasar reported it, with a Quasar that does
+     * not report it, or without a payment of this page. Use it, not the browser clock. Reset by the next hand-over.
+     * Read-only: the store sets it.
+     */
+    readonly paymentSentInTime: boolean | null;
+    /**
+     * Until when this page follows an `expired` or `cancelled` invoice for a payment on its way (ISO 8601), `null` when it
+     * does not (an invoice that can still be paid is followed with no limit). An expired invoice is followed until 35
+     * minutes past the later of `dueAt` and the latest hand-over of this page (Quasar waits 30 minutes past `dueAt` at
+     * most for a payment it learned of before it, and settles a later one in minutes); when the page found the payment on
+     * its way instead (a reload, another tab), the time it found it counts as the hand-over; an hour after the store found
+     * the invoice expired when it has no `dueAt`. A cancelled invoice is followed until 35 minutes after the later of when
+     * the store found it cancelled and the latest hand-over. A later hand-over moves it on. Past it the page shows nothing
+     * more without a reload, so say "this page follows the payment until {time}", never that it shows the outcome
+     * whenever it comes; a reloaded page reads the outcome. Read-only: the store sets it.
+     */
+    readonly followingUntil: string | null;
+    /** The payment's transaction, once Quasar has one. */
+    txHash: string | null;
+    /** Why the last action failed; cleared by the next one. */
+    error: CheckoutError | null;
+    /** The receipt PDF of a paid invoice (a plain `GET`, for a link); `null` before. */
+    /**
+     * How far this machine's clock is ahead of Quasar's, in milliseconds, as measured on the last price locked here; `0` until
+     * then and within a few seconds. Countdowns subtract it: a wrong clock must not end a price at once or keep an ended one live.
+     */
+    clockSkewMs: number;
+    receiptUrl: string | null;
+    /** The ERC-7677 paymaster URL for `wallet_sendCalls` when the quote offers sponsored calls; `null` otherwise. */
+    paymasterUrl: string | null;
+    /** The merchant's logo (PNG or JPEG, a plain `GET` for an `<img>`); `null` when the merchant has none. */
+    logoUrl: string | null;
+    /**
+     * Reads the checkout (`GET`) and, while the invoice can change, follows it (server-sent events, else a read every
+     * `pollMs`). An event that brings an outcome (underpaid, held, paid, refunded, expired, cancelled) updates
+     * `checkout.invoice.amountPaid` at once and reads the checkout again for the rest (`review`, the refund, the invoice
+     * that replaced it, `autoCharge`). A checkout whose invoice has a payment on its way (a reloaded or reopened page)
+     * starts in `confirming`, not at the payment, and the store follows that payment as its own. One whose latest
+     * payment Quasar could not confirm (its latest rejection is not `final`), or that has a payment that may still arrive
+     * ({@link CheckoutState.invoicePaymentUnresolved}) with none on its way, starts in `unconfirmed` (`expired` stays
+     * `expired`) with `error` `payment_unconfirmed`; one whose latest transaction does not pay the invoice starts with
+     * `error` `payment_mismatch` (in `unconfirmed`, with no plain payment, when the rejection is not `final`). A latest
+     * rejection that Quasar reads again (`not_found`, `timeout`, `replaced`) no longer counts once Quasar reports no
+     * payment that may still arrive (`unresolvedPayments` `0`): Quasar resolved it. Hand-overs this tab kept
+     * ({@link CheckoutState.submit}) that Quasar does not list yet are handed over again at once. It stops at a final
+     * state, except `expired` and `cancelled` while {@link CheckoutState.paymentOnTheWay} or
+     * {@link CheckoutState.invoicePaymentOnTheWay}: it keeps the event stream while Quasar keeps it open for that payment, and
+     * otherwise closes it and reads the checkout every 20 seconds (or every `pollMs`, when longer), until the payment
+     * ends the invoice (`paid`, `held`), fails, Quasar reports no payment on its way, {@link CheckoutState.followingUntil}
+     * comes, or `destroy` is called. A cancelled invoice with a payment that may still arrive
+     * and none on its way opens with `error` `payment_unconfirmed`, like an expired one. It never expires the invoice by
+     * the clock: past `dueAt`, a confirming payment stays `confirming` until Quasar reports the outcome. Sets `phase`
+     * `error` when the link is wrong or retired.
+     *
+     * @returns Resolves when the checkout is read.
+     */
+    load: () => Promise<void>;
+    /**
+     * Chooses a payment method; a quote for another method is dropped.
+     *
+     * @param methodId - One of `checkout.methods`.
+     * @param options - `keepError`: the page chose it, not the buyer, so what it says about a payment that left the wallet
+     * stays.
+     */
+    selectMethod: (methodId: string, options?: {
+        keepError?: boolean;
+    }) => void;
+    /**
+     * Sets the connected wallet; a quote locked to another wallet is dropped.
+     *
+     * @param payer - CAIP-10 account (`eip155:8453:0x…`, `solana:<genesis hash>:<address>`), or `null` for a Solana Pay
+     *   QR payment from another device.
+     */
+    setPayer: (payer: string | null) => void;
+    /** Forgets the last error: the buyer left what it was about. */
+    clearError: () => void;
+    /**
+     * Ticks or clears the merchant's consent (`checkout.consent`): a required one must be ticked before
+     * {@link CheckoutState.requestQuote}, which sends it with the quote.
+     *
+     * @param given - Whether the buyer ticked it.
+     */
+    setConsentGiven: (given: boolean) => void;
+    /**
+     * Forgets the locked quote and goes back to choosing a method ("Back to methods"), also for a Solana Pay QR quote
+     * that no other action drops; from the quote of a rest it goes back to the `underpaid` outcome. Nothing changes once
+     * the payment is on its way (`submitting`, `confirming`) or done. Quasar keeps the lock until it ends: a payment of the
+     * old quote that still arrives is credited.
+     */
+    releaseQuote: () => void;
+    /**
+     * Screens the payer and locks the price (`POST quote`).
+     *
+     * @returns The quote, or `null` with `error` set (`phase` `blocked` when AML refuses the wallet, `buyer` when the
+     *   details come first; `consent_required`, without a request, when a required consent is not ticked;
+     *   `payer_proof_required`, without a request while {@link CheckoutState.payerProof} is `required`, and from Quasar
+     *   for a wallet it wants confirmed first, `phase` back at `selectMethod`). On an underpaid invoice it prices the
+     *   rest ({@link CheckoutQuote.amountDue}) at the rate of the first quote, with no consent asked again, and refuses
+     *   with `409`, back at `underpaid`: `payer_mismatch` and {@link CheckoutError.originWallet} (the rest is paid from the
+     *   wallet that paid first) or `rest_method_mismatch` (in the method that paid first).
+     */
+    requestQuote: () => Promise<CheckoutQuote | null>;
+    /**
+     * Confirms that the connected wallet pays this invoice: asks Quasar for the exact message
+     * (`POST payer-proof/message`), has `sign` sign it with the wallet (a free signature that moves no funds), and sends
+     * the signature (`POST payer-proof`), which Quasar checks (an ordinary wallet's by recovery, a smart wallet's through
+     * its contract) and records for the invoice. Call it right after the wallet and the method are chosen, while
+     * {@link CheckoutState.payerProof} is `required`, and before a transfer or a paymaster payment while it is
+     * `unless_relayed`. A wallet confirms an invoice once: a wallet Quasar or this page already knows as confirmed asks
+     * for no signature (also one Quasar answers `proven` for, confirmed from another tab), and a method that needs none
+     * (`not_needed`) answers `true` at once. The page stays in its phase meanwhile ({@link CheckoutState.payerProof} is
+     * `confirming` for the wallet being asked before the price, never for another one or an `unless_relayed` one). A new call replaces a confirmation under way, so a
+     * prompt the buyer closed that never answers blocks nothing: call it again to try again. The replaced attempt's late
+     * answer only records the wallet's proof (no `error`, no phase change). Side effect: a wallet prompt through `sign`.
+     *
+     * @param sign - Signs the message with the wallet ({@link PayerProofSigner}).
+     * @returns Whether the wallet confirmed the invoice; {@link CheckoutState.payerProof} is then `confirmed`. `false`
+     *   for a replaced attempt that did not confirm it (nothing changes), and with `error` set: `payer_required` (no wallet),
+     *   `request_failed` (an `api` without the payer proof calls), `payer_proof_declined` (`sign` rejected: the buyer
+     *   refused, or the wallet cannot sign messages), or Quasar's refusal (`payer_proof_invalid`, `payer_proof_unavailable`,
+     *   `payer_chain_mismatch`, `origin_required`, `rate_limited`, `too_many_payers`, `invoice_not_payable`;
+     *   `payer_not_expected` sets `phase` `blocked`, `invoice_expired` `expired`).
+     */
+    confirmPayer: (sign: PayerProofSigner) => Promise<boolean>;
+    /**
+     * The buyer closed the wallet's window of the confirmation: the request stays open in the wallet, and a signature it
+     * gives later still counts, while a refusal it gives later changes nothing on the page, wherever the buyer went.
+     */
+    abandonConfirmation: () => void;
+    /**
+     * Sends the buyer details the checkout collects (`POST buyer`); the invoice document is issued with them.
+     *
+     * @param buyer - The details.
+     * @param options - `company: true` for an invoice for a company (name, address line, country and tax ID needed).
+     * @returns Whether they were taken.
+     */
+    setBuyer: (buyer: Buyer, options?: {
+        company?: boolean;
+    }) => Promise<boolean>;
+    /**
+     * Changes the language of the page and of the documents still to be issued (`POST locale`).
+     *
+     * @param locale - The language.
+     * @returns Whether it was saved.
+     */
+    setLocale: (locale: InvoiceLocale) => Promise<boolean>;
+    /**
+     * Hands Quasar the transaction the wallet sent (`POST submit`). For an EIP-5792 batch, pass the hash of its
+     * transaction (from `wallet_getCallsStatus`), not the batch ID.
+     *
+     * The wallet has already sent the transaction, so a hand-over that gets no answer (the network, HTTP 408, 429 or
+     * 5xx, `too_many_pending`) is not a failed payment: `txKey` keeps the transaction, `phase` is `unconfirmed` with
+     * `error` `payment_unconfirmed` (`reason` `submit_retrying`), and the store hands it over again after 2, 4, 8, 16
+     * and then every 30 seconds (Quasar takes a transaction once per `txKey`), for up to an hour or until `destroy`;
+     * after the hour `error.reason` is `submit_failed` (Quasar never received it: the buyer contacts the merchant with
+     * the transaction hash if money left the wallet). Once Quasar takes it, the store follows it as below; taken while
+     * the invoice is already `paid`, `held` or `refunded`, it leaves the phase as it is (Quasar records it for the
+     * merchant) and the store reads the checkout once more; taken while it is `expired` or `cancelled`, the phase stays
+     * and the store follows the payment until Quasar holds it (or pays the expired invoice in its grace).
+     *
+     * Quasar answers `409 tx_already_used` when it tracks the transaction for another invoice whose page handed it over
+     * first (EVM invoices share the merchant's address, so anyone who saw the hash may have done so). That is not a
+     * refusal of the payment: Quasar records this invoice's claim and credits the transaction to the invoice whose quoted
+     * wallet sent it. The store follows it as its payment, with `phase` `unconfirmed` (the outcome's on an expired or
+     * cancelled invoice) and `error` `payment_unconfirmed` with `reason` `tx_already_used`, and offers no payment
+     * ({@link CheckoutState.payAgain} does nothing) until Quasar decides. It is not handed over again. Any other refusal
+     * (4xx) is not retried either.
+     *
+     * Until Quasar takes or refuses it, the hand-over is kept in the tab's `sessionStorage`
+     * ({@link CheckoutStoreOptions.handOverStorage}), so a page closed or reloaded meanwhile hands it over again on the
+     * next {@link CheckoutState.load} of the same checkout.
+     *
+     * @param params - `txKey`: transaction hash or Solana signature; `from`: the sender, for a Solana Pay quote without
+     *   a payer; `connectorType`: the wallet connector, for the record.
+     * @returns Whether Quasar took it; `phase` is then `confirming` (`expired` or `cancelled` when the invoice expired or
+     *   was cancelled meanwhile: Quasar still takes the transaction, and holds it as a late payment) and
+     *   {@link CheckoutState.paymentOnTheWay} `true`. `false` while the hand-over is retried, after a refusal, and for
+     *   `tx_already_used` (followed all the same).
+     */
+    submit: (params: {
+        txKey: string;
+        from?: string;
+        connectorType?: string;
+        methodId?: string;
+    }) => Promise<boolean>;
+    /**
+     * Sends the payer's signature of `quote.gasless.relay.typedData` (`POST relay`): Quasar sends the transfer and the
+     * merchant pays the gas.
+     *
+     * @param signature - The 65-byte EIP-712 signature.
+     * @returns Whether it was relayed; `phase` is then `confirming` and {@link CheckoutState.paymentOnTheWay} `true`.
+     *   `txKey` is the transfer's hash when Quasar returns it, `null` while the relay is still `sending`.
+     */
+    relay: (signature: string) => Promise<boolean>;
+    /**
+     * Passes the wallet's answer to `wallet_grantPermissions` for a subscription's automatic charges (`POST permission`).
+     *
+     * Quasar takes a permission only from a wallet that confirmed the invoice: with `sign`, a refusal for that has the
+     * wallet sign the free confirmation and the permission is passed again.
+     *
+     * @param params - The granting account, the permission context, its delegation manager and dependencies.
+     * @param sign - Has the wallet sign Quasar's message, as for {@link CheckoutState.confirmPayer}.
+     * @returns Whether Quasar accepted it; `checkout.autoCharge` is then `active`.
+     */
+    grantPermission: (params: GrantPermissionParams, sign?: PayerProofSigner) => Promise<boolean>;
+    /**
+     * Tells Quasar that the wallet sent the transaction that revokes the permission (`autoCharge.revocation`): Quasar asks
+     * the chain (`POST permission/revoked`), and `checkout.autoCharge` follows what it finds. Neither the phase nor the
+     * error of the store change: it may be asked from any screen, and what that screen says stands.
+     *
+     * @returns Whether the permission has ended; `false` while the chain does not show it yet; `null` when Quasar could not
+     * be asked.
+     */
+    permissionRevoked: () => Promise<boolean | null>;
+    /**
+     * Goes back to the payment from `unconfirmed`, once the buyer checked that the payment did not leave the wallet:
+     * `awaitingPayment` while the locked quote is valid, `underpaid` for the rest of an underpaid invoice, otherwise
+     * `selectMethod` (the expired quote is dropped); the outcome of an invoice that no longer takes a payment. Nothing
+     * changes in another phase, nor while `error.reason` is `tx_already_used` or `settlement_failed`: that payment left
+     * the wallet and may still pay the invoice.
+     */
+    payAgain: () => void;
+    /** Stops following the invoice (closes the event stream or the reads). Call it when the page goes away. */
+    destroy: () => void;
+}
+/** The part of the browser's `EventSource` the store uses. */
+interface EventSourceLike {
+    /** `2` once closed for good. */
+    readyState: number;
+    /** Called on a failure; the browser reconnects unless `readyState` is `2`. */
+    onerror: ((event: unknown) => void) | null;
+    /** Listens to named events. */
+    addEventListener: (type: string, listener: (event: {
+        data: string;
+    }) => void) => void;
+    /** Closes the stream. */
+    close: () => void;
+}
+/** A constructor of {@link EventSourceLike}, such as the browser's `EventSource`. */
+type EventSourceConstructor = new (url: string) => EventSourceLike;
+/** Options of {@link createCheckoutStore}. */
+interface CheckoutStoreOptions {
+    /** The checkout token of the invoice (from its `checkoutToken` or the end of its `payUrl`). */
+    token: string;
+    /** The Quasar API. Defaults to {@link BASE_API_URL}. */
+    baseUrl?: string;
+    /** How often to read the invoice when there is no event stream, in milliseconds. Defaults to `5000`. */
+    pollMs?: number;
+    /**
+     * The `EventSource` to follow the invoice with. Defaults to the global one; `null` reads the invoice every `pollMs`
+     * instead.
+     */
+    EventSource?: EventSourceConstructor | null;
+    /**
+     * The calls to make instead of the HTTP ones of `token` and `baseUrl`, for tests and simulations (the TUWA docs
+     * Playground). With your own calls, pass `EventSource: null` too, or the store opens `api.url('events')`.
+     */
+    api?: CheckoutApi;
+    /**
+     * Where the store keeps the hand-overs of transactions the wallet sent that Quasar has not taken yet
+     * ({@link CheckoutState.submit}), so that the next {@link CheckoutState.load} of the same checkout hands them over
+     * again. Defaults to the browser's `sessionStorage` (the tab, until it closes), or none with your own `api`; `null`
+     * keeps nothing. The entry is `quasar-sdk:checkoutHandOvers:<token>`: a JSON array of
+     * `{ txKey, from?, connectorType?, at }` (the transaction, the sending wallet and the wallet connector as passed to
+     * `submit`, and when the store first got it, in milliseconds since 1970), removed once Quasar takes or refuses it.
+     * Failures of the storage are ignored.
+     */
+    handOverStorage?: CheckoutHandOverStorage | null;
+}
+/** The part of the browser's `Storage` (`sessionStorage`) the checkout store keeps its hand-overs in. */
+interface CheckoutHandOverStorage {
+    /** Reads an entry; `null` when there is none. */
+    getItem: (key: string) => string | null;
+    /** Writes an entry. */
+    setItem: (key: string, value: string) => void;
+    /** Removes an entry. */
+    removeItem: (key: string) => void;
+}
+/** The store {@link createCheckoutStore} returns: a vanilla Zustand store (use it with `useStore` of `zustand`). */
+type CheckoutStore = StoreApi<CheckoutState>;
+/**
+ * Creates the headless checkout of one invoice for the buyer's browser: a vanilla Zustand store with the invoice,
+ * its methods, the locked quote and where the payment stands, and the actions that move it on. The wallet is the
+ * app's: the store never sends a transaction, it returns `quote.instructions` (and `quote.gasless`) for Pulsar or the
+ * wallet to execute, and takes the result with `submit` or `relay`. It needs no key: the checkout token opens this
+ * invoice only. `@tuwaio/nova-payments` renders it.
+ *
+ * Side effects: requests to `<baseUrl>/v1/payments/checkout/<token>` (the page's origin must be one of the app's
+ * domains, when it lists any; its `Origin` is the site the payer proof message names); a wallet prompt to sign a
+ * message through the `sign` passed to {@link CheckoutState.confirmPayer}, never by itself; after `load`, an `EventSource` on its `events` route (or a `GET` every `pollMs`) until
+ * the invoice reaches a final state or `destroy` is called (an invoice that expired or was cancelled while a payment
+ * confirms is followed on, for a limited time, until that payment ends it as `paid` or `held`), and a `GET` of the
+ * checkout when an event brings an outcome. A hand-over Quasar has not taken yet is kept in the tab's `sessionStorage` under
+ * `quasar-sdk:checkoutHandOvers:<token>` ({@link CheckoutStoreOptions.handOverStorage}) until Quasar takes or refuses
+ * it; nothing else is stored in the browser.
+ *
+ * @param options - The checkout token and optional overrides.
+ * @returns The store; call `load()` first.
+ *
+ * @example
+ * ```ts
+ * import { createCheckoutStore } from '@tuwaio/payments-sdk/checkout';
+ *
+ * const checkout = createCheckoutStore({ token });
+ * await checkout.getState().load();
+ * checkout.getState().selectMethod(checkout.getState().checkout!.methods[0].id);
+ * checkout.getState().setPayer(`eip155:8453:${address}`);
+ * // An EVM payment the wallet sends: the wallet confirms the invoice first, with a free signature
+ * if (checkout.getState().payerProof === 'required') {
+ *   await checkout.getState().confirmPayer((message) => walletClient.signMessage({ account: address, message }));
+ * }
+ * const quote = await checkout.getState().requestQuote();
+ * // Send quote.instructions with the wallet, then:
+ * await checkout.getState().submit({ txKey: hash });
+ * ```
+ */
+declare function createCheckoutStore(options: CheckoutStoreOptions): CheckoutStore;
+
+/**
+ * @file The headless refund store: a merchant refunds a payment from a connected wallet in the browser.
+ */
+
+/**
+ * Where a refund stands: `idle`; `requesting` (Quasar prices it); `awaitingTransfer` (send `instructions` from the
+ * merchant's wallet, then {@link RefundState.submit}); `submitting`; `confirming` (Quasar follows the transaction);
+ * `confirmed` (the credit note is issued) or `failed`.
+ */
+type RefundPhase = 'idle' | 'requesting' | 'awaitingTransfer' | 'submitting' | 'confirming' | 'confirmed' | 'failed';
+/** A refund transaction the wallet sent, kept until Quasar takes it or refuses it for good. */
+interface SentRefundTransaction {
+    /** The transaction (hash or Solana signature). */
+    txHash: string;
+    /** The wallet that sent it, which may not be the one connected now. */
+    from: string;
+}
+/** The state and actions of {@link createRefundStore}. */
+interface RefundState {
+    /** Where the refund stands. */
+    phase: RefundPhase;
+    /** The refund, once asked for. */
+    refund: Refund | null;
+    /** What to send where: chain, asset, recipient (the payer) and amount in base units. */
+    instructions: RefundStart['instructions'] | null;
+    /** Why the last action failed; cleared by the next one. */
+    error: CheckoutError | null;
+    /**
+     * The transaction the wallet sent for this refund that Quasar has not taken yet. While it is set, never ask a wallet
+     * again: hand it over with {@link RefundState.submit}, or the buyer is refunded twice.
+     */
+    sentTransaction: SentRefundTransaction | null;
+    /**
+     * What a refund would send, through the option `preview`: nothing is asked for.
+     *
+     * @param invoiceId - The paid or held invoice.
+     * @param params - Amount (everything left when omitted), mode and reason.
+     * @returns The preview; `null` without the option, or when it failed (`error` says why).
+     */
+    preview: (invoiceId: string, params?: RefundParams) => Promise<RefundPreview | null>;
+    /**
+     * Asks for a refund of an invoice through `request`. When a transaction sent for an earlier refund of the invoice was
+     * not handed over, that refund comes back instead (`sentTransaction`), or is followed when Quasar took it after all, and
+     * nothing new is asked for while Quasar does not say what became of it.
+     *
+     * @param invoiceId - The paid or held invoice.
+     * @param params - Amount (everything left when omitted), mode and reason.
+     * @returns Whether it was asked for or came back; `phase` is then `awaitingTransfer` (`confirming` when taken).
+     */
+    start: (invoiceId: string, params?: RefundParams) => Promise<boolean>;
+    /**
+     * Continues a refund that waits for its transaction (asked for earlier, or through the API).
+     *
+     * @param refund - The refund, `requested`.
+     * @param instructions - What to send, as `request` returned it.
+     */
+    resume: (refund: Refund, instructions: RefundStart['instructions']) => void;
+    /**
+     * Reads the refund again before a wallet is asked to send it. A window can stay open while the refund is withdrawn or sent
+     * elsewhere, and a wallet asked then would pay out money nobody asks for any more. What it finds shows in `phase`.
+     *
+     * Side effects: one `get`; follows a refund it finds submitted.
+     *
+     * @returns Whether a wallet may send the refund now: `false` when Quasar does not answer (`error` says so), as it cannot be
+     * known then, and while `sentTransaction` holds a transaction already sent for it.
+     */
+    recheck: () => Promise<boolean>;
+    /**
+     * Hands over the refund transaction through `submit`, then follows the refund through `get` until it is final. The
+     * transaction stays in `sentTransaction`, and in {@link RefundStoreOptions.handOverStorage}, until Quasar takes it or
+     * refuses it for good: a refusal of 4xx, other than one that says nothing about it (401, 403, 408, 425, 429).
+     *
+     * @param params - The transaction and the merchant wallet it was sent from.
+     * @returns Whether it was taken; `phase` is then `confirming`.
+     */
+    submit: (params: SubmitRefundParams) => Promise<boolean>;
+    /** Stops reading the refund and keeps everything else, for when the window goes away. */
+    stopFollowing: () => void;
+    /** Reads the refund again after {@link RefundState.stopFollowing}, while it is `confirming`. */
+    keepFollowing: () => void;
+    /** Stops following and returns to `idle`. */
+    reset: () => void;
+}
+/**
+ * Options of {@link createRefundStore}: the three calls, which the app runs on its server with the secret key. A call refuses by
+ * throwing: the `QuasarSDKError` of the SDK, or from an app's own route an `Error` with the `code` of the refusal, its `status`
+ * and optionally `text`, what to show in the reader's language. A Server Action cannot pass such an error to the browser: wrap it
+ * in {@link refundAction}. Any other error reads as `request_failed`: Quasar did not answer.
+ */
+interface RefundStoreOptions {
+    /** Asks for the refund, for example a Server Action that calls `quasar.payments.refund`. */
+    request: (invoiceId: string, params: RefundParams) => Promise<RefundStart | RefusedRefundCall>;
+    /** Shows what a refund would send, for example through `quasar.payments.previewRefund`. Optional. */
+    preview?: (invoiceId: string, params: RefundParams) => Promise<RefundPreview | RefusedRefundCall>;
+    /** Hands over its transaction, for example through `quasar.payments.submitRefund`. */
+    submit: (refundId: string, params: SubmitRefundParams) => Promise<Refund | RefusedRefundCall>;
+    /** Reads the refund, for example through `quasar.payments.getRefund`. */
+    get: (refundId: string) => Promise<Refund | RefusedRefundCall>;
+    /** How often to read a refund being confirmed, in milliseconds. Defaults to `5000`. */
+    pollMs?: number;
+    /**
+     * Where a transaction the wallet sent is kept until Quasar takes or refuses it, so that a page closed or reloaded meanwhile
+     * hands it over instead of having the wallet send the refund again. Defaults to the browser's `sessionStorage` (the tab,
+     * until it closes); `null` keeps it in memory only.
+     */
+    handOverStorage?: CheckoutHandOverStorage | null;
+}
+/** What {@link refundAction} returns for a call Quasar refused. */
+interface RefusedRefundCall {
+    /** The refusal: its `code`, HTTP `status` and message. */
+    refused: {
+        code: string;
+        message: string;
+        status?: number;
+    };
+}
+/**
+ * Wraps a call of the refund store for a Server Action: React passes no fields of a thrown error to the browser, so without it
+ * every refusal reads as "Quasar did not answer". The action returns the refusal, and the store takes it as thrown.
+ *
+ * @param call - The call, for example `quasar.payments.refund` bound to its client.
+ * @returns The same call, which returns a refusal of Quasar instead of throwing it. Any other error is thrown as it was.
+ *
+ * @example
+ * ```ts
+ * 'use server';
+ * export const refundInvoice = refundAction((invoiceId: string, params: RefundParams) =>
+ *   quasar.payments.refund(invoiceId, params),
+ * );
+ * ```
+ */
+declare function refundAction<Args extends unknown[], Result>(call: (...args: Args) => Promise<Result>): (...args: Args) => Promise<Result | RefusedRefundCall>;
+/** The store {@link createRefundStore} returns: a vanilla Zustand store. */
+type RefundStore = StoreApi<RefundState>;
+/**
+ * Creates the headless refund of a payment from the merchant's connected wallet: ask for the refund, send its
+ * `instructions` with the wallet (Pulsar or the wallet itself; the store sends nothing on-chain), hand over the
+ * transaction, then follow the refund until Quasar confirms it and issues the credit note. The secret key never
+ * reaches the browser: the store calls `request`, `submit` and `get`, which the app runs on its server (Server
+ * Actions or its own routes calling `quasar.payments`).
+ *
+ * Side effects: the calls the app supplies; while `confirming`, `get` every `pollMs` for five minutes and every 30 seconds
+ * after that, until the refund is final, `reset` or `stopFollowing` is called, or a read answers 401, 403 or 404; `sessionStorage` under `quasar-sdk:refundHandOvers` for a sent transaction Quasar has not taken
+ * ({@link RefundStoreOptions.handOverStorage}).
+ *
+ * @param options - The three calls and the poll interval.
+ * @returns The store.
+ *
+ * @example
+ * ```ts
+ * import { createRefundStore } from '@tuwaio/payments-sdk/checkout';
+ *
+ * // refundInvoice, submitRefund and getRefund are Server Actions calling quasar.payments
+ * const refunds = createRefundStore({ request: refundInvoice, submit: submitRefund, get: getRefund });
+ * await refunds.getState().start(invoiceId, { reason: 'Order cancelled' });
+ * // Send refunds.getState().instructions with the wallet, then:
+ * await refunds.getState().submit({ txHash, from: address });
+ * ```
+ */
+declare function createRefundStore(options: RefundStoreOptions): RefundStore;
+
+export { createCheckoutStore as M, createRefundStore as N, refundAction as O };
+export type { AutoChargeOffer as A, Buyer as B, CheckoutError as C, PayerProofConfirmation as D, EventSourceConstructor as E, PayerProofKind as F, GrantPermissionParams as G, PayerProofNeed as H, PayerProofSigner as I, PayerProofStatus as J, RefundStoreOptions as K, RefusedRefundCall as L, PaymentInstructions as P, RefundPhase as R, SentRefundTransaction as S, TransferAuthorizationTypedData as T, RefundState as a, RefundPreview as b, CheckoutStore as c, CheckoutState as d, CheckoutView as e, CheckoutMethod as f, CheckoutQuote as g, PayerProofMessage as h, CheckoutApi as i, RefundStore as j, CheckoutPhase as k, CheckoutMerchant as l, PermissionRequest as m, CheckoutConsent as n, CheckoutHandOverStorage as o, CheckoutInvoice as p, CheckoutLine as q, CheckoutPayerProof as r, CheckoutRejectedPayment as s, CheckoutReview as t, CheckoutStatusEvent as u, CheckoutStoreOptions as v, CheckoutSubscription as w, CheckoutTheme as x, EventSourceLike as y, GaslessOffer as z };