@agent-cards/checkout 0.11.0 → 0.12.0

package/CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## Unreleased
 
+- Complete a merchant-confirmed payment when the merchant supplies no order or receipt ID. Return `{ status: 'completed', confirmation: { kind: 'merchant_payment', authorizationId } }` from the merchant resolver using the current checkout authorization. The resolver must verify the original payment request, amount, currency, selected card and merchant success; HTTP 200 or a success page alone is insufficient. The completed state carries `confirmation` without inventing `orderId`, clears stale reasons and continues to block another payment. Existing completion results with a genuine `orderId` keep working.
+
 - Approve a Recurly checkout before its native card request starts. Call `prepare` with `psp: 'recurly'` and `environment: 'shared'`, then submit the merchant's form once. The same selected card and approved purchase bind a new-card POST on the US or EU endpoint. The matching API, database migration and Vault release are required. Token issuance and merchant payment completion remain separate results.
 
 - Keep the selected card's issuer in guest Mercado Pago Checkout Pro in Mexico. The Vault resolves the card's eight-digit prefix against the merchant's captured checkout configuration over browser TLS. The SDK returns the original card-token response and corrects one native card association. Missing configuration, ambiguous issuers, changed checkout context, and a different card brand or type stop continuation. The matching API, Vault and encrypted relay release is required. Other Mercado Pago checkout families and merchant payment completion need separate validation.

package/README.md

@@ -367,17 +367,56 @@ const checkout = await attachToPlaywright(page, {
 
 // Your existing agent dispatches checkout. Later, once the paused request resumes:
 const state = await checkout.reconcile();
-if (state.status === 'completed' && state.orderId) await finishAgentTask(state.orderId);
+if (state.status === 'completed') await finishAgentTask(state);
 ```
 
-`resolveMerchantResult` must read an authoritative merchant order/receipt tied
-to this attempt. It returns one of:
+`resolveMerchantResult` must verify the merchant's result for the original
+payment attempt. It returns one of:
 
-- `{ status: 'completed', orderId }`: merchant-confirmed success.
+- `{ status: 'completed', orderId }`: merchant-confirmed success with a genuine order or receipt ID. Existing integrations keep this form.
+- `{ status: 'completed', confirmation: { kind: 'merchant_payment', authorizationId } }`: merchant-confirmed payment when no order or receipt ID is available. The ID must match the current checkout authorization.
 - `{ status: 'failed' }`: merchant confirmed the attempt failed; no successful payment/order exists.
 - `{ status: 'pending' }` or `{ status: 'unknown' }`: keep waiting or reconcile; never click Pay again.
 - `{ status: 'requires_user_action', reason: '3ds' | 'redirect' | 'other' }`: deliver your own browser live view or supported challenge UI to the user.
 
+For a merchant that confirms payment without returning an order ID, your
+resolver can return the explicit payment confirmation:
+
+```ts
+const checkout = await attachToPlaywright(page, {
+  vault, user, merchant, amount, currency,
+  requireMerchantResult: true,
+  resolveMerchantResult: async state => {
+    const payment = await readOriginalMerchantPayment(state);
+    if (!payment.confirmed || !state.authorizationId) return { status: 'unknown' };
+    return {
+      status: 'completed',
+      confirmation: {
+        kind: 'merchant_payment',
+        authorizationId: state.authorizationId,
+      },
+    };
+  },
+});
+```
+
+`readOriginalMerchantPayment` is your merchant-specific check. The check must
+match the original payment request, amount, currency and selected card, and
+verify authoritative merchant success for that attempt. HTTP 200 alone, a card
+token, a success URL or text that anyone can open does not establish payment.
+Copying `state.authorizationId` without checking the payment is insufficient.
+The SDK checks the authorization binding; it does not independently authenticate
+the merchant evidence supplied by your resolver.
+
+Return one completion form at a time. The payment-confirmation form leaves
+`state.orderId` absent and exposes `state.confirmation` with the exported
+`MerchantPaymentConfirmation` type. Your consumer should finish on
+`state.status === 'completed'` and treat `orderId` as optional. A missing or
+mismatched authorization, or `{ status: 'completed' }` without either completion
+form, leaves the outcome unknown. Confirmed completion clears stale failure or
+authentication reasons and continues to block further payment submissions.
+Never invent an order ID from a token or authorization ID.
+
 The SDK does not infer order success from `authorized` or a tokenization reply,
 and does not claim to detect or solve arbitrary 3DS challenges. Your merchant
 resolver (or `checkout.requestUserAction('3ds')` when your browser observes it)
@@ -388,22 +427,29 @@ isolated from the payment handoff.
 Native Stripe Checkout emits `checkout_blocked` before the existing `blocked`
 event when its local preparation rejects a request. Its
 `StripeCheckoutBlockedDetail` contains only fixed codes: `version: 1`,
-`processor: 'stripe'`, endpoint family, phase, stage, reason, gate state, and
-disposition. It contains no URLs, identifiers, request fields, or exception text.
+`processor: 'stripe'`, endpoint family, phase, stage, reason, optional validation code, gate state, and
+disposition. It contains no URLs, identifiers, request-derived field names or values, or exception text.
 
 | Field | Values |
 | --- | --- |
 | `endpoint_family` | `payment_methods`, `payment_page_confirm`, `other` |
 | `phase` | `tokenization`, `final`, `unknown` |
 | `stage` | `request_read`, `classification`, `claim`, `readiness`, `document`, `stub_response` |
+| `validation_code` | Shared-core `StripeCheckoutValidationCode`; present only for `request_validation_failed` |
 | `gate_state` | `fresh`, `stubbed`, `submitted`, `stopped` |
 | `disposition` | `active_claim_preserved`, `checkout_stopped` |
 
 `reason` is the exported `StripeCheckoutBlockReason` union. It identifies SDK
 claim and readiness failures, such as `duplicate_confirmation`, `document_changed`,
-or `attachment_not_ready`. The shared core's rejection is
-`request_validation_failed` with phase `unknown`; this event does not infer which
-core predicate failed. `gate_state` records the state before the adapter handles
+or `attachment_not_ready`. A shared-core rejection reports
+`request_validation_failed` and a fixed `validation_code` identifying the failed
+check, or `unclassified` when no recognized code is available. Initial request
+classification uses phase `unknown`; a billing capture rejection uses
+`tokenization`, and a billing attachment rejection uses `final`.
+For example, `form_field_unknown` identifies an allowlist rejection without
+revealing the field name or value. Identifying that field requires a separate
+reviewed synthetic fixture; the code alone does not establish or fix a processor
+schema mismatch. `gate_state` records the state before the adapter handles
 the failure, though document validation may already have stopped the gate.
 
 `active_claim_preserved` means a valid duplicate was refused without invalidating
@@ -579,7 +625,7 @@ When the cardholder has enabled an eligible spending rule in their vault, the sa
 
 Use `executionMode: 'user_approval'` to require the existing confirmation flow. Without a selected card or grant, the backend can use exactly one eligible rule; ambiguous card selection keeps confirmation. A `grantId` restricts selection to that rule. The initial executor supports only the configured controlled Stripe test flow, and production remains disabled.
 
-For controlled hosted Stripe Checkout, both attachment functions accept `stripeCheckout: { sessionId, publishableKey, environment? }`. The default is TEST, requiring `cs_test_` and `pk_test_`. LIVE requires explicit `environment: 'production'`, a `cs_live_` Session and its `pk_live_` key. Both modes require `executionMode: 'autopilot'`, an explicit `grantId`, and a positive numeric USD `amount` in cents. The top-level document must be that Session on `checkout.stripe.com`. Direct `authorize()` calls use `stripeCheckoutEnvironment: 'production'` for the same explicit LIVE opt-in; the attachment functions pass it automatically.
+For controlled hosted Stripe Checkout, both attachment functions accept `stripeCheckout: { sessionId, publishableKey, environment? }`. The default is TEST, requiring `cs_test_` and `pk_test_`. LIVE requires explicit `environment: 'production'`, a `cs_live_` Session and its `pk_live_` key. Both modes require `executionMode: 'autopilot'`, an explicit `grantId`, and a positive numeric USD `amount` in cents. The top-level document must be that exact Session on `https://checkout.stripe.com`, at `/c/pay/{sessionId}`, `/pay/{sessionId}`, `/g/pay/{sessionId}`, or `/f/pay/{sessionId}`. The SDK validates the existing URL without rewriting or navigating it. Direct `authorize()` calls use `stripeCheckoutEnvironment: 'production'` for the same explicit LIVE opt-in; the attachment functions pass it automatically.
 
 The SDK answers dummy-card tokenization locally, then sends the browser's final native confirmation through the shared core and enclave. The local response is preparation only: it creates no authorization and makes no processor request. The final result includes `checkoutSessionId` only after the selected grant, restricted terminal response, and captured amount have been checked. Continue to confirm the merchant order through the checkout controller.
 

package/dist/index.d.ts

@@ -10,4 +10,4 @@ export { hostedFormSubmittedPage, HOSTED_FORM_SUBMITTED_OUTCOME } from './hosted
 export type { HostedFormSubmittedPageInput, SyntheticPage } from './hosted-form.js';
 export { BUILTIN_REGISTRY, cardUrlPatterns, findRecognizer } from './registry.js';
 export type { Recognizer, CheckoutMode } from './registry.js';
-export type { CheckoutController, CheckoutState, MerchantResult, UserAction, LifecycleOptions, PaymentEndpointGuard } from './lifecycle.js';
+export type { CheckoutController, CheckoutState, MerchantResult, MerchantPaymentConfirmation, UserAction, LifecycleOptions, PaymentEndpointGuard } from './lifecycle.js';

package/dist/lifecycle.d.ts

@@ -1,9 +1,19 @@
 import { CheckoutPreparationError, type PrepareCheckoutOptions, type PreparedCheckout, type ReplayResponse } from './client.js';
 import type { CheckoutMode } from './registry.js';
-/** A processor approval is not an order. Only the merchant can confirm this result. */
+/** The application's resolver confirmed the payment for this checkout authorization. */
+export interface MerchantPaymentConfirmation {
+    kind: 'merchant_payment';
+    authorizationId: string;
+}
+/** Only authoritative merchant evidence can confirm completion; a processor token is insufficient. */
 export type MerchantResult = {
     status: 'completed';
     orderId: string;
+    confirmation?: never;
+} | {
+    status: 'completed';
+    confirmation: MerchantPaymentConfirmation;
+    orderId?: never;
 } | {
     status: 'failed';
 } | {
@@ -18,6 +28,7 @@ export interface CheckoutState {
     preparationId?: string;
     mode?: CheckoutMode;
     orderId?: string;
+    confirmation?: MerchantPaymentConfirmation;
     /** Stable SDK category; never includes a request body, processor response, or approval link. */
     reason?: string;
 }
@@ -30,7 +41,7 @@ export interface UserAction {
 export interface LifecycleOptions {
     onStateChange?: (state: Readonly<CheckoutState>) => void;
     onUserAction?: (action: UserAction) => void | Promise<void>;
-    /** Read authoritative merchant order state; do not click Pay or initiate a new charge here. */
+    /** Read authoritative merchant payment or order state; do not click Pay or initiate a new charge here. */
     resolveMerchantResult?: (state: Readonly<CheckoutState>) => Promise<MerchantResult>;
     /** Hold further card requests after handoff until the merchant result is reconciled. Default false for compatibility. */
     requireMerchantResult?: boolean;

package/dist/lifecycle.js

@@ -17,7 +17,9 @@ export class CheckoutLifecycle {
     constructor(options) {
         this.options = options;
     }
-    getState() { return { ...this.state }; }
+    getState() {
+        return { ...this.state, ...(this.state.confirmation ? { confirmation: { ...this.state.confirmation } } : {}) };
+    }
     setPreparationHandler(handler) { this.preparationHandler = handler; }
     prepare(options) {
         if (!this.preparationHandler)
@@ -195,14 +197,28 @@ export class CheckoutLifecycle {
         catch {
             result = { status: 'unknown' };
         }
-        if (!result || typeof result !== 'object')
+        if (!result || typeof result !== 'object' || Array.isArray(result))
             result = { status: 'unknown' };
-        if (result.status === 'completed' && typeof result.orderId === 'string' && result.orderId.length > 0) {
+        // The resolver is trusted application code: it must check the original
+        // request, amount, currency, selected card and authoritative merchant
+        // result. The SDK binds its explicit confirmation to this authorization;
+        // it does not turn an HTTP response or a success URL into payment proof.
+        const orderConfirmed = result.status === 'completed' && result.confirmation === undefined
+            && typeof result.orderId === 'string' && result.orderId.length > 0;
+        const paymentConfirmed = result.status === 'completed' && result.orderId === undefined
+            && result.confirmation && typeof result.confirmation === 'object' && !Array.isArray(result.confirmation)
+            && result.confirmation.kind === 'merchant_payment'
+            && typeof this.state.authorizationId === 'string' && this.state.authorizationId.length > 0
+            && result.confirmation.authorizationId === this.state.authorizationId;
+        if (result.status === 'completed' && (orderConfirmed || paymentConfirmed)) {
             this.held = true;
-            // Merchant completion supersedes the earlier failure or user-action
-            // reason; keep the authorization and preparation context for observers.
-            const { reason: _previousReason, ...context } = this.state;
-            this.set({ ...context, status: 'completed', orderId: result.orderId });
+            // Completion supersedes an earlier failure/challenge, while retaining
+            // preparation and authorization context. Never copy arbitrary evidence
+            // into public state or release the hold on additional payment requests.
+            const { reason: _previousReason, orderId: _previousOrder, confirmation: _previousConfirmation, ...context } = this.state;
+            this.set({ ...context, status: 'completed', ...(orderConfirmed
+                    ? { orderId: result.orderId }
+                    : { confirmation: { kind: 'merchant_payment', authorizationId: this.state.authorizationId } }) });
         }
         else if (result.status === 'failed') {
             // Keep the guard armed until the application deliberately starts another attempt.

package/dist/stripe-checkout.d.ts

@@ -1,3 +1,4 @@
+import { STRIPE_CHECKOUT_VALIDATION_CODES } from './stripe-checkout.generated.js';
 import type { PausedRequest } from './client.js';
 /** Test by default. Production requires explicit opt-in and an independently admitted live grant. */
 export interface StripeCheckoutOptions {
@@ -19,11 +20,12 @@ type Step = {
 };
 type Phase = Step['phase'] | 'unknown';
 type GateState = 'fresh' | 'stubbed' | 'submitted' | 'stopped';
+type ValidationCode = (typeof STRIPE_CHECKOUT_VALIDATION_CODES)[keyof typeof STRIPE_CHECKOUT_VALIDATION_CODES];
 export type StripeCheckoutBlockStage = 'request_read' | 'classification' | 'claim' | 'readiness' | 'document' | 'stub_response';
 type ReadinessReason = 'attachment_not_ready' | 'cancelled' | 'checkout_inactive' | 'approval_pending' | 'request_inactive';
 export type StripeCheckoutBlockReason = ReadinessReason | 'request_unavailable' | 'request_validation_failed' | 'context_already_present' | 'duplicate_tokenization' | 'duplicate_confirmation' | 'preparation_unavailable' | 'preparation_missing' | 'claim_invalidated' | 'document_changed' | 'document_unavailable' | 'readiness_unavailable' | 'stub_response_failed';
 /** Native pre-authorization refusal metadata. Never contains request or exception text.
- * Classification failures intentionally do not guess which shared-core predicate rejected.
+ * A classification code comes only from the shared core's fixed vocabulary.
  * gate_state is observed before the adapter retires a failed claim. A preserved duplicate
  * belongs to a competing request: consumers must not cancel the active checkout for it.
  */
@@ -34,6 +36,7 @@ export interface StripeCheckoutBlockedDetail {
     phase: Phase;
     stage: StripeCheckoutBlockStage;
     reason: StripeCheckoutBlockReason;
+    validation_code?: ValidationCode;
     gate_state: GateState;
     disposition: 'active_claim_preserved' | 'checkout_stopped';
 }
@@ -41,7 +44,8 @@ declare class StripeCheckoutRejectionError extends Error {
     readonly stage: StripeCheckoutBlockStage;
     readonly reason: StripeCheckoutBlockReason;
     readonly phase?: Phase | undefined;
-    constructor(message: string, stage: StripeCheckoutBlockStage, reason: StripeCheckoutBlockReason, phase?: Phase | undefined);
+    readonly validationCode?: ValidationCode | undefined;
+    constructor(message: string, stage: StripeCheckoutBlockStage, reason: StripeCheckoutBlockReason, phase?: Phase | undefined, validationCode?: ValidationCode | undefined);
 }
 export declare function stripeCheckoutReadinessError(reason: ReadinessReason): Error;
 /** A valid competing request must not retire the request that already claimed this step. */

package/dist/stripe-checkout.generated.d.ts

@@ -1,5 +1,29 @@
 declare var STRIPE_CHECKOUT_OPERATION: string;
 declare var STRIPE_CHECKOUT_CONTEXT_HEADER: string;
+declare var STRIPE_CHECKOUT_VALIDATION_CODES: Readonly<{
+    unclassified: "unclassified";
+    request_shape: "request_shape";
+    request_body_bounds: "request_body_bounds";
+    request_headers: "request_headers";
+    form_encoding: "form_encoding";
+    form_field_unknown: "form_field_unknown";
+    form_field_duplicate: "form_field_duplicate";
+    form_value_bounds: "form_value_bounds";
+    context_invalid: "context_invalid";
+    session_binding: "session_binding";
+    publishable_key: "publishable_key";
+    mode_binding: "mode_binding";
+    attribution_session: "attribution_session";
+    tokenization_fields: "tokenization_fields";
+    billing_email: "billing_email";
+    billing_binding: "billing_binding";
+    billing_conflict: "billing_conflict";
+    expected_amount: "expected_amount";
+    payment_method_type: "payment_method_type";
+    synthetic_payment_method: "synthetic_payment_method";
+    required_final_fields: "required_final_fields";
+}>;
+declare function stripeCheckoutValidationCode(error: any): "unclassified" | "request_shape" | "request_body_bounds" | "request_headers" | "form_encoding" | "form_field_unknown" | "form_field_duplicate" | "form_value_bounds" | "context_invalid" | "session_binding" | "publishable_key" | "mode_binding" | "attribution_session" | "tokenization_fields" | "billing_email" | "billing_binding" | "billing_conflict" | "expected_amount" | "payment_method_type" | "synthetic_payment_method" | "required_final_fields";
 declare function validateStripeCheckoutIdentity(value: any): Readonly<{
     environment: any;
     livemode: boolean;
@@ -55,4 +79,4 @@ declare function prepareStripeCheckoutReplay(request: any, card: any, options?:
     };
     where: string[];
 };
-export { STRIPE_CHECKOUT_CONTEXT_HEADER, STRIPE_CHECKOUT_OPERATION, attachStripeCheckoutBilling, captureStripeCheckoutBilling, classifyStripeCheckoutRequest, createStripeCheckoutTokenizationStub, encodeStripeCheckoutContext, hasStripeCheckoutMarker, isStripeCheckoutEndpoint, isStripeCheckoutHostedMode, parseStripeCheckoutContext, parseStripeCheckoutResponse, prepareStripeCheckoutReplay, validateStripeCheckoutCard, validateStripeCheckoutIdentity };
+export { STRIPE_CHECKOUT_CONTEXT_HEADER, STRIPE_CHECKOUT_OPERATION, STRIPE_CHECKOUT_VALIDATION_CODES, attachStripeCheckoutBilling, captureStripeCheckoutBilling, classifyStripeCheckoutRequest, createStripeCheckoutTokenizationStub, encodeStripeCheckoutContext, hasStripeCheckoutMarker, isStripeCheckoutEndpoint, isStripeCheckoutHostedMode, parseStripeCheckoutContext, parseStripeCheckoutResponse, prepareStripeCheckoutReplay, stripeCheckoutValidationCode, validateStripeCheckoutCard, validateStripeCheckoutIdentity };

package/dist/stripe-checkout.generated.js

@@ -1,6 +1,6 @@
 // @ts-nocheck
 // Generated from @agent-cards/payment-core. Do not edit.
-// artifact-sha256: 2f7e340ba22bc33539f11e384a3e8362ae3fa510a9f8b540783c02bebcbc1ebf
+// artifact-sha256: edd2d9de25c51bf0f4ebdbe729366e6d94b9a045b054a0910571e0565bd3cae0
 // src/definitions.js
 function deepFreeze(value) {
     if (value && typeof value === "object" && !Object.isFrozen(value)) {
@@ -527,19 +527,49 @@ var STRIPE_CHECKOUT_CONTEXT_HEADER = "x-agentcard-stripe-checkout-context";
 var SESSION = /^cs_(?:test|live)_[A-Za-z0-9]{1,200}(?![\s\S])/;
 var KEY = /^pk_(?:test|live)_[A-Za-z0-9_]{1,256}(?![\s\S])/;
 var SYNTHETIC = /^pm_agentcard_checkout_[A-Za-z0-9_-]{16,80}(?![\s\S])/;
-var reject = () => {
-    throw new Error("stripe_checkout_rejected");
+var STRIPE_CHECKOUT_VALIDATION_CODES = Object.freeze({
+    unclassified: "unclassified",
+    request_shape: "request_shape",
+    request_body_bounds: "request_body_bounds",
+    request_headers: "request_headers",
+    form_encoding: "form_encoding",
+    form_field_unknown: "form_field_unknown",
+    form_field_duplicate: "form_field_duplicate",
+    form_value_bounds: "form_value_bounds",
+    context_invalid: "context_invalid",
+    session_binding: "session_binding",
+    publishable_key: "publishable_key",
+    mode_binding: "mode_binding",
+    attribution_session: "attribution_session",
+    tokenization_fields: "tokenization_fields",
+    billing_email: "billing_email",
+    billing_binding: "billing_binding",
+    billing_conflict: "billing_conflict",
+    expected_amount: "expected_amount",
+    payment_method_type: "payment_method_type",
+    synthetic_payment_method: "synthetic_payment_method",
+    required_final_fields: "required_final_fields"
+});
+var validationCodes = /* @__PURE__ */ new WeakMap();
+var reject = (code = "unclassified") => {
+    const error = new Error("stripe_checkout_rejected");
+    validationCodes.set(error, code);
+    throw error;
 };
+function stripeCheckoutValidationCode(error) {
+    const code = validationCodes.get(error);
+    return Object.values(STRIPE_CHECKOUT_VALIDATION_CODES).find((value) => value === code) ?? STRIPE_CHECKOUT_VALIDATION_CODES.unclassified;
+}
 var object = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
 var opaque = (value) => typeof value === "string" && value.length <= 8192 && !/[\x00-\x1f\x7f]/.test(value);
 var alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
 function validateStripeCheckoutIdentity(value) {
     if (!object(value) || !["test", "production"].includes(value.environment ?? "test") || value.environment === null || !["sessionId", "publishableKey", "livemode"].some((key) => Object.hasOwn(value, key)))
-        reject();
+        reject("mode_binding");
     const environment = value.environment ?? "test", livemode = environment === "production";
     const mode = livemode ? "live" : "test";
     if (Object.hasOwn(value, "sessionId") && (typeof value.sessionId !== "string" || !SESSION.test(value.sessionId) || !value.sessionId.startsWith(`cs_${mode}_`)) || Object.hasOwn(value, "publishableKey") && (typeof value.publishableKey !== "string" || !KEY.test(value.publishableKey) || !value.publishableKey.startsWith(`pk_${mode}_`)) || Object.hasOwn(value, "livemode") && value.livemode !== livemode)
-        reject();
+        reject("mode_binding");
     return Object.freeze({ environment, livemode });
 }
 var TEST_CARDS = ["4242424242424242", "4000000000000002", "4000002500003155"];
@@ -587,7 +617,7 @@ function encodeAscii(value) {
 }
 function context(value) {
     if (!object(value) || Object.keys(value).length !== 3 || value.version !== 1 || !["version", "session_id", "synthetic_payment_method_id"].every((key) => Object.hasOwn(value, key)) || !SESSION.test(value.session_id) || !SYNTHETIC.test(value.synthetic_payment_method_id))
-        reject();
+        reject("context_invalid");
     return { version: 1, session_id: value.session_id, synthetic_payment_method_id: value.synthetic_payment_method_id };
 }
 function encodeStripeCheckoutContext(value) {
@@ -601,7 +631,7 @@ function parseStripeCheckoutContext(request) {
     if (!entries.length)
         return null;
     if (entries.length !== 1 || typeof entries[0][1] !== "string" || !/^[A-Za-z0-9_-]{1,1024}$/.test(entries[0][1]))
-        reject();
+        reject("context_invalid");
     const encoded = entries[0][1];
     let text = "", bits = 0, count = 0;
     for (const char of encoded) {
@@ -617,10 +647,10 @@ function parseStripeCheckoutContext(request) {
         value = context(JSON.parse(text));
     }
     catch {
-        reject();
+        reject("context_invalid");
     }
     if (encodeStripeCheckoutContext(value) !== encoded)
-        reject();
+        reject("context_invalid");
     return value;
 }
 function endpoint(raw) {
@@ -657,6 +687,9 @@ var finalFields = /* @__PURE__ */ new Set([
     "sid",
     "passive_captcha_token",
     "passive_captcha_ekey",
+    "pxcts",
+    "pxvid",
+    "px3",
     ...[
         "checkout_config_id",
         "checkout_session_id",
@@ -696,24 +729,32 @@ var tokenFields = /* @__PURE__ */ new Set([
     ].map((key) => `client_attribution_metadata[${key}]`)
 ]);
 function form(request, fields) {
-    if (!object(request) || request.method !== "POST" || typeof request.body !== "string" || request.body.length > 2e4 || !object(request.headers) || Object.keys(request.headers).length > 40 || Object.values(request.headers).some((value) => !opaque(value)))
-        reject();
+    if (!object(request) || request.method !== "POST" || typeof request.body !== "string")
+        reject("request_shape");
+    if (request.body.length > 2e4)
+        reject("request_body_bounds");
+    if (!object(request.headers) || Object.keys(request.headers).length > 40 || Object.values(request.headers).some((value) => !opaque(value)))
+        reject("request_headers");
     const pairs = [];
     const seen = /* @__PURE__ */ new Set();
     for (const raw of request.body.split("&")) {
         const index = raw.indexOf("=");
         if (index < 1)
-            reject();
+            reject("form_encoding");
         let key, value;
         try {
             key = decodeURIComponent(raw.slice(0, index).replace(/\+/g, " "));
             value = decodeURIComponent(raw.slice(index + 1).replace(/\+/g, " "));
         }
         catch {
-            reject();
+            reject("form_encoding");
         }
-        if (!fields.has(key) || seen.has(key) || !opaque(value))
-            reject();
+        if (!fields.has(key))
+            reject("form_field_unknown");
+        if (seen.has(key))
+            reject("form_field_duplicate");
+        if (!opaque(value))
+            reject("form_value_bounds");
         seen.add(key);
         pairs.push({ key, value, raw });
     }
@@ -722,27 +763,27 @@ function form(request, fields) {
 function keyFor(request, values, expected) {
     const authorization = Object.entries(request.headers).filter(([key2]) => key2.toLowerCase() === "authorization");
     if (authorization.length > 1)
-        reject();
+        reject("publishable_key");
     let headerKey;
     if (authorization.length) {
         const match = /^Bearer (pk_(?:test|live)_[A-Za-z0-9_]{1,256})$/.exec(authorization[0][1]);
         if (!match)
-            reject();
+            reject("publishable_key");
         headerKey = match[1];
     }
     const key = values.get("key") || headerKey;
     if (!KEY.test(key) || headerKey && headerKey !== key || expected !== void 0 && expected !== key)
-        reject();
+        reject("publishable_key");
     return key;
 }
 var billingEmail = (value) => value === null || typeof value === "string" && value.length > 0 && value.length <= 320 && opaque(value);
 function captureStripeCheckoutBilling(request, options) {
     const phase = classifyStripeCheckoutRequest(request, options);
     if (phase?.phase !== "tokenization" || !SYNTHETIC.test(options?.syntheticPaymentMethodId))
-        reject();
+        reject("billing_binding");
     const email = form(request, tokenFields).values.get("billing_details[email]") ?? null;
     if (!billingEmail(email))
-        reject();
+        reject("billing_email");
     return Object.freeze({
         session_id: phase.session_id,
         synthetic_payment_method_id: options.syntheticPaymentMethodId,
@@ -752,11 +793,11 @@ function captureStripeCheckoutBilling(request, options) {
 function attachStripeCheckoutBilling(request, captured, options) {
     const phase = classifyStripeCheckoutRequest(request, options);
     if (phase?.phase !== "final" || !object(captured) || Object.keys(captured).length !== 3 || !["session_id", "synthetic_payment_method_id", "email"].every((key) => Object.hasOwn(captured, key)) || captured.session_id !== phase.session_id || captured.synthetic_payment_method_id !== phase.synthetic_payment_method_id || !billingEmail(captured.email))
-        reject();
+        reject("billing_binding");
     const field = "payment_method_data[billing_details][email]";
     const existing = form(request, finalFields).values.get(field);
     if (existing !== void 0 && existing !== captured.email)
-        reject();
+        reject("billing_conflict");
     if (captured.email === null || existing !== void 0)
         return { ...request };
     const body = `${request.body}&${encodeURIComponent(field)}=${encodeURIComponent(captured.email)}`;
@@ -768,14 +809,14 @@ function classifyStripeCheckoutRequest(request, options = {}) {
     const url = endpoint(request?.url);
     if (!url) {
         if (hasStripeCheckoutMarker(request))
-            reject();
+            reject("context_invalid");
         return null;
     }
     const final = isStripeCheckoutEndpoint(request.url);
     const token = url.pathname === "/v1/payment_methods";
     if (!final && !token) {
         if (hasStripeCheckoutMarker(request))
-            reject();
+            reject("context_invalid");
         return null;
     }
     if (token && options.sessionId === void 0 && !hasStripeCheckoutMarker(request))
@@ -783,26 +824,34 @@ function classifyStripeCheckoutRequest(request, options = {}) {
     const marker = parseStripeCheckoutContext(request);
     const sessionId = final ? url.pathname.split("/")[3] : options.sessionId;
     if (!SESSION.test(sessionId) || options.sessionId !== void 0 && options.sessionId !== sessionId || marker && marker.session_id !== sessionId)
-        reject();
+        reject("session_binding");
     const { values } = form(request, final ? finalFields : tokenFields);
     const key = keyFor(request, values, options.publishableKey);
     validateStripeCheckoutIdentity({ environment: options.environment, sessionId, publishableKey: key });
     const attributionSession = values.get("client_attribution_metadata[checkout_session_id]");
     if (attributionSession !== void 0 && attributionSession !== sessionId)
-        reject();
+        reject("attribution_session");
     if (token) {
         const number = values.get("card[number]");
         if (values.get("type") !== "card" || typeof number !== "string" || number.length > 64 || /[^0-9 -]/.test(number) || !["4111111111111111", "4242424242424242"].includes(number.replace(/[ -]/g, "")) || !/^\d{3}$/.test(values.get("card[cvc]") ?? "") || !/^(?:0?[1-9]|1[0-2])$/.test(values.get("card[exp_month]") ?? "") || !/^(?:\d{2}|\d{4})$/.test(values.get("card[exp_year]") ?? "") || values.has("allow_redisplay") && values.get("allow_redisplay") !== "unspecified")
-            reject();
+            reject("tokenization_fields");
         return { phase: "tokenization", session_id: sessionId, publishable_key: key };
     }
     const amount = values.get("expected_amount");
     const syntheticId = values.get("payment_method");
     const email = values.get("payment_method_data[billing_details][email]");
     if (email !== void 0 && !billingEmail(email))
-        reject();
-    if (!/^[1-9]\d{0,11}$/.test(amount ?? "") || !Number.isSafeInteger(Number(amount)) || options.amountCents !== void 0 && options.amountCents !== Number(amount) || values.get("expected_payment_method_type") !== "card" || !SYNTHETIC.test(syntheticId) || ["init_checksum", "js_checksum", "version", "rv_timestamp"].some((key2) => !values.get(key2)) || options.syntheticPaymentMethodId !== void 0 && options.syntheticPaymentMethodId !== syntheticId || marker && marker.synthetic_payment_method_id !== syntheticId)
-        reject();
+        reject("billing_email");
+    if (!/^[1-9]\d{0,11}$/.test(amount ?? "") || !Number.isSafeInteger(Number(amount)) || options.amountCents !== void 0 && options.amountCents !== Number(amount))
+        reject("expected_amount");
+    if (values.get("expected_payment_method_type") !== "card")
+        reject("payment_method_type");
+    if (!SYNTHETIC.test(syntheticId))
+        reject("synthetic_payment_method");
+    if (["init_checksum", "js_checksum", "version", "rv_timestamp"].some((key2) => !values.get(key2)))
+        reject("required_final_fields");
+    if (options.syntheticPaymentMethodId !== void 0 && options.syntheticPaymentMethodId !== syntheticId || marker && marker.synthetic_payment_method_id !== syntheticId)
+        reject("synthetic_payment_method");
     return {
         phase: "final",
         session_id: sessionId,
@@ -912,4 +961,4 @@ function prepareStripeCheckoutReplay(request, card, options = {}) {
         where: Object.keys(replacements)
     };
 }
-export { STRIPE_CHECKOUT_CONTEXT_HEADER, STRIPE_CHECKOUT_OPERATION, attachStripeCheckoutBilling, captureStripeCheckoutBilling, classifyStripeCheckoutRequest, createStripeCheckoutTokenizationStub, encodeStripeCheckoutContext, hasStripeCheckoutMarker, isStripeCheckoutEndpoint, isStripeCheckoutHostedMode, parseStripeCheckoutContext, parseStripeCheckoutResponse, prepareStripeCheckoutReplay, validateStripeCheckoutCard, validateStripeCheckoutIdentity };
+export { STRIPE_CHECKOUT_CONTEXT_HEADER, STRIPE_CHECKOUT_OPERATION, STRIPE_CHECKOUT_VALIDATION_CODES, attachStripeCheckoutBilling, captureStripeCheckoutBilling, classifyStripeCheckoutRequest, createStripeCheckoutTokenizationStub, encodeStripeCheckoutContext, hasStripeCheckoutMarker, isStripeCheckoutEndpoint, isStripeCheckoutHostedMode, parseStripeCheckoutContext, parseStripeCheckoutResponse, prepareStripeCheckoutReplay, stripeCheckoutValidationCode, validateStripeCheckoutCard, validateStripeCheckoutIdentity };

package/dist/stripe-checkout.js

@@ -1,13 +1,15 @@
-import { classifyStripeCheckoutRequest, createStripeCheckoutTokenizationStub, encodeStripeCheckoutContext, isStripeCheckoutEndpoint, STRIPE_CHECKOUT_CONTEXT_HEADER, captureStripeCheckoutBilling, attachStripeCheckoutBilling, validateStripeCheckoutIdentity, } from './stripe-checkout.generated.js';
+import { classifyStripeCheckoutRequest, createStripeCheckoutTokenizationStub, encodeStripeCheckoutContext, isStripeCheckoutEndpoint, STRIPE_CHECKOUT_CONTEXT_HEADER, captureStripeCheckoutBilling, attachStripeCheckoutBilling, validateStripeCheckoutIdentity, stripeCheckoutValidationCode, STRIPE_CHECKOUT_VALIDATION_CODES, } from './stripe-checkout.generated.js';
 class StripeCheckoutRejectionError extends Error {
     stage;
     reason;
     phase;
-    constructor(message, stage, reason, phase) {
+    validationCode;
+    constructor(message, stage, reason, phase, validationCode) {
         super(message);
         this.stage = stage;
         this.reason = reason;
         this.phase = phase;
+        this.validationCode = validationCode;
     }
 }
 export function stripeCheckoutReadinessError(reason) {
@@ -59,8 +61,10 @@ export class StripeCheckoutGate {
             readiness: 'readiness_unavailable', document: 'document_unavailable', stub_response: 'stub_response_failed',
         };
         const rejection = error instanceof StripeCheckoutRejectionError ? error : undefined;
+        const reason = rejection?.reason ?? fallback[stage];
         return { version: 1, processor: 'stripe', endpoint_family: family,
-            phase: rejection?.phase ?? phase, stage: rejection?.stage ?? stage, reason: rejection?.reason ?? fallback[stage],
+            phase: rejection?.phase ?? phase, stage: rejection?.stage ?? stage, reason,
+            ...(reason === 'request_validation_failed' ? { validation_code: rejection?.validationCode ?? STRIPE_CHECKOUT_VALIDATION_CODES.unclassified } : {}),
             gate_state: this.state, disposition: error instanceof StripeCheckoutClaimConflictError ? 'active_claim_preserved' : 'checkout_stopped' };
     }
     assertClaim(step) {
@@ -73,7 +77,7 @@ export class StripeCheckoutGate {
             return;
         const url = new URL(raw);
         if (url.origin !== 'https://checkout.stripe.com' || url.username || url.password
-            || ![`/c/pay/${this.binding.sessionId}`, `/pay/${this.binding.sessionId}`].includes(url.pathname)) {
+            || ![`/c/pay/${this.binding.sessionId}`, `/pay/${this.binding.sessionId}`, `/g/pay/${this.binding.sessionId}`, `/f/pay/${this.binding.sessionId}`].includes(url.pathname)) {
             this.invalidate();
             throw new StripeCheckoutRejectionError('Native Stripe Checkout document changed.', 'document', 'document_changed');
         }
@@ -87,8 +91,8 @@ export class StripeCheckoutGate {
         try {
             phase = classifyStripeCheckoutRequest(request, this.binding);
         }
-        catch {
-            throw new StripeCheckoutRejectionError('stripe_checkout_rejected', 'classification', 'request_validation_failed', 'unknown');
+        catch (error) {
+            throw new StripeCheckoutRejectionError('stripe_checkout_rejected', 'classification', 'request_validation_failed', 'unknown', stripeCheckoutValidationCode(error));
         }
         if (!phase)
             return null;
@@ -106,7 +110,10 @@ export class StripeCheckoutGate {
                 this.billing = captureStripeCheckoutBilling(request, this.binding);
                 response = createStripeCheckoutTokenizationStub(request, this.binding);
             }
-            catch {
+            catch (error) {
+                const code = stripeCheckoutValidationCode(error);
+                if (code !== STRIPE_CHECKOUT_VALIDATION_CODES.unclassified)
+                    throw new StripeCheckoutRejectionError('stripe_checkout_rejected', 'classification', 'request_validation_failed', 'tokenization', code);
                 throw new StripeCheckoutRejectionError('stripe_checkout_rejected', 'stub_response', 'stub_response_failed', 'tokenization');
             }
             this.state = 'stubbed';
@@ -120,9 +127,9 @@ export class StripeCheckoutGate {
         try {
             final = attachStripeCheckoutBilling(request, this.billing, this.binding);
         }
-        catch {
+        catch (error) {
             this.invalidate();
-            throw new StripeCheckoutRejectionError('stripe_checkout_rejected', 'classification', 'request_validation_failed', 'final');
+            throw new StripeCheckoutRejectionError('stripe_checkout_rejected', 'classification', 'request_validation_failed', 'final', stripeCheckoutValidationCode(error));
         }
         this.state = 'submitted';
         this.billing = undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-cards/checkout",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Let browser agents pay with the user's own card, without your infrastructure ever touching card data.",
   "type": "module",
   "main": "dist/index.js",
@@ -27,7 +27,7 @@
     "_comment_build": "The public SDK keeps zero runtime dependencies. Its build vendors deterministic metadata and substitution artifacts from the internal payment core; TypeScript remains pinned.",
     "build": "node ../payment-core/scripts/build.mjs && node scripts/generate-payment-core.mjs && npx -y -p typescript@5.9.3 tsc && node scripts/generate-preflight-contract.mjs",
     "prepublishOnly": "pnpm build",
-    "test": "node test.mjs && node --test lifecycle.test.mjs merchant-abort.test.mjs preparation.test.mjs braintree.test.mjs autopilot.test.mjs stripe-checkout.test.mjs payment-core.test.mjs prepared-processor.test.mjs minimum-delay.test.mjs paysafe.test.mjs attachment.test.mjs mercado-checkout.test.mjs mercado-polling.test.mjs && node --test preflight-package.test.mjs preflight-collector.test.mjs && node --test kernel-native-qualification.test.mjs",
+    "test": "node test.mjs && node --test lifecycle.test.mjs merchant-abort.test.mjs preparation.test.mjs braintree.test.mjs autopilot.test.mjs stripe-checkout.test.mjs payment-core.test.mjs prepared-processor.test.mjs minimum-delay.test.mjs paysafe.test.mjs attachment.test.mjs mercado-checkout.test.mjs mercado-polling.test.mjs && node --test preflight-package.test.mjs preflight-collector.test.mjs && node --test kernel-native-qualification.test.mjs && node --test ../vault/scripts/recurly-validation/watch-duty-sdk-result.test.mjs",
     "test:browser": "node browser.test.mjs && node stripe-browser.test.mjs && node preparation-browser.test.mjs && node owned-shop-browser.test.mjs",
     "check:payment-core": "node scripts/generate-payment-core.mjs --check",
     "test:preflight": "node --test preflight-package.test.mjs preflight-collector.test.mjs kernel-native-qualification.test.mjs",