@tuwaio/quasar-sdk 0.7.3 → 0.9.0

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import { C as CreateInvoiceParams, i as CreateOptions, j as InvoiceWithCheckout, k as InvoiceDetails, L as ListInvoiceItemsParams, l as PaymentsList, R as Refund, m as InvoiceDocumentRef, n as ListInvoicesParams, o as Invoice, p as CorrectInvoiceParams, q as InvoiceCorrection, G as GetEventsParams, r as InvoiceLedger, f as RefundParams, g as RefundPreview, e as RefundStart, h as SubmitRefundParams, s as ListHeldTransfersParams, H as HeldTransfer, t as PaymentDocumentKind, u as PaymentDocument, v as QuoteParams, w as PaymentQuote, x as PaymentMethod, y as CreateSubscriptionParams, z as SubscriptionStart, A as ListSubscriptionsParams, D as Subscription, E as ListSubscriptionItemsParams, F as SubscriptionCharge, J as CancelSubscriptionParams, P as PaymentsEnvironment, K as InvoiceSettlement, M as InvoicePayment } from './errors-4kLHVSws.js';
+export { B as Buyer, N as HeldTransferStatus, O as InvoiceAml, U as InvoiceAttempt, V as InvoiceLine, W as InvoiceLineInput, X as InvoiceLinesInput, b as InvoiceLocale, Y as InvoiceQuote, Z as InvoiceSeller, I as InvoiceStatus, _ as InvoiceTermsInput, $ as InvoiceWalletConfirmation, a0 as LedgerEvent, a1 as LedgerSummary, a2 as LedgerVerification, a as PaymentsCurrency, Q as QuasarRequestIssue, a3 as QuasarSDKError, a4 as RefundMode, d as SubscriptionInterval, S as SubscriptionPermission, c as SubscriptionStatus, T as TaxCategory } from './errors-4kLHVSws.js';
 import { FetchOptions } from 'ofetch';
 import { Transaction } from '@tuwaio/pulsar-core';
 export { Transaction, TransactionStatus, TransactionTracker, UpdatableTransactionFields } from '@tuwaio/pulsar-core';
@@ -18,6 +20,8 @@ declare const PULSAR_HISTORY_ENDPOINT = "/v1/engine/pulsar/history";
  * @returns The path, with the batch ID URL-encoded.
  */
 declare const pulsarSyncHashEndpoint: (txKey: string) => string;
+/** Path prefix of the Payments API, which `PaymentsModule` calls. */
+declare const PAYMENTS_ENDPOINT = "/v1/payments";
 
 /**
  * @file Configuration, query and response types of the Quasar client, and the Pulsar transaction types it syncs.
@@ -87,41 +91,9 @@ interface PaginatedResult<T> {
 }
 
 /**
- * @file HTTP client of the Quasar SDK: authentication headers, timeout and errors.
+ * @file HTTP client of the Quasar SDK: authentication headers and timeout; failures become `QuasarSDKError`.
  */
 
-/**
- * Error thrown by the methods of the {@link Quasar} client when a request fails: an HTTP error status, a timeout or a
- * network error.
- *
- * @example
- * ```typescript
- * try {
- *   await quasar.pulsar.getHistory();
- * } catch (err) {
- *   if (err instanceof QuasarSDKError) {
- *     console.error(err.status);        // e.g. 401
- *     console.error(err.message);       // "[Quasar SDK] Request Failed (401): <error of the API>"
- *     console.error(err.originalError); // FetchError from ofetch
- *   }
- * }
- * ```
- */
-declare class QuasarSDKError extends Error {
-    /** HTTP status code of the response, or `undefined` when no response was received. */
-    readonly status: number | undefined;
-    /** The error thrown by `ofetch`. */
-    readonly originalError: Error;
-    /**
-     * Creates the error.
-     *
-     * @param message - Message: `[Quasar SDK] Request Failed (<status>): <error>`, where `<error>` is the `error` field of
-     *   the response body or the message of the fetch error.
-     * @param status - HTTP status code, or `undefined` when no response was received.
-     * @param originalError - The error thrown by `ofetch`.
-     */
-    constructor(message: string, status: number | undefined, originalError: Error);
-}
 /**
  * HTTP client shared by the modules of the {@link Quasar} client. Sends every request with the `x-tuwa-secret-key`
  * header (and `x-internal-secret` when configured) through `ofetch`.
@@ -156,12 +128,387 @@ declare class QuasarClient {
      */
     request<T>(path: string, options?: Omit<FetchOptions<'json'>, 'baseURL' | 'timeout'>): Promise<T>;
     /**
-     * Wraps an `ofetch` error in a {@link QuasarSDKError}. Side effect: logs a `console.error` on a 401 or 403 status.
+     * Downloads a file: its bytes, media type and the file name of its `Content-Disposition` header. Sends the same
+     * headers as {@link QuasarClient.request}.
      *
-     * @param error - The error thrown by `ofetch`.
-     * @returns The wrapped error.
+     * @param path - Endpoint path.
+     * @returns The bytes, `Content-Type` and file name (`null` when the response names none).
+     * @throws {QuasarSDKError} On an HTTP error status, a timeout or a network error.
      */
-    private buildError;
+    requestFile(path: string): Promise<{
+        bytes: Uint8Array;
+        contentType: string | null;
+        filename: string | null;
+    }>;
+}
+
+/**
+ * @file Payments module of the Quasar client: invoices, refunds, documents, quotes, payment methods and
+ * subscriptions of a Payments app.
+ */
+
+/**
+ * The Payments API (`/v1/payments`) of a Payments app, available as `quasar.payments` on a {@link Quasar} client.
+ * Quasar issues numbered invoices with PDF (and, when on, e-invoice) documents, checks the on-chain payment, records
+ * every step in a hash-chained ledger and sends `payments.v1` webhooks; money goes straight to your wallets. The app
+ * must be a Payments app, and the Quasar node must run Payments.
+ *
+ * Every method sends one request with the secret key in the `x-tuwa-secret-key` header.
+ *
+ * @example
+ * ```ts
+ * import { Quasar } from '@tuwaio/quasar-sdk';
+ *
+ * const quasar = new Quasar({ secretKey: process.env.QUASAR_SECRET_KEY ?? '' });
+ * const { invoice, payUrl } = await quasar.payments.createInvoice(
+ *   {
+ *     currency: 'EUR',
+ *     lineItems: [{ name: 'Pro plan, October', quantity: '1', unitPrice: '49.00', taxRate: '21' }],
+ *     buyer: { email: 'buyer@example.com', externalId: 'user_42' },
+ *   },
+ *   { idempotencyKey: 'order_42' },
+ * );
+ * ```
+ */
+declare class PaymentsModule {
+    private readonly client;
+    /**
+     * Creates the module. The {@link Quasar} client creates it for you.
+     *
+     * @param client - The HTTP client of the Quasar client.
+     * @internal
+     */
+    constructor(client: QuasarClient);
+    /**
+     * Issues an invoice (`POST /v1/payments/invoices`): numbered, with its PDF and, when the app has e-invoices on and
+     * the buyer details allow, its UBL; the `invoice.issued` webhook follows.
+     *
+     * @param params - The lines (or a bare `amount`), the buyer and the terms. Dates go as ISO 8601.
+     * @param options - `idempotencyKey`: a retry with the same key returns the invoice issued first, with the same link.
+     * @returns The invoice, its checkout token and its payment page (also in the invoice view while it can be paid).
+     * @throws {QuasarSDKError} `invalid_request` with `issues` (400), `seller_details_missing` and other issuer
+     *   refusals (400), an app that is not a Payments app or a node without Payments (403), a timeout or a network
+     *   error.
+     */
+    createInvoice(params: CreateInvoiceParams, options?: CreateOptions): Promise<InvoiceWithCheckout>;
+    /**
+     * Reads an invoice with its five newest refunds, every refund still under way, and how many refunds and credit
+     * notes it has (`GET /v1/payments/invoices/:id`). The full lists are {@link PaymentsModule.listInvoiceRefunds} and
+     * {@link PaymentsModule.listInvoiceDocuments}. It also names every transfer credited to it (`payments`: an invoice
+     * paid in parts has several), the newest transactions that did not pay it (`attempts`, `attemptsTotal`) and what the
+     * wallets that confirmed it signed (`walletConfirmations`).
+     *
+     * @param invoiceId - The invoice.
+     * @returns The invoice.
+     * @throws {QuasarSDKError} `invoice_not_found` (404), a timeout or a network error.
+     */
+    getInvoice(invoiceId: string): Promise<InvoiceDetails>;
+    /**
+     * Lists the refunds of an invoice, newest first (`GET /v1/payments/invoices/:id/refunds`).
+     *
+     * @param invoiceId - The invoice.
+     * @param params - Paging.
+     * @returns One page; pass `nextCursor` as `cursor` for the next.
+     * @throws {QuasarSDKError} `invoice_not_found` (404), `invalid_request` or `invalid_cursor` (400), a timeout or a
+     *   network error.
+     */
+    listInvoiceRefunds(invoiceId: string, params?: ListInvoiceItemsParams): Promise<PaymentsList<Refund>>;
+    /**
+     * Lists the documents issued for an invoice, newest first (`GET /v1/payments/invoices/:id/documents`): the invoice,
+     * its receipt and its credit notes, as PDF and UBL. Download them with {@link PaymentsModule.getDocument} and
+     * {@link PaymentsModule.getCreditNote}.
+     *
+     * @param invoiceId - The invoice.
+     * @param params - Paging.
+     * @returns One page; pass `nextCursor` as `cursor` for the next.
+     * @throws {QuasarSDKError} `invoice_not_found` (404), `invalid_request` or `invalid_cursor` (400), a timeout or a
+     *   network error.
+     */
+    listInvoiceDocuments(invoiceId: string, params?: ListInvoiceItemsParams): Promise<PaymentsList<InvoiceDocumentRef>>;
+    /**
+     * Lists invoices, newest first (`GET /v1/payments/invoices`).
+     *
+     * @param params - Filters and paging.
+     * @returns One page; pass `nextCursor` as `cursor` for the next.
+     * @throws {QuasarSDKError} `invalid_request` or `invalid_cursor` (400), a timeout or a network error.
+     */
+    listInvoices(params?: ListInvoicesParams): Promise<PaymentsList<Invoice>>;
+    /**
+     * Cancels an open invoice (`POST /v1/payments/invoices/:id/cancel`): it stops being payable; its number stays
+     * taken. A payment that arrives later is held for you. An underpaid invoice is closed as expired: refund what arrived.
+     *
+     * @param invoiceId - The invoice.
+     * @param params - `reason`, recorded in the ledger.
+     * @returns The invoice.
+     * @throws {QuasarSDKError} `invoice_not_found` (404), an invoice that is not open (409), a timeout or a network
+     *   error.
+     */
+    cancelInvoice(invoiceId: string, params?: {
+        reason?: string;
+    }): Promise<Invoice>;
+    /**
+     * Accepts a held payment (`POST /v1/payments/invoices/:id/release`): the invoice becomes paid and the buyer gets a
+     * receipt. A transfer Quasar could tie to no invoice is never an invoice hold: it is a {@link HeldTransfer} of its
+     * own, refunded with {@link PaymentsModule.refundHeldTransfer}.
+     *
+     * @param invoiceId - The invoice.
+     * @param params - `reason`, required, recorded in the ledger.
+     * @returns The invoice.
+     * @throws {QuasarSDKError} `invoice_not_found` (404); `invoice_not_held` or `invoice_partly_refunded` (refund the rest)
+     *   (409); a timeout or a network error.
+     */
+    releaseInvoice(invoiceId: string, params: {
+        reason: string;
+    }): Promise<Invoice>;
+    /**
+     * Corrects the buyer details of an open or paid invoice (`POST /v1/payments/invoices/:id/correct`): a credit note
+     * for it and a new invoice with the corrected details. A paid invoice's payment carries over to the new one.
+     *
+     * @param invoiceId - The invoice.
+     * @param params - The corrected buyer and the reason the credit note gives.
+     * @returns The new invoice (with its checkout while it is open) and the one it replaces.
+     * @throws {QuasarSDKError} `invalid_request` (400), `invoice_not_found` (404), an invoice that cannot be corrected
+     *   (409), a timeout or a network error.
+     */
+    correctInvoice(invoiceId: string, params: CorrectInvoiceParams): Promise<InvoiceCorrection>;
+    /**
+     * Gives an invoice, in any status, a new checkout token and payment page (`POST /v1/payments/invoices/:id/checkout`),
+     * for example when its link leaked. The earlier link stops working, also in the emails already sent, and so does the
+     * link of an invoice this one replaced; the current link needs no call: the invoice shows it (`payUrl`). The link of a
+     * settled invoice stops opening 90 days after it settled, unless its subscription still runs.
+     *
+     * @param invoiceId - The invoice.
+     * @returns The invoice with its new token and page.
+     * @throws {QuasarSDKError} `invoice_not_found` (404), a timeout or a network error.
+     */
+    replacePayLink(invoiceId: string): Promise<InvoiceWithCheckout>;
+    /**
+     * Reads a page of an invoice ledger, oldest first (`GET /v1/payments/invoices/:id/events`): up to 100 steps, with
+     * how many the ledger has, who created the invoice and when its quote was locked and its receipt issued. Every
+     * payment page a buyer opens locks a quote, so a ledger can be long.
+     *
+     * @param invoiceId - The invoice.
+     * @param params - `verify: true` adds the check of the whole hash chain; `limit` and `cursor` page it.
+     * @returns One page; pass `nextCursor` as `cursor` for the next.
+     * @throws {QuasarSDKError} `invoice_not_found` (404), `invalid_request` or `invalid_cursor` (400), a timeout or a
+     *   network error.
+     */
+    getEvents(invoiceId: string, params?: GetEventsParams): Promise<InvoiceLedger>;
+    /**
+     * Shows what a refund would send, without asking for it (`POST /v1/payments/invoices/:id/refunds/preview`).
+     *
+     * @param invoiceId - The invoice.
+     * @param params - Amount (everything left when omitted), mode and reason, as for {@link PaymentsModule.refund}.
+     * @returns What it would send now, what the payment brought, and this amount at the rate of the payment.
+     * @throws {QuasarSDKError} What {@link PaymentsModule.refund} would be refused with, a timeout or a network error.
+     */
+    previewRefund(invoiceId: string, params?: RefundParams): Promise<RefundPreview>;
+    /**
+     * Asks for a refund of a paid or held invoice (`POST /v1/payments/invoices/:id/refunds`). Send the returned amount
+     * from your wallet to the payer, then pass the transaction to {@link PaymentsModule.submitRefund}.
+     *
+     * @param invoiceId - The invoice.
+     * @param params - Amount (everything left when omitted), mode and reason.
+     * @param options - `idempotencyKey`: a retry with the same key answers the refund asked for first while it waits for
+     *   its transaction. Once it was sent, finished, failed or taken back the same key answers `refund_not_waiting` (409,
+     *   the refund in `details.refund`), so nothing is sent twice: a new refund needs a new key. `idempotency_key_reused`
+     *   (409): the key was used for another invoice, mode or amount.
+     * @returns The refund and what to send where.
+     * @throws {QuasarSDKError} `invalid_request` (400), `invoice_not_found` (404), an invoice that cannot be refunded or
+     *   an amount above what is left (409), a timeout or a network error.
+     */
+    refund(invoiceId: string, params?: RefundParams, options?: CreateOptions): Promise<RefundStart>;
+    /**
+     * Takes back a refund still waiting for its transaction (`POST /v1/payments/refunds/:id/withdraw`): it holds its amount
+     * until it goes out, and nothing else ends it. A refund continued later is priced again at the rate of then. Call
+     * `reset()` on a refund store that holds it (`createRefundStore`): it would still offer to send it, and Quasar would
+     * refuse to record what was sent.
+     *
+     * @param refundId - The refund.
+     * @returns The refund, `failed` as `withdrawn`.
+     * @throws {QuasarSDKError} `refund_not_found` (404), `refund_not_waiting` (409), a timeout or a network error.
+     */
+    withdrawRefund(refundId: string): Promise<Refund>;
+    /**
+     * Reads a refund (`GET /v1/payments/refunds/:id`).
+     *
+     * @param refundId - The refund.
+     * @returns The refund.
+     * @throws {QuasarSDKError} `refund_not_found` (404), a timeout or a network error.
+     */
+    getRefund(refundId: string): Promise<Refund>;
+    /**
+     * Hands Quasar the refund transaction (`POST /v1/payments/refunds/:id/submit`); once it is final, the refund is
+     * confirmed, a credit note issued and `refund.confirmed` sent.
+     *
+     * @param refundId - The refund.
+     * @param params - The transaction and your wallet it was sent from.
+     * @returns The refund, `submitted`.
+     * @throws {QuasarSDKError} `invalid_request` (400), `refund_not_found` (404), `refund_not_submittable` or
+     *   `transaction_already_used` (409: a transaction an invoice credited as a payment; one handed over as a payment
+     *   that paid nothing becomes the refund's), a timeout or a network error.
+     */
+    submitRefund(refundId: string, params: SubmitRefundParams): Promise<Refund>;
+    /**
+     * Lists held transfers, newest first (`GET /v1/payments/held-transfers`, or `GET /v1/payments/invoices/:id/held-transfers`
+     * with `invoice`): transfers that reached your invoices without being tied to them by proof, to refund to their senders.
+     *
+     * @param params - One invoice, one state (`held` for those still to refund), or neither.
+     * @returns The held transfers, at most 100.
+     * @throws {QuasarSDKError} a timeout or a network error.
+     */
+    listHeldTransfers(params?: ListHeldTransfersParams): Promise<HeldTransfer[]>;
+    /**
+     * Asks for the refund of a held transfer, the whole of it to the wallet that sent it
+     * (`POST /v1/payments/held-transfers/:id/refund`): send it from your wallet, then hand the transaction over with
+     * {@link PaymentsModule.submitRefund}. The refund's `heldTransfer` names the transfer, which becomes `refunding`, then
+     * `refunded` once the refund is confirmed.
+     *
+     * @param heldTransferId - The held transfer.
+     * @returns The refund and what to send where.
+     * @throws {QuasarSDKError} `held_transfer_not_found` (404); `held_transfer_not_refundable` (it is not `held`) or
+     *   `sender_blocked` (AML blocked the wallet that sent it) (409); a timeout or a network error.
+     */
+    refundHeldTransfer(heldTransferId: string): Promise<RefundStart>;
+    /**
+     * Downloads a stored document of an invoice byte for byte as issued
+     * (`GET /v1/payments/invoices/:id/documents/:kind`).
+     *
+     * @param invoiceId - The invoice.
+     * @param kind - `invoice` or `receipt` (PDF), or `invoice.xml` (UBL).
+     * @returns The bytes, media type and file name.
+     * @throws {QuasarSDKError} `invoice_not_found` or `document_not_found` (404), a timeout or a network error.
+     */
+    getDocument(invoiceId: string, kind: PaymentDocumentKind): Promise<PaymentDocument>;
+    /**
+     * Downloads a credit note of an invoice (`GET /v1/payments/invoices/:id/documents/credit-note/:ref`).
+     *
+     * @param invoiceId - The invoice.
+     * @param ref - The refund it credits, or its number.
+     * @param format - `pdf` (default) or `ubl`.
+     * @returns The bytes, media type and file name.
+     * @throws {QuasarSDKError} `invoice_not_found` or `document_not_found` (404), a timeout or a network error.
+     */
+    getCreditNote(invoiceId: string, ref: string, format?: 'pdf' | 'ubl'): Promise<PaymentDocument>;
+    /**
+     * Prices an amount in a payment method now (`POST /v1/payments/quotes`); nothing is locked.
+     *
+     * @param params - Amount, currency and method.
+     * @returns The price.
+     * @throws {QuasarSDKError} `invalid_request` (400), `method_not_found` (404), no fresh price (503), a timeout or a
+     *   network error.
+     */
+    quote(params: QuoteParams): Promise<PaymentQuote>;
+    /**
+     * Lists the app's active payment methods, in their order (`GET /v1/payments/methods`).
+     *
+     * @returns The methods.
+     * @throws {QuasarSDKError} A timeout or a network error.
+     */
+    listMethods(): Promise<{
+        object: 'list';
+        data: PaymentMethod[];
+    }>;
+    /**
+     * Starts a subscription (`POST /v1/payments/subscriptions`): each period is one invoice, issued ahead of the period
+     * and paid like any invoice (`send_invoice`) or charged with the buyer's ERC-7715 permission (`auto_charge`).
+     *
+     * @param params - The plan, its interval and terms.
+     * @param options - `idempotencyKey`: a retry with the same key returns the subscription started first.
+     * @returns The subscription and, without a trial, its first invoice with the payment page.
+     * @throws {QuasarSDKError} `invalid_request` (400), `subscriptions_disabled` (403), `auto_charge_unavailable` with
+     *   `details.reason` (400), a timeout or a network error.
+     */
+    createSubscription(params: CreateSubscriptionParams, options?: CreateOptions): Promise<SubscriptionStart>;
+    /**
+     * Lists subscriptions, newest first (`GET /v1/payments/subscriptions`).
+     *
+     * @param params - Filters and paging.
+     * @returns One page.
+     * @throws {QuasarSDKError} `invalid_request` or `invalid_cursor` (400), a timeout or a network error.
+     */
+    listSubscriptions(params?: ListSubscriptionsParams): Promise<PaymentsList<Subscription>>;
+    /**
+     * Reads a subscription (`GET /v1/payments/subscriptions/:id`). The invoices of its periods and its automatic
+     * charges are lists of their own: {@link PaymentsModule.listSubscriptionInvoices} and
+     * {@link PaymentsModule.listSubscriptionCharges}.
+     *
+     * @param subscriptionId - The subscription.
+     * @returns The subscription.
+     * @throws {QuasarSDKError} `subscription_not_found` (404), a timeout or a network error.
+     */
+    getSubscription(subscriptionId: string): Promise<Subscription>;
+    /**
+     * Lists the invoices of a subscription's periods, newest first (`GET /v1/payments/subscriptions/:id/invoices`).
+     *
+     * @param subscriptionId - The subscription.
+     * @param params - Paging.
+     * @returns One page; pass `nextCursor` as `cursor` for the next.
+     * @throws {QuasarSDKError} `subscription_not_found` (404), `invalid_request` or `invalid_cursor` (400), a timeout
+     *   or a network error.
+     */
+    listSubscriptionInvoices(subscriptionId: string, params?: ListSubscriptionItemsParams): Promise<PaymentsList<Invoice>>;
+    /**
+     * Lists the automatic charges of a subscription, newest first (`GET /v1/payments/subscriptions/:id/charges`).
+     *
+     * @param subscriptionId - The subscription.
+     * @param params - Paging.
+     * @returns One page; pass `nextCursor` as `cursor` for the next.
+     * @throws {QuasarSDKError} `subscription_not_found` (404), `invalid_request` or `invalid_cursor` (400), a timeout
+     *   or a network error.
+     */
+    listSubscriptionCharges(subscriptionId: string, params?: ListSubscriptionItemsParams): Promise<PaymentsList<SubscriptionCharge>>;
+    /**
+     * Cancels a subscription now (its open invoices are cancelled) or when the running period ends
+     * (`POST /v1/payments/subscriptions/:id/cancel`).
+     *
+     * @param subscriptionId - The subscription.
+     * @param params - `atPeriodEnd` and `reason`.
+     * @returns The subscription.
+     * @throws {QuasarSDKError} `subscription_not_found` (404), `subscription_not_active` (409), a timeout or a network
+     *   error.
+     */
+    cancelSubscription(subscriptionId: string, params?: CancelSubscriptionParams): Promise<Subscription>;
+    /**
+     * Takes back a cancellation scheduled for the period end (`POST /v1/payments/subscriptions/:id/cancel/undo`): the
+     * subscription renews again (`subscription.cancel_unscheduled`). Nothing scheduled: nothing changes.
+     *
+     * @param subscriptionId - The subscription.
+     * @returns The subscription.
+     * @throws {QuasarSDKError} `subscription_not_found` (404), a canceled or ended subscription (409), a timeout or a
+     *   network error.
+     */
+    undoSubscriptionCancel(subscriptionId: string): Promise<Subscription>;
+    /**
+     * Ends the automatic-charge permission of a subscription (`POST /v1/payments/subscriptions/:id/permission/end`), for a
+     * buyer who lost the wallet: Quasar charges it no more, and the buyer pays from the invoice links or gives a new
+     * permission. The delegation stays valid on chain until its wallet revokes it, but Quasar does not use it again.
+     *
+     * @param subscriptionId - The subscription.
+     * @returns The subscription.
+     * @throws {QuasarSDKError} `subscription_not_found` (404), `permission_not_active` (409), a timeout or a network error.
+     */
+    endSubscriptionPermission(subscriptionId: string): Promise<Subscription>;
+    /**
+     * Pauses a subscription (`POST /v1/payments/subscriptions/:id/pause`): its open invoices are cancelled and no period
+     * is billed until it resumes.
+     *
+     * @param subscriptionId - The subscription.
+     * @returns The subscription.
+     * @throws {QuasarSDKError} `subscription_not_found` (404), `subscription_not_active` (409), a timeout or a network
+     *   error.
+     */
+    pauseSubscription(subscriptionId: string): Promise<Subscription>;
+    /**
+     * Resumes a paused subscription (`POST /v1/payments/subscriptions/:id/resume`) with a new period that starts now
+     * and is invoiced at once.
+     *
+     * @param subscriptionId - The subscription.
+     * @returns The subscription and the new period's invoice with its payment page.
+     * @throws {QuasarSDKError} `subscription_not_found` (404), `subscription_not_paused` or `subscription_over` (409),
+     *   a timeout or a network error.
+     */
+    resumeSubscription(subscriptionId: string): Promise<SubscriptionStart>;
 }
 
 /**
@@ -216,7 +563,7 @@ declare class PulsarModule {
      * Sends the hash of the transaction that executed an EIP-5792 batch (`POST /v1/engine/pulsar/sync/:txKey/hash`). A
      * batch is synced by its batch ID (`TransactionTracker.EIP5792`), which only the wallet can resolve; with the hash,
      * Quasar tracks it on-chain until it reaches a final status. Get the hashes in the browser with
-     * {@link watchBatchHashes} and send each through a Server Action. Without a hash, Quasar marks the batch `Failed`
+     * `watchBatchHashes` from `@tuwaio/quasar-sdk/pulsar` and send each through a Server Action. Without a hash, Quasar marks the batch `Failed`
      * an hour after it was synced.
      *
      * @param txKey - The batch ID, the `txKey` of the transaction.
@@ -256,51 +603,6 @@ declare class PulsarModule {
     getHistory(query?: HistoryQuery): Promise<PaginatedResult<Transaction>>;
 }
 
-/**
- * @file Hashes of EIP-5792 batches, read from a Pulsar store in the browser.
- */
-
-/**
- * The part of a Pulsar store that {@link watchBatchHashes} reads: the store returned by `createPulsarStore` of
- * `@tuwaio/pulsar-core` has it.
- *
- * @typeParam T - The transaction type of the store.
- */
-interface PulsarPoolStore<T extends Transaction> {
-    /** Returns the current state of the store. */
-    getState: () => {
-        transactionsPool: Record<string, T>;
-    };
-    /** Calls `listener` with the new state on every change; returns the function that removes it. */
-    subscribe: (listener: (state: {
-        transactionsPool: Record<string, T>;
-    }) => void) => () => void;
-}
-/**
- * Watches a Pulsar store for EIP-5792 batches whose transaction became known and calls `onHash` once for each, so the
- * app can send the hash to Quasar with `PulsarModule.syncHash` (through a Server Action, since that call needs the
- * secret key). A batch is reported once Quasar has it (`syncStatus: 'synced'`) and Pulsar wrote its `hash`; batches
- * created more than an hour ago are skipped, because Quasar no longer waits for them. When `onHash` rejects, the batch
- * is reported again on the next change of the store.
- *
- * Side effects: subscribes to the store until the returned function is called; keeps the reported batch IDs in memory.
- *
- * @param store - The Pulsar store, for example the one `createPulsarStore` returns.
- * @param onHash - Called with each batch and its hash; return its promise so a failure is retried.
- * @returns A function that stops watching.
- *
- * @example
- * ```ts
- * import { watchBatchHashes } from '@tuwaio/quasar-sdk';
- *
- * // In the browser, next to the store; `syncBatchHash` is a Server Action that calls `quasar.pulsar.syncHash`
- * const stop = watchBatchHashes(pulsarStore, (tx) => syncBatchHash(tx.txKey, tx.hash));
- * ```
- */
-declare function watchBatchHashes<T extends Transaction>(store: PulsarPoolStore<T>, onHash: (tx: T & {
-    hash: `0x${string}`;
-}) => void | Promise<void>): () => void;
-
 /**
  * @file The `Quasar` client, the entry point of the Quasar API.
  */
@@ -326,6 +628,8 @@ declare class Quasar {
     private readonly client;
     /** Syncs Pulsar transactions to Quasar and reads their history. */
     readonly pulsar: PulsarModule;
+    /** Invoices, refunds, documents and subscriptions of a Payments app. */
+    readonly payments: PaymentsModule;
     /**
      * Creates the client. Sends no request.
      *
@@ -335,5 +639,235 @@ declare class Quasar {
     constructor(config: QuasarConfig);
 }
 
-export { BASE_API_URL, PULSAR_HISTORY_ENDPOINT, PULSAR_SYNC_ENDPOINT, PulsarModule, Quasar, QuasarSDKError, pulsarSyncHashEndpoint, watchBatchHashes };
-export type { HistoryQuery, PaginatedResult, PulsarPoolStore, QuasarConfig };
+/**
+ * @file Verification of Quasar webhooks: the HMAC-SHA256 signature of the raw body and the time deliveries were sent;
+ * and the types of their bodies.
+ */
+
+/** The header that carries the signature of a webhook: the hex HMAC-SHA256 of the raw body, keyed with the secret. */
+declare const WEBHOOK_SIGNATURE_HEADER = "x-quasar-signature";
+/** `apiVersion` of payment webhook bodies. */
+declare const PAYMENT_WEBHOOK_VERSION = "payments.v1";
+/** Types of payment webhook events. */
+type PaymentWebhookEventType = 'invoice.issued' | 'invoice.processing' | 'invoice.paid' | 'invoice.underpaid' | 'invoice.held' | 'invoice.transfer_held' | 'invoice.transfer_hold_voided' | 'invoice.released' | 'invoice.expired' | 'invoice.cancelled' | 'invoice.refunded' | 'invoice.partially_refunded' | 'invoice.replaced' | 'refund.confirmed' | 'refund.failed' | 'payment.reverted' | 'payment.unverified' | 'subscription.created' | 'subscription.renewed' | 'subscription.past_due' | 'subscription.paused' | 'subscription.resumed' | 'subscription.cancel_scheduled' | 'subscription.cancel_unscheduled' | 'subscription.canceled' | 'subscription.ended' | 'subscription.permission_granted' | 'subscription.charge_failed' | 'subscription.permission_revoked' | 'subscription.invoice_refused';
+/**
+ * What a hold is about (`data.hold` of `invoice.held`): an invoice paid in a way that waits for your decision. `reason`
+ * (`late`, `aml`, `quote_expired`), its transaction (`txHash`) and network (`chainId`), the wallets that sent it
+ * (`senders`) and whether it came late (`late`). Release it with {@link PaymentsModule.releaseInvoice} or refund it; a refund to a wallet AML blocks now
+ * is refused (`sender_blocked`).
+ */
+interface PaymentWebhookHold {
+    /** Why the payment is held; `null` when Quasar did not record why. */
+    reason: 'late' | 'aml' | 'quote_expired' | null;
+    /** The transaction of the held payment. */
+    txHash: string | null;
+    /** CAIP-2 chain of the transaction; Quasar versions before November 10, 2026 leave it out. */
+    chainId?: string | null;
+    /** The wallets that sent it. */
+    senders?: string[];
+    /** It arrived after the invoice expired or was cancelled, or was handed over after `dueAt`. */
+    late?: true;
+}
+/**
+ * A transfer that reached the invoice's address without being tied to it by proof (`data.heldTransfer` of
+ * `invoice.transfer_held`): it paid nothing and the invoice stays as it was. It is a record of its own, which you
+ * refund as a whole to the wallet that sent it ({@link PaymentsModule.refundHeldTransfer}): `reason` is
+ * `payer_mismatch` (another wallet than the one the quote was for), `payer_unconfirmed` (the quoted wallet never
+ * confirmed the invoice), `reference_missing` (a Solana Pay transfer without the invoice's reference whose amount does
+ * not tie it to the invoice either), `already_paid`, `quote_changed` or `too_many_parts`.
+ */
+interface PaymentWebhookHeldTransfer {
+    /** Not set: the transfer is held. */
+    voided?: undefined;
+    /** The held transfer ({@link HeldTransfer}). */
+    id: string | null;
+    /** Its transaction. */
+    txHash: string | null;
+    /** CAIP-2 chain of the transaction; Quasar versions before November 10, 2026 leave it out. */
+    chainId?: string | null;
+    /** What it carried, in base units of its token. */
+    amount: string | null;
+    /** The wallets that sent it. */
+    senders: string[];
+    /** Why it is tied to no invoice. */
+    reason: 'payer_mismatch' | 'payer_unconfirmed' | 'reference_missing' | 'already_paid' | 'quote_changed' | 'too_many_parts' | null;
+    /** It arrived after the invoice expired or was cancelled. */
+    late?: true;
+    /** Set when AML blocked its sender: Quasar refunds it to no one. */
+    screening?: {
+        status: 'blocked';
+        reasons: unknown[];
+    };
+}
+/**
+ * A held transfer Quasar voided (`data.heldTransfer` of `invoice.transfer_hold_voided`): the same transaction was
+ * proven to pay another invoice of yours since (`paidInvoice`), so there is nothing to refund.
+ */
+interface PaymentWebhookHeldTransferVoided {
+    /** The held transfer. */
+    id: string | null;
+    /** Always `true`. */
+    voided: true;
+    /** Its transaction. */
+    txHash: string | null;
+    /** CAIP-2 chain of the transaction; Quasar versions before November 10, 2026 leave it out. */
+    chainId?: string | null;
+    /** The invoice the transaction paid instead. */
+    paidInvoice: string | null;
+}
+/**
+ * The body of a payment webhook (`payments.v1`). `id`, `type` and `createdAt` are those of the ledger event, so
+ * deduplicate by `id`; `data.invoice` is the invoice when the delivery was sent, so a retry carries its current state.
+ */
+interface PaymentWebhookEvent {
+    /** Event ID: the same for every delivery and retry of the event. */
+    id: string;
+    /** Always `event`. */
+    object: 'event';
+    /** Always `payments.v1`. */
+    apiVersion: typeof PAYMENT_WEBHOOK_VERSION;
+    /** What happened. */
+    type: PaymentWebhookEventType;
+    /** When it happened (ISO 8601). */
+    createdAt: string;
+    /** When this delivery was sent; signed with the body, it lets {@link verifyWebhook} refuse old replays. */
+    sentAt: string;
+    /** Live or test. */
+    environment: PaymentsEnvironment;
+    /** What the event is about. */
+    data: {
+        /** The invoice now (subscription events carry the invoice of their period, when there is one). */
+        invoice?: Invoice;
+        /** The payment, once the invoice has one. */
+        settlement?: InvoiceSettlement;
+        /**
+         * Every transfer credited to the invoice so far, on `invoice.paid`, `invoice.underpaid`, `invoice.held` and
+         * `invoice.released`: an invoice paid in parts has several.
+         */
+        payments?: InvoicePayment[];
+        /** The refund of a refund event. */
+        refund?: Refund;
+        /** Why AML held the payment, on a hold by AML. */
+        aml?: {
+            decision: 'block';
+            reasons: unknown[];
+        };
+        /** What `invoice.held` holds. Quasar versions before October 29, 2026 leave it out. */
+        hold?: PaymentWebhookHold;
+        /**
+         * The transfer of `invoice.transfer_held` and `invoice.transfer_hold_voided`. The refund of a held transfer names
+         * it in `refund.heldTransfer`.
+         */
+        heldTransfer?: PaymentWebhookHeldTransfer | PaymentWebhookHeldTransferVoided;
+        /** The transaction to check, in `payment.reverted` and `payment.unverified`. */
+        transaction?: {
+            txHash: string | null;
+            chainId: string | null;
+        };
+        /** The subscription of a subscription event. */
+        subscription?: Subscription;
+    };
+}
+/** The body of a transaction webhook: a synced Pulsar transaction reached a final status. */
+interface TransactionWebhookEvent {
+    /** Key of the Pulsar transaction. */
+    txKey: string;
+    /** Its on-chain hash, when it has one. */
+    hash?: string;
+    /** Final status: `Success`, `Failed` or `Replaced`. */
+    status: string;
+    /** The same as `status`; also sent in the `x-quasar-event` header. */
+    action: string;
+    /** The `type` of the Pulsar transaction. */
+    txType?: string;
+    /** Its chain: the EVM chain ID (`"1"`) or the Solana CAIP-2 chain ID. */
+    chainId: string;
+    /** Unix time in seconds when the webhook was created. */
+    timestamp: number;
+    /**
+     * When this delivery attempt was sent (ISO 8601), signed with the body. Quasar engines released before Payments omit
+     * it; {@link verifyWebhook} then checks `timestamp`.
+     */
+    sentAt?: string;
+    /** The `payload` of the Pulsar transaction. */
+    metadata?: unknown;
+}
+/** A verified webhook body: a payment event or a transaction webhook. Tell them apart with {@link isPaymentWebhookEvent}. */
+type QuasarWebhook = PaymentWebhookEvent | TransactionWebhookEvent;
+/** Why {@link verifyWebhook} refused a delivery. */
+type QuasarWebhookErrorCode = 'missing_secret' | 'missing_signature' | 'invalid_signature' | 'invalid_body' | 'invalid_options' | 'stale';
+/** Error thrown by {@link verifyWebhook}: answer the delivery with 400 (or 401) and do not act on it. */
+declare class QuasarWebhookError extends Error {
+    /** Why the delivery was refused. */
+    readonly code: QuasarWebhookErrorCode;
+    /**
+     * Creates the error.
+     *
+     * @param code - Why the delivery was refused.
+     * @param message - What to log.
+     */
+    constructor(code: QuasarWebhookErrorCode, message: string);
+}
+/** What {@link verifyWebhook} takes. */
+interface VerifyWebhookParams {
+    /** The request body exactly as received, before any parsing: a string or its bytes. */
+    body: string | Uint8Array;
+    /** The value of the `x-quasar-signature` header. */
+    signature: string | null | undefined;
+    /** The signing secret of the webhook endpoint. */
+    secret: string;
+    /**
+     * How far the send time may be from now, in seconds: a finite number above 0, or `false` to turn the check off
+     * (`0`, a negative number, `NaN` or `Infinity` throw `invalid_options`). Defaults to `300`. The send time is
+     * `sentAt`; a transaction webhook of an engine that sends no `sentAt` is checked by its `timestamp`, the time it was
+     * created, which its retries reuse, so a retry later than the tolerance is refused.
+     */
+    toleranceSeconds?: number | false;
+    /** The current time, for tests. Defaults to now. */
+    now?: Date;
+}
+/**
+ * Whether a verified webhook is a payment event (`apiVersion: 'payments.v1'`) rather than a transaction webhook.
+ *
+ * @param event - A body returned by {@link verifyWebhook}.
+ * @returns `true` for a payment event.
+ */
+declare function isPaymentWebhookEvent(event: QuasarWebhook): event is PaymentWebhookEvent;
+/**
+ * Verifies a Quasar webhook and returns its body. Checks the signature (`x-quasar-signature`, the hex HMAC-SHA256 of
+ * the raw body keyed with the endpoint's signing secret) in constant time, parses the body and refuses a delivery
+ * whose send time (`sentAt`, falling back to `timestamp` for older transaction webhooks) is further from now than
+ * `toleranceSeconds` (a replay of an old delivery). Uses Web Crypto, so it runs in Node.js 20+, edge runtimes and
+ * Workers. Payment events are delivered at least once: deduplicate them by `id`.
+ *
+ * @param params - The raw body, the signature header, the secret and the tolerance.
+ * @returns The body: a {@link PaymentWebhookEvent} or a {@link TransactionWebhookEvent}.
+ * @throws {QuasarWebhookError} `missing_secret`, `missing_signature`, `invalid_signature`, `invalid_body` (not a
+ *   JSON object), `invalid_options` (an invalid `toleranceSeconds`) or `stale` (an event outside the tolerance or
+ *   missing its send time).
+ *
+ * @example
+ * ```ts
+ * import { isPaymentWebhookEvent, verifyWebhook } from '@tuwaio/quasar-sdk';
+ *
+ * export async function POST(request: Request) {
+ *   try {
+ *     const event = await verifyWebhook({
+ *       body: await request.text(),
+ *       signature: request.headers.get('x-quasar-signature'),
+ *       secret: process.env.QUASAR_WEBHOOK_SECRET ?? '',
+ *     });
+ *     if (isPaymentWebhookEvent(event) && event.type === 'invoice.paid') {
+ *       await fulfil(event.data.invoice?.metadata?.orderId);
+ *     }
+ *     return new Response(null, { status: 204 });
+ *   } catch {
+ *     return new Response(null, { status: 400 });
+ *   }
+ * }
+ * ```
+ */
+declare function verifyWebhook(params: VerifyWebhookParams): Promise<QuasarWebhook>;
+
+export { BASE_API_URL, CancelSubscriptionParams, CorrectInvoiceParams, CreateInvoiceParams, CreateOptions, CreateSubscriptionParams, GetEventsParams, HeldTransfer, Invoice, InvoiceCorrection, InvoiceDetails, InvoiceDocumentRef, InvoiceLedger, InvoicePayment, InvoiceSettlement, InvoiceWithCheckout, ListHeldTransfersParams, ListInvoiceItemsParams, ListInvoicesParams, ListSubscriptionItemsParams, ListSubscriptionsParams, PAYMENTS_ENDPOINT, PAYMENT_WEBHOOK_VERSION, PULSAR_HISTORY_ENDPOINT, PULSAR_SYNC_ENDPOINT, PaymentDocument, PaymentDocumentKind, PaymentMethod, PaymentQuote, PaymentsEnvironment, PaymentsList, PaymentsModule, PulsarModule, Quasar, QuasarWebhookError, QuoteParams, Refund, RefundParams, RefundPreview, RefundStart, SubmitRefundParams, Subscription, SubscriptionCharge, SubscriptionStart, WEBHOOK_SIGNATURE_HEADER, isPaymentWebhookEvent, pulsarSyncHashEndpoint, verifyWebhook };
+export type { HistoryQuery, PaginatedResult, PaymentWebhookEvent, PaymentWebhookEventType, PaymentWebhookHeldTransfer, PaymentWebhookHeldTransferVoided, PaymentWebhookHold, QuasarConfig, QuasarWebhook, QuasarWebhookErrorCode, TransactionWebhookEvent, VerifyWebhookParams };