@fantastic.dev/better-stripe 0.20.1 → 0.22.0

package/CHANGELOG.md

@@ -14,6 +14,18 @@
 - Remove internal tracker references from public documentation and add a
   regression check that prevents their reintroduction.
 
+## [0.22.0](https://github.com/FantasticDevHQ/better-stripe/compare/v0.21.0...v0.22.0) (2026-10-15)
+
+### Features
+
+- **payouts:** qualify and execute combined recipient releases ([#189](https://github.com/FantasticDevHQ/better-stripe/issues/189)) ([08f4cec](https://github.com/FantasticDevHQ/better-stripe/commit/08f4cecf004635caa42255d4171206e35bda181c))
+
+## [0.21.0](https://github.com/FantasticDevHQ/better-stripe/compare/v0.20.1...v0.21.0) (2026-10-15)
+
+### Features
+
+- **payouts:** reconcile verified payout outcomes and fees ([#187](https://github.com/FantasticDevHQ/better-stripe/issues/187)) ([7f14edb](https://github.com/FantasticDevHQ/better-stripe/commit/7f14edb93dcc2c7808f1e3e3f3a8dbe2ff84ad3d))
+
 ## [0.20.1](https://github.com/FantasticDevHQ/better-stripe/compare/v0.20.0...v0.20.1) (2026-10-15)
 
 ### Documentation

package/README.md

@@ -42,14 +42,18 @@ deadline-expiry API. See [policy setup and limits](docs/settlement.md#recipient-
 A [recipient funding reader](docs/settlement.md#verified-recipient-funding-receipts)
 verifies original and reversal receipts, maturity, and exact settlement amounts;
 received credit is kept distinct from still-unpaid entitlement.
-The component also has an internal transactional claim ledger for reservations
-and paid allocations. Automatic combined release and adoption of existing
-balances still require the separate release boundary; schedule controls and
-claim primitives alone do not enforce a minimum.
+A [payout receipt and reconciliation API](docs/settlement.md#verified-payout-receipts-and-reconciliation)
+verifies actual bank-payout debits and returns, adopts an attempted claim's
+provider outcome, and books its net payout fees once.
+The [combined release API](docs/settlement.md#combined-recipient-release) verifies
+complete source and payout history, reserves mature unpaid funds, and creates an
+idempotent bank payout. Install a host job to invoke it and expire due policies.
+Existing unallocated balances, larger histories and other debit allocations still
+require migration; schedule controls alone do not enforce a minimum.
 
 ## Status
 
-**Version**: `0.20.1` <!-- x-release-please-version --> (pre-1.0). API may change between minor versions until 1.0.
+**Version**: `0.22.0` <!-- x-release-please-version --> (pre-1.0). API may change between minor versions until 1.0.
 
 Used in production by its authors. Webhook pipeline is covered by unit tests and a live E2E harness (`npm run e2e:webhooks`) that fires real Stripe-signed events and asserts the ledger.
 
@@ -131,6 +135,13 @@ existing integration to this API version.
 
 The component ships committed Convex codegen output at `src/component/_generated/{api,component,dataModel,server}.ts` — consumers reach the bindings via the `./_generated/component` subpath export. The example app also commits its own codegen at `example/convex/_generated/`. Running `pnpm dev` (which wraps `convex dev`) regenerates these automatically when the schema or function definitions change, but only against the live dev deployment and only while the dev server is watching.
 
+The example resolves the workspace package through `dist/`. After changing
+component source, regenerate library bindings with `pnpm codegen:lib`, run
+`pnpm build`, then deploy the rebuilt component from the example directory with
+`pnpm exec convex dev --once`. Run `pnpm codegen:example` afterward. Code generation
+alone does not prove that a newly added function is mounted; invoke a representative
+query or action against the development deployment before running financial tests.
+
 If you add, remove, or rename a query/mutation/action on a branch without the dev server watching — or after a rebase — regenerate explicitly before committing:
 
 ```bash

package/dist/client/connect/payoutExecution.d.ts

@@ -0,0 +1,34 @@
+import type Stripe from "stripe";
+import type { Infer } from "convex/values";
+import type { Component, RunCtx } from "../helpers.js";
+import type { policyDoc } from "../../component/payoutPolicy/schema.js";
+import { type PayoutReconciliation } from "./payoutReconciliation.js";
+type Policy = Infer<typeof policyDoc>;
+export type PayoutReleaseOptions = {
+    accountId: string;
+    ownerKey: string;
+    operationKey: string;
+    currency: string;
+    /** Host supplies all authorized off-provider debts/reserves, without double counting provider receipt debits. */
+    independentLiabilities: number;
+    maxPages?: number;
+};
+type Held = {
+    status: "held";
+    reason: string;
+};
+export type PayoutReleaseResult = PayoutReconciliation | Held;
+/**
+ * Complete receipt qualification followed by an atomic claim and one immutable
+ * provider request. Host authorizes the recipient, policy, operation and known
+ * off-provider liabilities. Attempted operations only reconcile on subsequent
+ * calls; they are never blindly recreated after an unknown provider outcome.
+ */
+export declare function releaseRecipientPayout(stripe: Stripe, component: Component, ctx: RunCtx, opts: PayoutReleaseOptions, verify: () => Promise<{
+    status: "verified";
+    policy: Policy;
+} | {
+    status: string;
+}>): Promise<PayoutReleaseResult>;
+export {};
+//# sourceMappingURL=payoutExecution.d.ts.map

package/dist/client/connect/payoutExecution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payoutExecution.d.ts","sourceRoot":"","sources":["../../../src/client/connect/payoutExecution.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AACjC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAKvD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wCAAwC,CAAC;AAUxE,OAAO,EAEL,KAAK,oBAAoB,EAC1B,MAAM,2BAA2B,CAAC;AAEnC,KAAK,MAAM,GAAG,KAAK,CAAC,OAAO,SAAS,CAAC,CAAC;AACtC,MAAM,MAAM,oBAAoB,GAAG;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,iHAAiH;IACjH,sBAAsB,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AACF,KAAK,IAAI,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAC/C,MAAM,MAAM,mBAAmB,GAAG,oBAAoB,GAAG,IAAI,CAAC;AAQ9D;;;;;GAKG;AACH,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,SAAS,EACpB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,oBAAoB,EAC1B,MAAM,EAAE,MAAM,OAAO,CACnB;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,CAC5D,GACA,OAAO,CAAC,mBAAmB,CAAC,CAiN9B"}

package/dist/client/connect/payoutExecution.js

@@ -0,0 +1,189 @@
+import { runMutationOrThrow } from "../helpers.js";
+import { componentRef } from "../webhooks/helpers.js";
+import { transferFingerprint, validateIdentity, } from "../../component/payoutRelease/helpers.js";
+import { getTransferFundingReceipt, } from "./transferReceipt.js";
+import { verifyPayoutHistory } from "./payoutHistory.js";
+import { reconcileRecipientPayout, } from "./payoutReconciliation.js";
+/**
+ * Complete receipt qualification followed by an atomic claim and one immutable
+ * provider request. Host authorizes the recipient, policy, operation and known
+ * off-provider liabilities. Attempted operations only reconcile on subsequent
+ * calls; they are never blindly recreated after an unknown provider outcome.
+ */
+export async function releaseRecipientPayout(stripe, component, ctx, opts, verify) {
+    validateIdentity(opts);
+    if (!/^[a-z]{3}$/.test(opts.currency) ||
+        !Number.isSafeInteger(opts.independentLiabilities) ||
+        opts.independentLiabilities < 0)
+        throw new Error("Invalid payout currency or independent liabilities.");
+    const maxPages = opts.maxPages ?? 10;
+    if (!Number.isInteger(maxPages) || maxPages < 1 || maxPages > 100)
+        throw new Error("Payout page budget must be between 1 and 100.");
+    if (!ctx.runMutation)
+        throw new Error("Payout release requires runMutation.");
+    const identity = {
+        accountId: opts.accountId,
+        ownerKey: opts.ownerKey,
+        operationKey: opts.operationKey,
+    };
+    const existing = (await ctx.runQuery(componentRef(component, "payoutRelease/queries/get"), identity));
+    if (existing) {
+        if (existing.currency !== opts.currency)
+            throw new Error("Payout claim currency cannot be changed.");
+        if (existing.attemptedAt !== undefined || existing.status !== "reserved")
+            return reconcileRecipientPayout(stripe, component, ctx, {
+                ...identity,
+                maxPages,
+            });
+        // A crash before the attempt has no provider side effect. Release its exact
+        // reservations; the next scheduled operation must collect fresh receipts.
+        const claim = (await runMutationOrThrow(ctx, componentRef(component, "payoutRelease/mutations/cancelUnattempted"), identity));
+        return { status: "terminal", claim };
+    }
+    const controls = await verify();
+    if (controls.status !== "verified" || !("policy" in controls))
+        return { status: "held", reason: controls.status };
+    const snapshot = (await ctx.runQuery(componentRef(component, "payoutRelease/queries/snapshot"), { accountId: opts.accountId, ownerKey: opts.ownerKey }));
+    if (snapshot.status !== "ready")
+        return snapshot;
+    const banks = [];
+    let bankCursor;
+    for (let page = 0;; page++) {
+        if (page >= maxPages)
+            return { status: "held", reason: "bank_history_incomplete" };
+        const batch = await stripe.accounts.listExternalAccounts(opts.accountId, {
+            object: "bank_account",
+            limit: 100,
+            ...(bankCursor ? { starting_after: bankCursor } : {}),
+        });
+        for (const bank of batch.data)
+            if (bank.object === "bank_account" &&
+                bank.currency === opts.currency &&
+                bank.default_for_currency &&
+                bank.status !== "errored")
+                banks.push(bank.id);
+        if (!batch.has_more)
+            break;
+        const next = batch.data[batch.data.length - 1]?.id;
+        if (!next || next === bankCursor)
+            return { status: "held", reason: "bank_history_incomplete" };
+        bankCursor = next;
+    }
+    if (banks.length !== 1 || !/^ba_\w+$/.test(banks[0]))
+        return { status: "held", reason: "bank_destination_unavailable" };
+    const destinationId = banks[0];
+    const transactions = [];
+    for (const claim of snapshot.claims) {
+        if (claim.currency !== opts.currency ||
+            claim.status === "canceled" ||
+            claim.status === "rejected")
+            continue;
+        if (claim.attemptedAt === undefined)
+            return { status: "held", reason: "pending_claim" };
+        const result = await reconcileRecipientPayout(stripe, component, ctx, {
+            accountId: opts.accountId,
+            ownerKey: opts.ownerKey,
+            operationKey: claim.operationKey,
+            maxPages,
+        });
+        if (result.status !== "updated")
+            return result;
+        for (const t of [result.receipt.debit, result.receipt.credit])
+            if (t)
+                transactions.push({ ...t, sourceId: result.receipt.stripePayoutId });
+    }
+    const observations = [];
+    for (const row of snapshot.transfers) {
+        const receipt = await getTransferFundingReceipt(stripe, component, ctx, {
+            accountId: opts.accountId,
+            stripeTransferId: row.stripeTransferId,
+        });
+        if (receipt.status !== "ready")
+            return { status: "held", reason: receipt.reason };
+        observations.push({
+            stripeTransferId: row.stripeTransferId,
+            currency: receipt.settlementCurrency,
+            matureNet: receipt.matureNet,
+            pendingCredits: receipt.pendingCredits,
+            ledgerFingerprint: transferFingerprint(row),
+            observedAt: receipt.observedAt,
+            transactionIds: receipt.transactions.map((t) => t.id),
+        });
+        if (receipt.settlementCurrency === opts.currency)
+            transactions.push(...receipt.transactions);
+    }
+    const history = await verifyPayoutHistory(stripe, {
+        accountId: opts.accountId,
+        currency: opts.currency,
+        transactions,
+        maxPages,
+    });
+    if (history.status !== "verified")
+        return history;
+    const claim = (await runMutationOrThrow(ctx, componentRef(component, "payoutRelease/mutations/claim"), {
+        ...identity,
+        expectedRevision: controls.policy.revision,
+        currency: opts.currency,
+        destinationId,
+        providerAvailable: history.providerAvailable,
+        independentLiabilities: opts.independentLiabilities,
+        observations,
+    }));
+    if (claim.status === "held")
+        return claim;
+    // Another caller can win this operation while receipts were being collected.
+    if (claim.attemptedAt !== undefined || claim.status !== "reserved")
+        return reconcileRecipientPayout(stripe, component, ctx, {
+            ...identity,
+            maxPages,
+        });
+    const latest = await verify();
+    if (latest.status !== "verified" ||
+        !("policy" in latest) ||
+        latest.policy.revision !== controls.policy.revision) {
+        await runMutationOrThrow(ctx, componentRef(component, "payoutRelease/mutations/cancelUnattempted"), identity);
+        return {
+            status: "held",
+            reason: latest.status === "verified" ? "policy_changed" : latest.status,
+        };
+    }
+    await runMutationOrThrow(ctx, componentRef(component, "payoutRelease/mutations/beginAttempt"), identity);
+    let payout;
+    try {
+        payout = await stripe.payouts.create({
+            amount: claim.amount,
+            currency: claim.currency,
+            destination: claim.destinationId,
+            method: "standard",
+            source_type: "card",
+            metadata: { bsPayoutClaim: claim.operationKey },
+        }, {
+            stripeAccount: claim.accountId,
+            idempotencyKey: `bs:payout-release:${claim.operationKey}`,
+        });
+    }
+    catch (error) {
+        if (error instanceof Error &&
+            "type" in error &&
+            error.type === "StripeInvalidRequestError" &&
+            "code" in error &&
+            ["balance_insufficient", "amount_too_small"].includes(String(error.code)) &&
+            "requestId" in error &&
+            typeof error.requestId === "string" &&
+            /^req_\w+$/.test(error.requestId)) {
+            const saved = (await runMutationOrThrow(ctx, componentRef(component, "payoutRelease/mutations/recordRejection"), {
+                ...identity,
+                requestId: error.requestId,
+                code: error.code,
+            }));
+            return { status: "terminal", claim: saved };
+        }
+        throw error;
+    }
+    return reconcileRecipientPayout(stripe, component, ctx, {
+        ...identity,
+        stripePayoutId: payout.id,
+        maxPages,
+    });
+}
+//# sourceMappingURL=payoutExecution.js.map

package/dist/client/connect/payoutExecution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"payoutExecution.js","sourceRoot":"","sources":["../../../src/client/connect/payoutExecution.ts"],"names":[],"mappings":"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"}

package/dist/client/connect/payoutHistory.d.ts

@@ -0,0 +1,22 @@
+import type Stripe from "stripe";
+import type { TransferReceiptTransaction } from "./transferReceipt.js";
+export type PayoutHistoryVerification = {
+    status: "verified";
+    providerAvailable: number;
+    observedAt: number;
+} | {
+    status: "held";
+    reason: "unallocated_history" | "history_changed" | "history_incomplete" | "balance_changed";
+};
+/**
+ * Verify a complete currency history against independently verified transfer and
+ * payout receipts. Unknown debits AND credits require explicit allocation. A
+ * current balance alone never establishes still-unpaid source ownership.
+ */
+export declare function verifyPayoutHistory(stripe: Stripe, opts: {
+    accountId: string;
+    currency: string;
+    transactions: TransferReceiptTransaction[];
+    maxPages?: number;
+}): Promise<PayoutHistoryVerification>;
+//# sourceMappingURL=payoutHistory.d.ts.map

package/dist/client/connect/payoutHistory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payoutHistory.d.ts","sourceRoot":"","sources":["../../../src/client/connect/payoutHistory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AACjC,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,sBAAsB,CAAC;AAEvE,MAAM,MAAM,yBAAyB,GACjC;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,iBAAiB,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GACrE;IACE,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EACF,qBAAqB,GACrB,iBAAiB,GACjB,oBAAoB,GACpB,iBAAiB,CAAC;CACvB,CAAC;AA+BN;;;;GAIG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE;IACJ,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,0BAA0B,EAAE,CAAC;IAC3C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GACA,OAAO,CAAC,yBAAyB,CAAC,CA4FpC"}

package/dist/client/connect/payoutHistory.js

@@ -0,0 +1,122 @@
+import { addSummaryAmounts as add } from "../../component/earnings/arithmetic.js";
+function fingerprint(t) {
+    return JSON.stringify([
+        t.id,
+        t.sourceId,
+        t.amount,
+        t.fee,
+        t.net,
+        t.currency,
+        t.created,
+        t.availableOn,
+        t.status,
+        t.type,
+    ]);
+}
+function normalize(t) {
+    if (t.status !== "available" && t.status !== "pending")
+        throw new Error("Invalid provider receipt status.");
+    return {
+        id: t.id,
+        sourceId: typeof t.source === "string" ? t.source : (t.source?.id ?? ""),
+        amount: t.amount,
+        fee: t.fee,
+        net: t.net,
+        currency: t.currency,
+        created: t.created,
+        availableOn: t.available_on,
+        status: t.status,
+        type: t.type,
+    };
+}
+/**
+ * Verify a complete currency history against independently verified transfer and
+ * payout receipts. Unknown debits AND credits require explicit allocation. A
+ * current balance alone never establishes still-unpaid source ownership.
+ */
+export async function verifyPayoutHistory(stripe, opts) {
+    const maxPages = opts.maxPages ?? 10;
+    if (!Number.isInteger(maxPages) || maxPages < 1 || maxPages > 100)
+        throw new Error("History page budget must be between 1 and 100.");
+    if (!/^acct_\w+$/.test(opts.accountId) || !/^[a-z]{3}$/.test(opts.currency))
+        throw new Error("Invalid payout history scope.");
+    const expected = new Map();
+    for (const t of opts.transactions) {
+        if (expected.has(t.id))
+            throw new Error("Duplicate payout history receipt.");
+        if (t.currency !== opts.currency ||
+            !/^txn_\w+$/.test(t.id) ||
+            !t.sourceId ||
+            [t.amount, t.fee, t.net, t.created, t.availableOn].some((n) => !Number.isSafeInteger(n)) ||
+            t.net !== add(t.amount, -t.fee))
+            throw new Error("Invalid payout history receipt.");
+        expected.set(t.id, fingerprint(t));
+    }
+    const scope = { stripeAccount: opts.accountId };
+    const seen = new Set();
+    let cursor, head;
+    let available = 0, pending = 0, complete = false;
+    const held = (reason) => ({ status: "held", reason });
+    for (let page = 0; page < maxPages; page++) {
+        const batch = await stripe.balanceTransactions.list({
+            currency: opts.currency,
+            limit: 100,
+            ...(cursor ? { starting_after: cursor } : {}),
+        }, scope);
+        if (page === 0 && batch.data[0])
+            head = fingerprint(normalize(batch.data[0]));
+        for (const raw of batch.data) {
+            const t = normalize(raw);
+            if (seen.has(t.id))
+                return held("history_incomplete");
+            seen.add(t.id);
+            if (!expected.has(t.id))
+                return held("unallocated_history");
+            if (fingerprint(t) !== expected.get(t.id))
+                return held("history_changed");
+            if (t.status === "available")
+                available = add(available, t.net);
+            else if (t.status === "pending")
+                pending = add(pending, t.net);
+            else
+                return held("history_changed");
+        }
+        if (!batch.has_more) {
+            complete = true;
+            break;
+        }
+        const next = batch.data[batch.data.length - 1]?.id;
+        if (!next || next === cursor)
+            return held("history_incomplete");
+        cursor = next;
+    }
+    if (!complete)
+        return held("history_incomplete");
+    if (seen.size !== expected.size)
+        return held("history_changed");
+    const balance = await stripe.balance.retrieve(undefined, scope);
+    const latest = await stripe.balanceTransactions.list({ currency: opts.currency, limit: 1 }, scope);
+    const latestHead = latest.data[0]
+        ? fingerprint(normalize(latest.data[0]))
+        : undefined;
+    if (latestHead !== head)
+        return held("history_changed");
+    const entries = (rows) => rows.filter((t) => t.currency === opts.currency);
+    const a = entries(balance.available), p = entries(balance.pending);
+    if (a.length > 1 ||
+        p.length > 1 ||
+        (a[0]?.amount ?? 0) !== available ||
+        (p[0]?.amount ?? 0) !== pending)
+        return held("balance_changed");
+    // The durable payout request explicitly draws from card balance. Other rails
+    // cannot increase this cap even if they contribute to aggregate availability.
+    const card = a[0]?.source_types?.card ?? 0;
+    if (!Number.isSafeInteger(card))
+        throw new Error("Invalid provider card balance.");
+    return {
+        status: "verified",
+        providerAvailable: Math.min(available, card),
+        observedAt: Date.now(),
+    };
+}
+//# sourceMappingURL=payoutHistory.js.map

package/dist/client/connect/payoutHistory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"payoutHistory.js","sourceRoot":"","sources":["../../../src/client/connect/payoutHistory.ts"],"names":[],"mappings":"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"}

package/dist/client/connect/payoutReceipt.d.ts

@@ -0,0 +1,53 @@
+import type Stripe from "stripe";
+import type { PayoutStatus } from "../../component/connect/validators.js";
+export type RecipientPayoutReceiptOptions = {
+    accountId: string;
+    stripePayoutId: string;
+    /** Required when adopting a provider payout into a previously attempted claim. */
+    operationKey?: string;
+};
+export type PayoutReceiptTransaction = {
+    id: string;
+    amount: number;
+    fee: number;
+    net: number;
+    currency: string;
+    status: "available" | "pending";
+    created: number;
+    availableOn: number;
+    type: string;
+};
+export type RecipientPayoutReceipt = {
+    status: "not_ready";
+    accountId: string;
+    stripePayoutId: string;
+    reason: "debit_unavailable" | "debit_pending" | "return_unavailable" | "return_pending" | "provider_changed" | "reversal_allocation_required" | "currency_allocation_required";
+} | {
+    status: "ready";
+    accountId: string;
+    stripePayoutId: string;
+    operationKey?: string;
+    amount: number;
+    currency: string;
+    providerStatus: PayoutStatus;
+    automatic: boolean;
+    method: string;
+    type: string;
+    sourceType: string;
+    destinationId: string;
+    created: number;
+    arrivalDate: number;
+    debit: PayoutReceiptTransaction;
+    credit?: PayoutReceiptTransaction;
+    returnedPrincipal: number;
+    returnedNet: number;
+    observedAt: number;
+};
+/**
+ * Read-only provider receipts, not unpaid entitlement or authorization to release
+ * a reservation. Fees remain separate from principal and must be accounted for
+ * by the payout/recovery ledger. Manual payout receipts do not identify the
+ * original transfers that funded them. Host authorizes access to this account.
+ */
+export declare function getRecipientPayoutReceipt(stripe: Stripe, options: RecipientPayoutReceiptOptions): Promise<RecipientPayoutReceipt>;
+//# sourceMappingURL=payoutReceipt.d.ts.map

package/dist/client/connect/payoutReceipt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payoutReceipt.d.ts","sourceRoot":"","sources":["../../../src/client/connect/payoutReceipt.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AACjC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uCAAuC,CAAC;AAC1E,MAAM,MAAM,6BAA6B,GAAG;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,kFAAkF;IAClF,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AACF,MAAM,MAAM,wBAAwB,GAAG;IACrC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,WAAW,GAAG,SAAS,CAAC;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AACF,MAAM,MAAM,sBAAsB,GAC9B;IACE,MAAM,EAAE,WAAW,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EACF,mBAAmB,GACnB,eAAe,GACf,oBAAoB,GACpB,gBAAgB,GAChB,kBAAkB,GAClB,8BAA8B,GAC9B,8BAA8B,CAAC;CACpC,GACD;IACE,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,YAAY,CAAC;IAC7B,SAAS,EAAE,OAAO,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,wBAAwB,CAAC;IAChC,MAAM,CAAC,EAAE,wBAAwB,CAAC;IAClC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAqFN;;;;;GAKG;AACH,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,6BAA6B,GACrC,OAAO,CAAC,sBAAsB,CAAC,CA2IjC"}