@fantastic.dev/better-stripe 0.74.0 → 0.76.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (73) hide show
  1. package/CHANGELOG.md +12 -0
  2. package/README.md +1 -1
  3. package/dist/client/billing/capturedCheckoutPayment.d.ts +31 -0
  4. package/dist/client/billing/capturedCheckoutPayment.d.ts.map +1 -0
  5. package/dist/client/billing/capturedCheckoutPayment.js +91 -0
  6. package/dist/client/billing/capturedCheckoutPayment.js.map +1 -0
  7. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts +32 -32
  8. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts +32 -32
  9. package/dist/client/core/accountCloseOptions.d.ts +21 -0
  10. package/dist/client/core/accountCloseOptions.d.ts.map +1 -0
  11. package/dist/client/core/accountCloseOptions.js +15 -0
  12. package/dist/client/core/accountCloseOptions.js.map +1 -0
  13. package/dist/client/core/accountCloseScope.d.ts +9 -0
  14. package/dist/client/core/accountCloseScope.d.ts.map +1 -0
  15. package/dist/client/core/accountCloseScope.js +49 -0
  16. package/dist/client/core/accountCloseScope.js.map +1 -0
  17. package/dist/client/core/accountClosurePreview.d.ts +40 -0
  18. package/dist/client/core/accountClosurePreview.d.ts.map +1 -0
  19. package/dist/client/core/accountClosurePreview.js +98 -0
  20. package/dist/client/core/accountClosurePreview.js.map +1 -0
  21. package/dist/client/core/accounts.d.ts +3 -6
  22. package/dist/client/core/accounts.d.ts.map +1 -1
  23. package/dist/client/core/accounts.js +21 -5
  24. package/dist/client/core/accounts.js.map +1 -1
  25. package/dist/client/index.d.ts +10 -6
  26. package/dist/client/index.d.ts.map +1 -1
  27. package/dist/client/index.js +8 -0
  28. package/dist/client/index.js.map +1 -1
  29. package/dist/client/publicTypes.d.ts +2 -0
  30. package/dist/client/publicTypes.d.ts.map +1 -1
  31. package/dist/component/_generated/api.d.ts +2 -0
  32. package/dist/component/_generated/api.d.ts.map +1 -1
  33. package/dist/component/_generated/api.js.map +1 -1
  34. package/dist/component/_generated/component.d.ts +14 -0
  35. package/dist/component/_generated/component.d.ts.map +1 -1
  36. package/dist/component/accountClosure/blockers.d.ts +6 -0
  37. package/dist/component/accountClosure/blockers.d.ts.map +1 -0
  38. package/dist/component/accountClosure/blockers.js +43 -0
  39. package/dist/component/accountClosure/blockers.js.map +1 -0
  40. package/dist/component/accountClosure/mutations.d.ts.map +1 -1
  41. package/dist/component/accountClosure/mutations.js +6 -31
  42. package/dist/component/accountClosure/mutations.js.map +1 -1
  43. package/dist/component/accountClosure/queries.d.ts +48 -0
  44. package/dist/component/accountClosure/queries.d.ts.map +1 -1
  45. package/dist/component/accountClosure/queries.js +32 -0
  46. package/dist/component/accountClosure/queries.js.map +1 -1
  47. package/dist/component/balanceFunding/mutations.d.ts +43 -43
  48. package/dist/component/balanceFunding/preparationHandlers.d.ts +8 -8
  49. package/dist/component/payoutRelease/queries.d.ts +2 -2
  50. package/dist/component/payoutRelease/queries.d.ts.map +1 -1
  51. package/dist/component/processingCostReconciliation/rollback.d.ts +1 -1
  52. package/dist/component/usage/allowance.fixtures.d.ts +16 -16
  53. package/docs/README.md +1 -0
  54. package/docs/captured-checkout-payment.md +136 -0
  55. package/docs/client-api.md +41 -0
  56. package/docs/react-workflows.md +37 -3
  57. package/package.json +1 -1
  58. package/src/client/billing/captured-checkout-payment.test.ts +272 -0
  59. package/src/client/billing/capturedCheckoutPayment.ts +120 -0
  60. package/src/client/core/account-close-guard.test.ts +349 -0
  61. package/src/client/core/account-closure-preview.test.ts +219 -0
  62. package/src/client/core/accountCloseOptions.ts +23 -0
  63. package/src/client/core/accountCloseScope.ts +87 -0
  64. package/src/client/core/accountClosurePreview.ts +149 -0
  65. package/src/client/core/accounts.ts +33 -7
  66. package/src/client/index.ts +19 -2
  67. package/src/client/publicTypes.ts +6 -0
  68. package/src/component/_generated/api.ts +2 -0
  69. package/src/component/_generated/component.ts +16 -0
  70. package/src/component/accountClosure/blockers.test.ts +114 -0
  71. package/src/component/accountClosure/blockers.ts +60 -0
  72. package/src/component/accountClosure/mutations.ts +6 -39
  73. package/src/component/accountClosure/queries.ts +41 -1
@@ -0,0 +1,136 @@
1
+ # Captured Checkout payment observations
2
+
3
+ `qualifyCapturedCheckoutPayment` is a server-side, read-only qualifier for an
4
+ already retrieved, expanded payment-mode Checkout Session. It makes no provider
5
+ request and performs no component or database write.
6
+
7
+ Retrieve the original Session with its PaymentIntent and latest charge expanded:
8
+
9
+ ```ts
10
+ import { qualifyCapturedCheckoutPayment } from "@fantastic.dev/better-stripe";
11
+
12
+ // Authenticate the caller and resolve these values from the host's original
13
+ // purchase binding before retrieving provider data. Browser selectors and
14
+ // provider metadata do not authorize this read.
15
+ const session = await stripe.getCheckoutSessionFromStripe(ctx, {
16
+ stripeSessionId: original.stripeSessionId,
17
+ expand: ["payment_intent.latest_charge"],
18
+ });
19
+
20
+ const observation = qualifyCapturedCheckoutPayment(session, {
21
+ stripeSessionId: original.stripeSessionId,
22
+ customerAccountId: original.customerAccountId,
23
+ livemode: original.livemode,
24
+ });
25
+
26
+ if (observation.status === "unavailable") {
27
+ // Keep purchase/access verification pending or unavailable. Do not infer a
28
+ // payment from the browser return URL or manufacture a webhook event.
29
+ return { status: "unavailable", reason: observation.reason };
30
+ }
31
+
32
+ // Correlate these generic provider facts with the authorized original request.
33
+ return observation;
34
+ ```
35
+
36
+ The qualifier requires a completed, paid, payment-mode Session, an expanded
37
+ succeeded PaymentIntent and its expanded paid, succeeded, fully captured charge.
38
+ Session, PaymentIntent and charge identities, buyer account, livemode, positive
39
+ safe-integer amounts and currency must agree. Missing or unexpanded objects,
40
+ partial capture and contradictory evidence cannot return `ready`.
41
+
42
+ The result is a discriminated union:
43
+
44
+ - `status: "ready"` includes `stripeSessionId`, `stripePaymentIntentId`,
45
+ `stripeChargeId`, `customerAccountId`, `livemode`, `amount`, `currency`,
46
+ `sessionMetadata` and `paymentIntentMetadata`.
47
+ - `status: "unavailable"` includes a reason of `invalid_context`,
48
+ `invalid_evidence` or `identity_mismatch`.
49
+
50
+ `amount` remains an integer in Stripe's original-currency **minor units**. It is
51
+ not a decimal amount in major units: do not divide every currency by 100 or round
52
+ the provider value. Keep the currency with the amount and use the public currency
53
+ formatting helpers for display. Session and PaymentIntent metadata remain
54
+ separate string records for host correlation; they are not authentication.
55
+
56
+ ## Historical capture is separate from authority
57
+
58
+ `ready` describes coherent evidence that the original payment was fully captured.
59
+ It does not require an invoice, processing fee or balance transaction. Delayed
60
+ fees do not make that captured payment unavailable, and a later refund does not
61
+ erase its historical capture. Current refund eligibility, dispute exposure,
62
+ settlement, payable balance and payout authority require their own APIs and
63
+ current policy checks.
64
+
65
+ This observation is not a reservation, verified webhook signature, durable
66
+ fulfillment receipt or access grant. The host still authenticates the actor,
67
+ binds the immutable request and original buyer/account, checks application
68
+ eligibility and decides whether to accept signed-original evidence and fulfill
69
+ the purchase. A signed webhook adapter may reuse this same qualifier after its
70
+ real signature verification and original correlation. Calling the qualifier does
71
+ not create a signed event or replace that adapter's transaction and replay rules.
72
+
73
+ ## Reuse from a real signed adapter
74
+
75
+ The current Vite example does **not** implement an authenticated captured-receipt
76
+ adapter or a durable signed-original Checkout fulfillment consumer. The following
77
+ is a host integration sketch, not an implemented example handler or an additional
78
+ package API:
79
+
80
+ ```ts
81
+ import {
82
+ qualifyCapturedCheckoutPayment,
83
+ registerRoutes,
84
+ } from "@fantastic.dev/better-stripe";
85
+
86
+ registerRoutes(http, components.betterStripe, {
87
+ stripeSecretKey,
88
+ webhookSecret,
89
+ onEvent: async (ctx, event) => {
90
+ // registerRoutes has verified the real webhook signature before this hook.
91
+ if (!("data" in event) || event.type !== "checkout.session.completed")
92
+ return;
93
+
94
+ // These two functions are host-owned: resolve the immutable original, then
95
+ // apply its transactional acceptance/replay policy. They are not SDK APIs.
96
+ const original = await readOriginalForVerifiedEvent(ctx, {
97
+ eventId: event.id,
98
+ stripeSessionId: event.data.object.id,
99
+ });
100
+ const session = await stripe.getCheckoutSessionFromStripe(ctx, {
101
+ stripeSessionId: original.stripeSessionId,
102
+ expand: ["payment_intent.latest_charge"],
103
+ });
104
+ const observation = qualifyCapturedCheckoutPayment(session, {
105
+ stripeSessionId: original.stripeSessionId,
106
+ customerAccountId: original.customerAccountId,
107
+ livemode: original.livemode,
108
+ });
109
+ if (observation.status !== "ready") return;
110
+ await acceptOriginalPayment(ctx, {
111
+ eventId: event.id,
112
+ original,
113
+ observation,
114
+ });
115
+ },
116
+ });
117
+ ```
118
+
119
+ The host must retain the actual verified event identity, reconcile it with the
120
+ original purchase, and make acceptance and entitlement writes under its existing
121
+ atomic/replay rules. The fetched Session remains a read-time provider
122
+ observation; the qualifier does not assert that it was the signed event payload.
123
+ Do not construct a `Stripe.Event` from a receipt read or invoke webhook-only
124
+ processing merely to qualify a captured payment. Existing applications can share
125
+ the qualifier between their authorized reader and their genuine signed adapter
126
+ without duplicating the generic capture validator.
127
+
128
+ ## Receipt presentation
129
+
130
+ For receipt presentation, keep the public React `PaymentReceipt` workflow and
131
+ host render props. Supply an authoritative server payment projection only after
132
+ the host's receipt policy accepts it. A successful browser `confirm()` means
133
+ confirmation was submitted; it does not establish paid status or access. The
134
+ host retains authorization, receipt refresh, entitlement decisions, localization
135
+ and styling. See [React workflows](react-workflows.md) and
136
+ [refund context](refund-context.md) for their separate contracts.
@@ -37,6 +37,47 @@ retain original financial references. The Vite reference's
37
37
  [closed-account authorization example](https://github.com/FantasticDevHQ/better-stripe/blob/main/example/README.md#closed-account-history)
38
38
  shows where the host's authenticated-actor check belongs.
39
39
 
40
+ #### Closure observations and confirmed scope
41
+
42
+ `previewAccountClosure(ctx, { stripeAccountId, sessionLimit? })` is a bounded,
43
+ read-only action for an exact host-authorized account. It freshly reads provider
44
+ account configurations and closed state, the existing account balance reader,
45
+ one `status: "open"` Checkout page (default 25, maximum 100), and the indexed
46
+ component usage blockers shared with closure. It creates no closure intent and
47
+ makes no provider write. Do not pass an arbitrary browser account ID as authority.
48
+
49
+ Each observation is `{ status: "observed", value }` or `{ status: "unknown" }`.
50
+ Balances retain every returned currency's separate available and pending amounts.
51
+ Any nonzero amount, including negative amounts, produces `nonzero_balance`;
52
+ currencies and available/pending amounts are not netted. Open sessions produce
53
+ `open_checkout_sessions`. Usage corrections, open prepaid credits and managed
54
+ usage enrollment retain their component blocker names. A truncated session page
55
+ adds `open_sessions_truncated`; unavailable or malformed sources remain unknown.
56
+ The result always has `financialCoverage: "unknown"` and
57
+ `financial_coverage_unknown`. Zero balances and an empty complete page establish
58
+ only those observations, never settlement of all liabilities. There is no
59
+ `eligible` flag or host-provided completeness override.
60
+
61
+ After independent host authorization, financial clearance and explicit whole-account
62
+ confirmation, pass `expectedAppliedConfigurations` to `closeAccount` (or its alias).
63
+ The guarded path requires exact original stored scope/ownership and a fresh exact-ID
64
+ provider observation before an active-account close POST. Changed, missing,
65
+ duplicate or unsupported scope fails without a POST. It never rewrites the saved
66
+ original role set on retry. A legacy original with unknown scope stays held.
67
+ An observed same-account terminal `closed: true` can reconcile retained original
68
+ ownership/history without another POST, including after a lost response or a
69
+ pre-dispatch crash. This proves observed account state, not that our request caused
70
+ closure. A close acknowledgement must match the original ID and closed state.
71
+
72
+ This is a point-in-time scope guard. Provider changes between read and close are
73
+ not atomically fenced; financial writers and outstanding obligations require
74
+ separate host/component contracts. Omitting the option preserves the existing
75
+ unguarded behavior, including first-call cached configurations. Integrations
76
+ adopting this guard must pass it explicitly. The public
77
+ `closeAccountOptionsSchema` and `accountClosurePreviewOptionsSchema` validate
78
+ these SDK inputs; `CloseAccountOptions` and `AccountClosurePreview` expose the
79
+ matching types. Restarting onboarding remains closure, never reopening an account.
80
+
40
81
  | Method | Description |
41
82
  | --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
42
83
  | `createAccount(ctx, { userId, email?, name?, country?, orgId?, metadata? })` | Create a V2 account in Stripe and the component database |
@@ -8,6 +8,37 @@ Components render semantic HTML without package CSS. Use their render props or
8
8
  companion hooks to supply your own design system. Stripe iframe contents use
9
9
  Stripe's `appearance` options and retain Stripe's own styling.
10
10
 
11
+ ## Whole-account closure confirmation
12
+
13
+ `AccountCloseCard` supplies a headless confirmation surface. Use its render prop
14
+ with your own styles and translated text, as in the Vite seller onboarding page.
15
+ Obtain `previewAccountClosure` through an authenticated host action for the exact
16
+ original account. Display the observed customer/merchant/recipient configurations,
17
+ known blockers and unknown sources. Re-read on account or session changes; do not
18
+ reuse another account's preview or infer eligibility from an exhausted page.
19
+
20
+ Keep the destructive control disabled until your server independently authorizes
21
+ the actor, original account and financial clearance, and the person explicitly
22
+ confirms the displayed whole-account scope. A preview's financial coverage remains
23
+ unknown even when all its known blockers are absent. The host close action must
24
+ recheck that authority and pass the confirmed original configuration set:
25
+
26
+ ```ts
27
+ await stripe.closeAccount(ctx, {
28
+ stripeAccountId: originalAccountId,
29
+ expectedAppliedConfigurations: confirmedConfigurations,
30
+ });
31
+ ```
32
+
33
+ Supply `titleLabel`, `descriptionLabel` and `closeLabel` to describe irreversible
34
+ whole-account closure rather than a recipient-only stop-withdrawals action.
35
+ The existing `restartAccountOnboarding` alias also closes; it cannot reopen the
36
+ account or authorize creating a replacement. A scope drift or unknown response
37
+ must retain the same account and original request for recovery. Freshly observing
38
+ that original account closed can reconcile history without another POST; it
39
+ does not attribute closure to our request. See the
40
+ [server contract](./client-api.md#closure-observations-and-confirmed-scope).
41
+
11
42
  ## Charge and Price currency units
12
43
 
13
44
  `getChargeCurrencyMetadata`, `chargeAmountToDecimal`, `parseChargeAmount` and `formatChargeAmount` are
@@ -170,9 +201,12 @@ keep it editable if a payment attempt fails.
170
201
  The lower-level `CheckoutElementsForm`, `PaymentIntentForm`, and `CheckoutForm`
171
202
  are also exported for an existing client secret.
172
203
 
173
- Only a server-confirmed payment or checkout session should grant access to the
174
- product. Use `PaymentReceipt` or `CheckoutStatus` with webhook-backed query data;
175
- a browser return URL alone does not prove payment.
204
+ Use `PaymentReceipt` or `CheckoutStatus` with authoritative server-backed data.
205
+ A completed Checkout Session or a
206
+ [captured payment observation](captured-checkout-payment.md) does not itself
207
+ grant access. The host still authenticates the buyer, correlates the original
208
+ purchase and applies its fulfillment and entitlement policy. A browser return
209
+ URL or successful confirmation submission alone does not prove payment.
176
210
 
177
211
  ## Via API, BetterStripe components, or Stripe embedded
178
212
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fantastic.dev/better-stripe",
3
- "version": "0.74.0",
3
+ "version": "0.76.0",
4
4
  "description": "Convex component for Stripe Accounts v2, subscriptions, metered billing and Connect marketplaces, with React workflows.",
5
5
  "keywords": [
6
6
  "stripe",
@@ -0,0 +1,272 @@
1
+ import { expect, it } from "vitest";
2
+
3
+ import * as sdk from "../index.js";
4
+
5
+ it("exports a pure captured Checkout payment qualifier from the public SDK", () => {
6
+ expect(sdk).toHaveProperty(
7
+ "qualifyCapturedCheckoutPayment",
8
+ expect.any(Function),
9
+ );
10
+ });
11
+
12
+ const expected = {
13
+ stripeSessionId: "cs_original",
14
+ customerAccountId: "acct_buyer",
15
+ livemode: false,
16
+ };
17
+
18
+ function session() {
19
+ return {
20
+ id: "cs_original",
21
+ object: "checkout.session",
22
+ mode: "payment",
23
+ subscription: null,
24
+ status: "complete",
25
+ payment_status: "paid",
26
+ customer_account: "acct_buyer",
27
+ livemode: false,
28
+ amount_total: 3500,
29
+ currency: "usd",
30
+ metadata: { originalRequest: "host-request" },
31
+ payment_intent: {
32
+ id: "pi_original",
33
+ object: "payment_intent",
34
+ status: "succeeded",
35
+ customer_account: "acct_buyer",
36
+ livemode: false,
37
+ amount: 3500,
38
+ amount_received: 3500,
39
+ currency: "usd",
40
+ metadata: { originalPayment: "host-payment" },
41
+ latest_charge: {
42
+ id: "ch_original",
43
+ object: "charge",
44
+ payment_intent: "pi_original",
45
+ livemode: false,
46
+ status: "succeeded",
47
+ paid: true,
48
+ captured: true,
49
+ amount: 3500,
50
+ amount_captured: 3500,
51
+ currency: "usd",
52
+ },
53
+ },
54
+ };
55
+ }
56
+
57
+ function change(input: object, path: string, value: unknown) {
58
+ const keys = path.split(".");
59
+ let current = input as Record<string, unknown>;
60
+ for (const key of keys.slice(0, -1))
61
+ current = current[key] as Record<string, unknown>;
62
+ current[keys[keys.length - 1]!] = value;
63
+ }
64
+
65
+ it("qualifies the retrieved original without invoice, fees or balance data", () => {
66
+ const input = session();
67
+ const before = structuredClone(input);
68
+ expect(sdk.qualifyCapturedCheckoutPayment(input, expected)).toEqual({
69
+ status: "ready",
70
+ stripeSessionId: "cs_original",
71
+ stripePaymentIntentId: "pi_original",
72
+ stripeChargeId: "ch_original",
73
+ customerAccountId: "acct_buyer",
74
+ livemode: false,
75
+ amount: 3500,
76
+ currency: "usd",
77
+ sessionMetadata: { originalRequest: "host-request" },
78
+ paymentIntentMetadata: { originalPayment: "host-payment" },
79
+ });
80
+ expect(input).toEqual(before);
81
+ });
82
+
83
+ it.each([
84
+ ["id", "cs_foreign"],
85
+ ["object", "payment_intent"],
86
+ ["mode", "subscription"],
87
+ ["subscription", "sub_contradiction"],
88
+ ["status", "open"],
89
+ ["status", "expired"],
90
+ ["status", null],
91
+ ["payment_status", "unpaid"],
92
+ ["payment_status", "no_payment_required"],
93
+ ["payment_intent", "pi_original"],
94
+ ["payment_intent", null],
95
+ ["payment_intent.id", "bad"],
96
+ ["payment_intent.object", "charge"],
97
+ ["payment_intent.status", "processing"],
98
+ ["payment_intent.status", "requires_capture"],
99
+ ["payment_intent.status", "canceled"],
100
+ ["payment_intent.latest_charge", "ch_original"],
101
+ ["payment_intent.latest_charge", null],
102
+ ["payment_intent.latest_charge.id", "bad"],
103
+ ["payment_intent.latest_charge.object", "payment_intent"],
104
+ ["payment_intent.latest_charge.payment_intent", "pi_foreign"],
105
+ ["payment_intent.latest_charge.status", "failed"],
106
+ ["payment_intent.latest_charge.paid", false],
107
+ ["payment_intent.latest_charge.captured", false],
108
+ ["customer_account", "acct_foreign"],
109
+ ["customer_account", undefined],
110
+ ["payment_intent.customer_account", "acct_foreign"],
111
+ ["payment_intent.customer_account", undefined],
112
+ ["livemode", true],
113
+ ["payment_intent.livemode", true],
114
+ ["payment_intent.latest_charge.livemode", true],
115
+ ["currency", "USD"],
116
+ ["currency", ""],
117
+ ["payment_intent.currency", "eur"],
118
+ ["payment_intent.latest_charge.currency", "eur"],
119
+ ["metadata", { invalid: 1 }],
120
+ ["payment_intent.metadata", { invalid: null }],
121
+ ["amount_total", 3499],
122
+ ["payment_intent.amount", 3499],
123
+ ["payment_intent.amount_received", 3499],
124
+ ["payment_intent.latest_charge.amount", 3499],
125
+ ["payment_intent.latest_charge.amount_captured", 3499],
126
+ ] as const)("withholds inconsistent or incomplete %s = %j", (path, value) => {
127
+ const input = session();
128
+ change(input, path, value);
129
+ expect(sdk.qualifyCapturedCheckoutPayment(input, expected).status).toBe(
130
+ "unavailable",
131
+ );
132
+ });
133
+
134
+ it.each([null, undefined, {}, "session", []])(
135
+ "rejects malformed input %j",
136
+ (input) => {
137
+ expect(sdk.qualifyCapturedCheckoutPayment(input, expected)).toEqual({
138
+ status: "unavailable",
139
+ reason: "invalid_evidence",
140
+ });
141
+ },
142
+ );
143
+
144
+ it.each(["stripeSessionId", "customerAccountId", "livemode"] as const)(
145
+ "rejects malformed expected %s at runtime",
146
+ (key) => {
147
+ const input = { ...expected, [key]: null };
148
+ expect(
149
+ sdk.qualifyCapturedCheckoutPayment(session(), input as never),
150
+ ).toEqual({
151
+ status: "unavailable",
152
+ reason: "invalid_context",
153
+ });
154
+ },
155
+ );
156
+
157
+ it.each(["", "bad", "cs_"])(
158
+ "rejects malformed Session selector %j",
159
+ (stripeSessionId) => {
160
+ expect(
161
+ sdk.qualifyCapturedCheckoutPayment(session(), {
162
+ ...expected,
163
+ stripeSessionId,
164
+ }),
165
+ ).toEqual({
166
+ status: "unavailable",
167
+ reason: "invalid_context",
168
+ });
169
+ },
170
+ );
171
+ it.each(["", "cus_buyer", "acct_"])(
172
+ "rejects malformed V2 account selector %j",
173
+ (customerAccountId) => {
174
+ expect(
175
+ sdk.qualifyCapturedCheckoutPayment(session(), {
176
+ ...expected,
177
+ customerAccountId,
178
+ }),
179
+ ).toEqual({
180
+ status: "unavailable",
181
+ reason: "invalid_context",
182
+ });
183
+ },
184
+ );
185
+
186
+ it("does not substitute customer-v1 presentation for V2 account authority", () => {
187
+ const input = session();
188
+ Object.assign(input, { customer: "cus_buyer", customer_account: undefined });
189
+ Object.assign(input.payment_intent, {
190
+ customer: "cus_buyer",
191
+ customer_account: undefined,
192
+ });
193
+ expect(sdk.qualifyCapturedCheckoutPayment(input, expected).status).toBe(
194
+ "unavailable",
195
+ );
196
+ });
197
+
198
+ it("rejects coherent live evidence against expected test scope", () => {
199
+ const input = session();
200
+ input.livemode =
201
+ input.payment_intent.livemode =
202
+ input.payment_intent.latest_charge.livemode =
203
+ true;
204
+ expect(sdk.qualifyCapturedCheckoutPayment(input, expected)).toEqual({
205
+ status: "unavailable",
206
+ reason: "identity_mismatch",
207
+ });
208
+ expect(
209
+ sdk.qualifyCapturedCheckoutPayment(input, { ...expected, livemode: true })
210
+ .status,
211
+ ).toBe("ready");
212
+ });
213
+
214
+ it.each([0, -1, 0.5, Number.MAX_SAFE_INTEGER + 1, NaN, Infinity, "3500"])(
215
+ "rejects coherently invalid gross amount %j",
216
+ (amount) => {
217
+ const input = session();
218
+ for (const path of [
219
+ "amount_total",
220
+ "payment_intent.amount",
221
+ "payment_intent.amount_received",
222
+ "payment_intent.latest_charge.amount",
223
+ "payment_intent.latest_charge.amount_captured",
224
+ ])
225
+ change(input, path, amount);
226
+ expect(sdk.qualifyCapturedCheckoutPayment(input, expected).status).toBe(
227
+ "unavailable",
228
+ );
229
+ },
230
+ );
231
+
232
+ it.each([
233
+ ["jpy", 3500],
234
+ ["kwd", 3501],
235
+ ["usd", Number.MAX_SAFE_INTEGER],
236
+ ] as const)(
237
+ "preserves integer original provider units for %s",
238
+ (currency, amount) => {
239
+ const input = session();
240
+ input.currency =
241
+ input.payment_intent.currency =
242
+ input.payment_intent.latest_charge.currency =
243
+ currency;
244
+ input.amount_total =
245
+ input.payment_intent.amount =
246
+ input.payment_intent.amount_received =
247
+ input.payment_intent.latest_charge.amount =
248
+ input.payment_intent.latest_charge.amount_captured =
249
+ amount;
250
+ expect(sdk.qualifyCapturedCheckoutPayment(input, expected)).toMatchObject({
251
+ status: "ready",
252
+ amount,
253
+ currency,
254
+ });
255
+ },
256
+ );
257
+
258
+ it("keeps captured history after refunds/disputes without asserting eligibility", () => {
259
+ const input = session();
260
+ Object.assign(input.payment_intent.latest_charge, {
261
+ refunded: true,
262
+ amount_refunded: 3500,
263
+ disputed: true,
264
+ balance_transaction: null,
265
+ application_fee: null,
266
+ invoice: null,
267
+ });
268
+ const result = sdk.qualifyCapturedCheckoutPayment(input, expected);
269
+ expect(result).toMatchObject({ status: "ready", amount: 3500 });
270
+ expect(result).not.toHaveProperty("refundable");
271
+ expect(result).not.toHaveProperty("payable");
272
+ });
@@ -0,0 +1,120 @@
1
+ import { z } from "zod";
2
+
3
+ const id = (prefix: string) =>
4
+ z
5
+ .string()
6
+ .max(255)
7
+ .regex(new RegExp(`^${prefix}_[A-Za-z0-9_]+$`));
8
+ const amount = z.number().int().positive().max(Number.MAX_SAFE_INTEGER);
9
+ const currency = z.string().regex(/^[a-z]{3}$/);
10
+ const metadata = z.record(z.string(), z.string());
11
+ const expectedSchema = z.object({
12
+ stripeSessionId: id("cs"),
13
+ customerAccountId: id("acct"),
14
+ livemode: z.boolean(),
15
+ });
16
+ const evidenceSchema = z.object({
17
+ id: id("cs"),
18
+ object: z.literal("checkout.session"),
19
+ mode: z.literal("payment"),
20
+ subscription: z.null(),
21
+ status: z.literal("complete"),
22
+ payment_status: z.literal("paid"),
23
+ customer_account: id("acct"),
24
+ livemode: z.boolean(),
25
+ amount_total: amount,
26
+ currency,
27
+ metadata,
28
+ payment_intent: z.object({
29
+ id: id("pi"),
30
+ object: z.literal("payment_intent"),
31
+ status: z.literal("succeeded"),
32
+ customer_account: id("acct"),
33
+ livemode: z.boolean(),
34
+ amount,
35
+ amount_received: amount,
36
+ currency,
37
+ metadata,
38
+ latest_charge: z.object({
39
+ id: id("ch"),
40
+ object: z.literal("charge"),
41
+ payment_intent: id("pi"),
42
+ status: z.literal("succeeded"),
43
+ paid: z.literal(true),
44
+ captured: z.literal(true),
45
+ livemode: z.boolean(),
46
+ amount,
47
+ amount_captured: amount,
48
+ currency,
49
+ }),
50
+ }),
51
+ });
52
+
53
+ /** Server-owned original selectors, not browser authorization or signed-event proof. */
54
+ export type CapturedCheckoutPaymentExpected = z.infer<typeof expectedSchema>;
55
+
56
+ export type CapturedCheckoutPaymentObservation =
57
+ | {
58
+ status: "ready";
59
+ stripeSessionId: string;
60
+ stripePaymentIntentId: string;
61
+ stripeChargeId: string;
62
+ customerAccountId: string;
63
+ livemode: boolean;
64
+ /** Integer original provider minor units, never converted to major-unit decimals. */
65
+ amount: number;
66
+ currency: string;
67
+ sessionMetadata: Record<string, string>;
68
+ paymentIntentMetadata: Record<string, string>;
69
+ }
70
+ | {
71
+ status: "unavailable";
72
+ reason: "invalid_context" | "invalid_evidence" | "identity_mismatch";
73
+ };
74
+
75
+ /**
76
+ * Qualify an already retrieved Session with payment_intent.latest_charge expanded.
77
+ * No I/O or writes. Captured history is not fulfillment, refund or settlement authority.
78
+ */
79
+ export function qualifyCapturedCheckoutPayment(
80
+ session: unknown,
81
+ expected: CapturedCheckoutPaymentExpected,
82
+ ): CapturedCheckoutPaymentObservation {
83
+ const scope = expectedSchema.safeParse(expected);
84
+ if (!scope.success)
85
+ return { status: "unavailable", reason: "invalid_context" };
86
+ const parsed = evidenceSchema.safeParse(session);
87
+ if (!parsed.success)
88
+ return { status: "unavailable", reason: "invalid_evidence" };
89
+ const paid = parsed.data;
90
+ const pi = paid.payment_intent;
91
+ const charge = pi.latest_charge;
92
+ if (
93
+ paid.id !== scope.data.stripeSessionId ||
94
+ paid.customer_account !== scope.data.customerAccountId ||
95
+ pi.customer_account !== scope.data.customerAccountId ||
96
+ paid.livemode !== scope.data.livemode ||
97
+ pi.livemode !== scope.data.livemode ||
98
+ charge.livemode !== scope.data.livemode ||
99
+ charge.payment_intent !== pi.id ||
100
+ pi.amount !== paid.amount_total ||
101
+ pi.amount_received !== paid.amount_total ||
102
+ charge.amount !== paid.amount_total ||
103
+ charge.amount_captured !== paid.amount_total ||
104
+ pi.currency !== paid.currency ||
105
+ charge.currency !== paid.currency
106
+ )
107
+ return { status: "unavailable", reason: "identity_mismatch" };
108
+ return {
109
+ status: "ready",
110
+ stripeSessionId: paid.id,
111
+ stripePaymentIntentId: pi.id,
112
+ stripeChargeId: charge.id,
113
+ customerAccountId: paid.customer_account,
114
+ livemode: paid.livemode,
115
+ amount: paid.amount_total,
116
+ currency: paid.currency,
117
+ sessionMetadata: paid.metadata,
118
+ paymentIntentMetadata: pi.metadata,
119
+ };
120
+ }