@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.
- package/CHANGELOG.md +12 -0
- package/README.md +1 -1
- package/dist/client/billing/capturedCheckoutPayment.d.ts +31 -0
- package/dist/client/billing/capturedCheckoutPayment.d.ts.map +1 -0
- package/dist/client/billing/capturedCheckoutPayment.js +91 -0
- package/dist/client/billing/capturedCheckoutPayment.js.map +1 -0
- package/dist/client/connect/payoutAdoptionTestHelpers.d.ts +32 -32
- package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts +32 -32
- package/dist/client/core/accountCloseOptions.d.ts +21 -0
- package/dist/client/core/accountCloseOptions.d.ts.map +1 -0
- package/dist/client/core/accountCloseOptions.js +15 -0
- package/dist/client/core/accountCloseOptions.js.map +1 -0
- package/dist/client/core/accountCloseScope.d.ts +9 -0
- package/dist/client/core/accountCloseScope.d.ts.map +1 -0
- package/dist/client/core/accountCloseScope.js +49 -0
- package/dist/client/core/accountCloseScope.js.map +1 -0
- package/dist/client/core/accountClosurePreview.d.ts +40 -0
- package/dist/client/core/accountClosurePreview.d.ts.map +1 -0
- package/dist/client/core/accountClosurePreview.js +98 -0
- package/dist/client/core/accountClosurePreview.js.map +1 -0
- package/dist/client/core/accounts.d.ts +3 -6
- package/dist/client/core/accounts.d.ts.map +1 -1
- package/dist/client/core/accounts.js +21 -5
- package/dist/client/core/accounts.js.map +1 -1
- package/dist/client/index.d.ts +10 -6
- package/dist/client/index.d.ts.map +1 -1
- package/dist/client/index.js +8 -0
- package/dist/client/index.js.map +1 -1
- package/dist/client/publicTypes.d.ts +2 -0
- package/dist/client/publicTypes.d.ts.map +1 -1
- package/dist/component/_generated/api.d.ts +2 -0
- package/dist/component/_generated/api.d.ts.map +1 -1
- package/dist/component/_generated/api.js.map +1 -1
- package/dist/component/_generated/component.d.ts +14 -0
- package/dist/component/_generated/component.d.ts.map +1 -1
- package/dist/component/accountClosure/blockers.d.ts +6 -0
- package/dist/component/accountClosure/blockers.d.ts.map +1 -0
- package/dist/component/accountClosure/blockers.js +43 -0
- package/dist/component/accountClosure/blockers.js.map +1 -0
- package/dist/component/accountClosure/mutations.d.ts.map +1 -1
- package/dist/component/accountClosure/mutations.js +6 -31
- package/dist/component/accountClosure/mutations.js.map +1 -1
- package/dist/component/accountClosure/queries.d.ts +48 -0
- package/dist/component/accountClosure/queries.d.ts.map +1 -1
- package/dist/component/accountClosure/queries.js +32 -0
- package/dist/component/accountClosure/queries.js.map +1 -1
- package/dist/component/balanceFunding/mutations.d.ts +43 -43
- package/dist/component/balanceFunding/preparationHandlers.d.ts +8 -8
- package/dist/component/payoutRelease/queries.d.ts +2 -2
- package/dist/component/payoutRelease/queries.d.ts.map +1 -1
- package/dist/component/processingCostReconciliation/rollback.d.ts +1 -1
- package/dist/component/usage/allowance.fixtures.d.ts +16 -16
- package/docs/README.md +1 -0
- package/docs/captured-checkout-payment.md +136 -0
- package/docs/client-api.md +41 -0
- package/docs/react-workflows.md +37 -3
- package/package.json +1 -1
- package/src/client/billing/captured-checkout-payment.test.ts +272 -0
- package/src/client/billing/capturedCheckoutPayment.ts +120 -0
- package/src/client/core/account-close-guard.test.ts +349 -0
- package/src/client/core/account-closure-preview.test.ts +219 -0
- package/src/client/core/accountCloseOptions.ts +23 -0
- package/src/client/core/accountCloseScope.ts +87 -0
- package/src/client/core/accountClosurePreview.ts +149 -0
- package/src/client/core/accounts.ts +33 -7
- package/src/client/index.ts +19 -2
- package/src/client/publicTypes.ts +6 -0
- package/src/component/_generated/api.ts +2 -0
- package/src/component/_generated/component.ts +16 -0
- package/src/component/accountClosure/blockers.test.ts +114 -0
- package/src/component/accountClosure/blockers.ts +60 -0
- package/src/component/accountClosure/mutations.ts +6 -39
- 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.
|
package/docs/client-api.md
CHANGED
|
@@ -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 |
|
package/docs/react-workflows.md
CHANGED
|
@@ -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
|
-
|
|
174
|
-
|
|
175
|
-
|
|
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
|
@@ -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
|
+
}
|