@agent-cards/checkout 0.4.1 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.5.0
+
+- Prepare Braintree card checkout with `controller.prepare({ psp: 'braintree', environment: 'production' | 'sandbox' })` before the merchant's first Pay action. The cardholder approves and unlocks first; one fresh native request then uses that approval without another notification. The matching API and Vault release is required.
+- Let native Braintree client-configuration queries pass without consuming consent. Prepared checkout accepts one card-tokenization mutation for the approved processor and environment. Other operations, ambiguous GraphQL payloads and legacy REST fallback cannot use the preparation.
+- Keep the native request timeout and one-use, card, merchant, amount, currency and document bindings. Approval readiness lasts at most 30 seconds. Tokenization amounts remain display-only; a token does not establish a paid order.
+- Add a real Chromium fixture with approval delayed 61 seconds before a fresh 60-second XHR, plus cancellation, request classification and binding regressions. The isolated fixture contacts no payment processor and is not live purchase proof.
+
 ## 0.4.1
 
 - Stop describing every processor request rejection as a card decline or proof that nothing was charged. `ProcessorRefusedError` keeps its existing class and code, with neutral wording and an optional `processorError` containing bounded Razorpay reason, source, step and payment/order identifiers from the matching API/Vault release. Older failure records cannot recover details that were not retained.

package/README.md

@@ -82,7 +82,7 @@ pair is shown and reported (`amountAuthority: 'display_only'`), not enforced.
 Then let your agent click "Pay" like it always does. `attachToCdp` pauses the
 request for approval and resumes it only while the merchant request remains
 live. Merchant timeouts still apply: Square's observed tokenization deadline
-is about 10 seconds for approval and token handoff. For human approval, use
+is about 10 seconds, and Braintree's native request timeout is 60 seconds, including approval and token handoff. For human approval, use
 `controller.prepare()` before the first Pay action as shown below.
 
 Playwright:
@@ -130,7 +130,7 @@ Coverage is specific to the processor request format, merchant setup, browser tr
 |---|---|
 | Shopify | supported, verified end to end |
 | Stripe | tokenization replay and direct card-bearing PaymentIntent confirms are implemented; direct confirms with `amountCents` + `currency` use backend amount verification. Browser token-to-intent continuation is unsupported and held. Validate the exact merchant flow before pilot use |
-| Braintree / PayPal | supported, verified end to end |
+| Braintree card tokenization | prepared checkout supported; production paid-order validation pending |
 | Checkout.com | supported |
 | VGS Collect (Very Good Security; Wolt) | not supported: VGS's proxy aliases only submissions from its own iframe, so a replay from the cardholder's device is refused by the merchant (verified on Wolt, 2026-09-03). Not recognized, so the agent's browser is not paused there |
 | Adyen | supported (mode `cse`): the vault encrypts the card for Adyen on the cardholder's device and your browser sends it |
@@ -400,7 +400,7 @@ do not reuse that token in a new attachment as a workaround. Configuration and
 unsupported-mode failures require fixing the integration. Bank flows requiring
 another confirmation and other stored-token chains remain unverified.
 
-Square's observed native tokenization request expires after about 10 seconds. SDK 0.4.0 adds approval before submission, requiring the matching preparation API and Vault deployment. Start human approval before the caller's first Pay action:
+Prepare a Square or Braintree checkout before the first Pay action so the cardholder can approve before the native card request starts. The API and Vault deployments must support the selected processor:
 
 ```ts
 const checkout = await attachToPlaywright(page, {
@@ -409,19 +409,21 @@ const checkout = await attachToPlaywright(page, {
   onApprovalUrl: deliverPrivatelyToCardholder,
 });
 const preparation = await checkout.prepare({
-  psp: 'square',
-  environment: 'production', // explicit; use 'sandbox' for Square Sandbox
+  psp: 'braintree', // use 'square' for Square
+  environment: 'production', // explicit; use 'sandbox' for the processor's sandbox
 });
 // The cardholder has consented and unlocked the same approval document.
 // No processor request or payment has started.
 await page.getByRole('button', { name: 'Pay', exact: true }).click();
 ```
 
-`prepare()` is available on both Playwright and raw CDP controllers. It requires `amountCents` and `currency`, must precede the first recognized card request, and returns only when the cardholder's device is ready. It delivers the preparation URL through `onApprovalUrl` and `onUserAction`; binding the subsequent authorization sends no second approval link or SMS. The phone page must stay open. Its selected card, merchant origin, declared merchant, amount, currency and Square environment bind one fresh request. The amount remains `display_only`; a Square token does not enforce the merchant's eventual charge amount.
+`prepare()` is available on both Playwright and raw CDP controllers. It requires `amountCents` and `currency`, must precede the first recognized card request, and returns only when the cardholder's device is ready. It delivers the preparation URL through `onApprovalUrl` and `onUserAction`; binding the subsequent authorization sends no second approval link or SMS. The phone page must stay open. Its selected card, merchant origin, declared merchant, amount, currency, processor and environment bind one fresh request. The amount remains `display_only`; a card token does not enforce the merchant's eventual charge amount.
 
-Readiness lasts up to 30 seconds (`preparation.expiresAt`) and appears as `ready_to_submit`, with `paymentStatus: 'not_started'`. Trigger the caller-owned Pay action immediately after the promise resolves. Expiry, navigation, cancellation, an early request or a changed checkout fails closed. A preparation and its attachment are single use; reconcile any bound authorization before creating a new attachment. The SDK never clicks Pay, reuses a stale request, pauses Square timers, or automatically retries a failed prepared checkout.
+Braintree's native `ClientConfiguration` GraphQL query can run before, during or after preparation without using the approval. Only a single `TokenizeCreditCard` mutation can consume the prepared Braintree checkout. Prepared requests require guest card tokenization with explicit `options.validate: false`; omitted validation options, saved-card fields and `validate: true` are refused. Other GraphQL operations, batches and compound mutations are blocked. Braintree's legacy REST fallback cannot consume a prepared authorization.
 
-After Pay, Square's native deadline still covers fresh authorization binding, device replay, relay and token handoff. A disconnected/backgrounded phone or slow transport can still miss it. A subsequent SCA challenge has its own lifetime after token handoff. If the merchant request aborts or its frame closes, the attachment blocks further requests and tries to retire the pre-replay authorization; a started replay or unconfirmed cancellation remains unknown. Without `prepare()`, approval loading and human interaction still share the native deadline, so delayed approval cannot finish that request.
+Readiness lasts up to 30 seconds (`preparation.expiresAt`) and appears as `ready_to_submit`, with `paymentStatus: 'not_started'`. Trigger the caller-owned Pay action immediately after the promise resolves. Expiry, navigation, cancellation, an early request or a changed checkout fails closed. A preparation and its attachment are single use; reconcile any bound authorization before creating a new attachment. The SDK never clicks Pay, reuses a stale request, changes native request deadlines, or automatically retries a failed prepared checkout.
+
+After Pay, the processor's native deadline still covers fresh authorization binding, device replay and token handoff. A disconnected/backgrounded phone or slow transport can still miss it. A subsequent SCA challenge has its own lifetime after token handoff. If the merchant request aborts or its frame closes, the attachment blocks further requests and tries to retire the pre-replay authorization; a started replay or unconfirmed cancellation remains unknown. Without `prepare()`, approval loading and human interaction still share the native deadline, so delayed approval cannot finish that request.
 
 Lost authorization polling, local approval timeouts, or interrupted browser
 handoffs produce `outcome_unknown` and block automatic retry. The thrown

package/dist/braintree.d.ts

@@ -0,0 +1,8 @@
+/** Classify native Braintree GraphQL requests without changing their bytes. */
+export type BraintreeEnvironment = 'production' | 'sandbox';
+export type BraintreeRequestKind = 'configuration' | 'tokenization' | 'invalid';
+export declare function braintreeEnvironment(url: string): BraintreeEnvironment | undefined;
+/** Undefined belongs to another processor; invalid Braintree requests stay blocked. */
+export declare function classifyBraintreeRequest(url: string, method: string, body: string | null): BraintreeRequestKind | undefined;
+/** Preparation accepts guest tokenization only; ordinary interception stays broader. */
+export declare function isPreparedBraintreeRequest(body: string | null): boolean;

package/dist/braintree.js

@@ -0,0 +1,290 @@
+const PRODUCTION = 'https://payments.braintree-api.com/graphql';
+const SANDBOX = 'https://payments.sandbox.braintree-api.com/graphql';
+const MAX_BODY_LENGTH = 128 * 1024;
+const MAX_DEPTH = 32;
+const MAX_NODES = 10_000;
+export function braintreeEnvironment(url) {
+    return url === PRODUCTION ? 'production' : url === SANDBOX ? 'sandbox' : undefined;
+}
+function invalid() { throw new Error('invalid_braintree_request'); }
+function record(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+/** JSON.parse discards duplicate keys, so validate keys before using any value. */
+class JsonReader {
+    text;
+    at = 0;
+    nodes = 0;
+    constructor(text) {
+        this.text = text;
+    }
+    read() {
+        const value = this.value(0);
+        this.space();
+        if (this.at !== this.text.length)
+            invalid();
+        return value;
+    }
+    space() {
+        while (' \t\r\n'.includes(this.text[this.at] ?? '\0'))
+            this.at++;
+    }
+    take(expected) {
+        this.space();
+        if (this.text[this.at++] !== expected)
+            invalid();
+    }
+    string() {
+        this.space();
+        const start = this.at;
+        if (this.text[this.at++] !== '"')
+            invalid();
+        while (this.at < this.text.length) {
+            const char = this.text[this.at++];
+            if (char === '\\') {
+                this.at++;
+                continue;
+            }
+            if (char === '"')
+                return JSON.parse(this.text.slice(start, this.at));
+        }
+        return invalid();
+    }
+    value(depth) {
+        if (depth > MAX_DEPTH || ++this.nodes > MAX_NODES)
+            invalid();
+        this.space();
+        const char = this.text[this.at];
+        if (char === '"')
+            return this.string();
+        if (char === '{') {
+            this.at++;
+            const result = Object.create(null);
+            const keys = new Set();
+            this.space();
+            if (this.text[this.at] === '}') {
+                this.at++;
+                return result;
+            }
+            while (true) {
+                const key = this.string();
+                if (keys.has(key))
+                    invalid();
+                keys.add(key);
+                this.take(':');
+                result[key] = this.value(depth + 1);
+                this.space();
+                const next = this.text[this.at++];
+                if (next === '}')
+                    return result;
+                if (next !== ',')
+                    invalid();
+            }
+        }
+        if (char === '[') {
+            this.at++;
+            const result = [];
+            this.space();
+            if (this.text[this.at] === ']') {
+                this.at++;
+                return result;
+            }
+            while (true) {
+                result.push(this.value(depth + 1));
+                this.space();
+                const next = this.text[this.at++];
+                if (next === ']')
+                    return result;
+                if (next !== ',')
+                    invalid();
+            }
+        }
+        for (const [literal, value] of [['true', true], ['false', false], ['null', null]]) {
+            if (this.text.startsWith(literal, this.at)) {
+                this.at += literal.length;
+                return value;
+            }
+        }
+        const number = /^-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?/.exec(this.text.slice(this.at));
+        if (!number)
+            invalid();
+        this.at += number[0].length;
+        const value = Number(number[0]);
+        if (!Number.isFinite(value))
+            invalid();
+        return value;
+    }
+}
+/** Native operations need names, punctuation and variables, never literals. */
+function lex(query) {
+    const tokens = [];
+    let at = 0;
+    while (at < query.length) {
+        const char = query[at];
+        if (' \t\r\n,'.includes(char)) {
+            at++;
+            continue;
+        }
+        if ('!$():{}'.includes(char)) {
+            tokens.push(char);
+            at++;
+        }
+        else if (/[A-Za-z_]/.test(char)) {
+            const start = at++;
+            while (at < query.length && /[A-Za-z_0-9]/.test(query[at]))
+                at++;
+            tokens.push(query.slice(start, at));
+        }
+        else
+            invalid(); // Includes comments, strings, fragments and directives.
+        if (tokens.length > MAX_NODES)
+            invalid();
+    }
+    return tokens;
+}
+class GraphqlReader {
+    tokens;
+    at = 0;
+    constructor(tokens) {
+        this.tokens = tokens;
+    }
+    peek() { return this.tokens[this.at]; }
+    take(expected) {
+        if (this.tokens[this.at++] !== expected)
+            invalid();
+    }
+    name() {
+        const value = this.tokens[this.at++];
+        if (!value || !/^[A-Za-z_][A-Za-z_0-9]*$/.test(value))
+            invalid();
+        return value;
+    }
+    read() {
+        const kind = this.name();
+        const name = this.name();
+        let inputDefinition = false;
+        if (this.peek() === '(') {
+            // No defaults, alternate types, unused variables or duplicate definitions.
+            for (const token of ['(', '$', 'input', ':', 'TokenizeCreditCardInput', '!', ')'])
+                this.take(token);
+            inputDefinition = true;
+        }
+        const fields = this.selection(0);
+        if (this.at !== this.tokens.length)
+            invalid();
+        return { kind, name, inputDefinition, fields };
+    }
+    selection(depth) {
+        if (depth > MAX_DEPTH)
+            invalid();
+        this.take('{');
+        const fields = [];
+        const names = new Set();
+        while (this.peek() !== '}') {
+            const name = this.name();
+            if (names.has(name))
+                invalid();
+            names.add(name);
+            const args = [];
+            if (this.peek() === '(') {
+                if (depth !== 0)
+                    invalid();
+                this.take('(');
+                const argument = this.name();
+                this.take(':');
+                this.take('$');
+                args.push({ name: argument, variable: this.name() });
+                this.take(')');
+            }
+            const children = this.peek() === '{' ? this.selection(depth + 1) : [];
+            fields.push({ name, arguments: args, fields: children });
+            // Aliases, directives and other punctuation cannot begin the next field.
+        }
+        this.take('}');
+        if (fields.length === 0)
+            invalid();
+        return fields;
+    }
+}
+/** Undefined belongs to another processor; invalid Braintree requests stay blocked. */
+export function classifyBraintreeRequest(url, method, body) {
+    let hostname;
+    try {
+        hostname = new URL(url).hostname;
+    }
+    catch {
+        return undefined;
+    }
+    if (hostname !== 'payments.braintree-api.com' && hostname !== 'payments.sandbox.braintree-api.com')
+        return undefined;
+    if (!braintreeEnvironment(url) || method !== 'POST' || typeof body !== 'string' || body.length === 0 || body.length > MAX_BODY_LENGTH)
+        return 'invalid';
+    try {
+        const envelope = new JsonReader(body).read();
+        if (!record(envelope) || typeof envelope.query !== 'string' || typeof envelope.operationName !== 'string')
+            return 'invalid';
+        if (Object.keys(envelope).some(key => !['query', 'operationName', 'variables', 'clientSdkMetadata'].includes(key)))
+            return 'invalid';
+        if (envelope.clientSdkMetadata !== undefined && !record(envelope.clientSdkMetadata))
+            return 'invalid';
+        const operation = new GraphqlReader(lex(envelope.query)).read();
+        if (operation.name !== envelope.operationName || operation.fields.length !== 1)
+            return 'invalid';
+        const root = operation.fields[0];
+        if (root.fields.length === 0)
+            return 'invalid';
+        const variables = envelope.variables === undefined ? Object.create(null) : envelope.variables;
+        if (!record(variables))
+            return 'invalid';
+        if (operation.kind === 'query' && ['ClientConfiguration', 'ClientConfigurationQuery'].includes(operation.name)
+            && !operation.inputDefinition && root.name === 'clientConfiguration' && root.arguments.length === 0
+            && Object.keys(variables).length === 0)
+            return 'configuration';
+        if (operation.kind !== 'mutation' || operation.name !== 'TokenizeCreditCard' || !operation.inputDefinition
+            || root.name !== 'tokenizeCreditCard' || root.arguments.length !== 1
+            || root.arguments[0].name !== 'input' || root.arguments[0].variable !== 'input'
+            || Object.keys(variables).length !== 1 || !record(variables.input) || !record(variables.input.creditCard))
+            return 'invalid';
+        const card = variables.input.creditCard;
+        if (!['number', 'expirationMonth', 'expirationYear'].every(key => typeof card[key] === 'string' && card[key].trim().length > 0))
+            return 'invalid';
+        if (card.cvv !== undefined && (typeof card.cvv !== 'string' || card.cvv.trim().length === 0))
+            return 'invalid';
+        return 'tokenization';
+    }
+    catch {
+        return 'invalid';
+    }
+}
+/** Preparation accepts guest tokenization only; ordinary interception stays broader. */
+export function isPreparedBraintreeRequest(body) {
+    if (classifyBraintreeRequest(PRODUCTION, 'POST', body) !== 'tokenization')
+        return false;
+    try {
+        const envelope = new JsonReader(body).read();
+        const variables = envelope.variables;
+        const input = variables.input;
+        if (Object.keys(input).some(key => key !== 'creditCard' && key !== 'options'))
+            return false;
+        const card = input.creditCard;
+        if (Object.keys(card).some(key => !['number', 'expirationMonth', 'expirationYear', 'cvv', 'cardholderName', 'billingAddress'].includes(key)))
+            return false;
+        if (Object.entries(card).some(([key, value]) => key !== 'billingAddress' && typeof value !== 'string'))
+            return false;
+        if (card.billingAddress !== undefined) {
+            if (!record(card.billingAddress))
+                return false;
+            const addressKeys = ['postalCode', 'firstName', 'lastName', 'company', 'streetAddress', 'extendedAddress',
+                'locality', 'region', 'countryCodeNumeric', 'countryCodeAlpha2', 'countryCodeAlpha3', 'countryName'];
+            if (Object.entries(card.billingAddress).some(([key, value]) => !addressKeys.includes(key) || typeof value !== 'string'))
+                return false;
+        }
+        // Fingerprint authorization defaults validation on when the option is absent.
+        // Preparation permits only an explicit request for a transient card token.
+        return record(input.options) && Object.keys(input.options).every(key => key === 'validate')
+            && input.options.validate === false;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/cdp.js

@@ -1,6 +1,7 @@
 import { BUILTIN_REGISTRY, cardUrlPatterns } from './registry.js';
 import { ApprovalDeclinedError, ApprovalTimeoutError, CardEncryptedError, CheckoutApiError, PaymentOutcomeUnknownError, ProcessorRefusedError, UnsupportedModeError, redactUrl, } from './client.js';
 import { PreparationGate } from './preparation.js';
+import { classifyBraintreeRequest } from './braintree.js';
 import { substituteEncryptedFields } from './substitute.js';
 import { hostedFormSubmittedPage } from './hosted-form.js';
 import { CheckoutLifecycle, paymentEndpointGuards } from './lifecycle.js';
@@ -413,6 +414,19 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
         if (method !== 'Fetch.requestPaused')
             return;
         const { requestId, request, resourceType, networkId, frameId } = params;
+        // Braintree shares /graphql between configuration and card mutations.
+        // Classify before URL-only recognition or claiming a prepared request.
+        const braintree = request.method.toUpperCase() === 'POST'
+            ? classifyBraintreeRequest(request.url, request.method, pausedBody(request)) : undefined;
+        if (braintree === 'configuration') {
+            await cdp.send('Fetch.continueRequest', { requestId }, sessionId).catch(() => { });
+            return;
+        }
+        if (braintree === 'invalid') {
+            opts.onEvent?.({ type: 'blocked', detail: 'unsupported_braintree_graphql_operation' });
+            await cdp.send('Fetch.failRequest', { requestId, errorReason: 'Aborted' }, sessionId).catch(() => { });
+            return;
+        }
         if (!opts.vault.isCardRequest(request.url, request.method)) {
             if (guards.matches(request.url, request.method)) {
                 preparationGate.invalidate('unsupported_checkout');
@@ -426,7 +440,7 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
         }
         let preparation;
         try {
-            preparation = preparationGate.claim(request.url);
+            preparation = preparationGate.claim(request.url, braintree === 'tokenization' ? pausedBody(request) : undefined);
         }
         catch (error) {
             opts.onEvent?.({ type: 'blocked', detail: failureSummary(error) });
@@ -646,6 +660,14 @@ export async function attachToPlaywright(page, opts) {
     let lastSubmitted = null;
     await page.route((url) => opts.vault.isCardRequest(url.toString()) || guards.matches(url.toString()), async (route) => {
         const request = route.request();
+        const braintree = request.method().toUpperCase() === 'POST'
+            ? classifyBraintreeRequest(request.url(), request.method(), request.postData() ?? '') : undefined;
+        if (braintree === 'configuration')
+            return route.fallback();
+        if (braintree === 'invalid') {
+            opts.onEvent?.({ type: 'blocked', detail: 'unsupported_braintree_graphql_operation' });
+            return route.abort('aborted');
+        }
         // The matcher only sees the URL; a preflight or a GET must pass through
         // untouched or the browser's CORS check fails on our synthetic answer.
         if (!opts.vault.isCardRequest(request.url(), request.method())) {
@@ -659,7 +681,7 @@ export async function attachToPlaywright(page, opts) {
         }
         let preparation;
         try {
-            preparation = preparationGate.claim(request.url());
+            preparation = preparationGate.claim(request.url(), braintree === 'tokenization' ? request.postData() ?? '' : undefined);
         }
         catch (error) {
             opts.onEvent?.({ type: 'blocked', detail: failureSummary(error) });

package/dist/client.d.ts

@@ -1,5 +1,6 @@
 import { type CheckoutMode, type Recognizer } from './registry.js';
 import type { Substitutions } from './substitute.js';
+import { type PreparationProcessor } from './prepared-processor.js';
 export interface PausedRequest {
     url: string;
     method: string;
@@ -99,7 +100,7 @@ export interface HostedFormReplay {
 /** What authorize() resolves with; branch on `mode` (absent means token). */
 export type ReplayResponse = TokenReplay | CseReplay | HostedFormReplay;
 export interface PrepareCheckoutOptions {
-    psp: 'square';
+    psp: PreparationProcessor;
     /** The processor environment, independent of your Agentcard client's mode. */
     environment: 'production' | 'sandbox';
     signal?: AbortSignal;
@@ -120,7 +121,7 @@ export interface PrepareCheckoutInput extends PrepareCheckoutOptions {
 export interface PreparedCheckout {
     readonly id: string;
     readonly status: 'ready';
-    readonly psp: 'square';
+    readonly psp: PreparationProcessor;
     readonly environment: 'production' | 'sandbox';
     readonly expiresAt: string;
     readonly cardId: string;

package/dist/client.js

@@ -1,4 +1,5 @@
 import { BUILTIN_REGISTRY, cardUrlPatterns as deriveCardUrlPatterns, findRecognizer, } from './registry.js';
+import { matchesPreparedRequest } from './prepared-processor.js';
 /**
  * The modes this SDK can finish. Asked for on syncRegistry (the API serves
  * only recognizers in these modes, so a request this build cannot complete
@@ -314,7 +315,7 @@ export class VaultClient {
     async prepareCheckout(input) {
         input = { ...input };
         const fail = (reason, id = null) => new CheckoutPreparationError(id, reason);
-        if (input.psp !== 'square' || !['production', 'sandbox'].includes(input.environment))
+        if (!['square', 'braintree'].includes(input.psp) || !['production', 'sandbox'].includes(input.environment))
             throw fail('unsupported_processor');
         if (!Number.isSafeInteger(input.amountCents) || input.amountCents <= 0 || typeof input.currency !== 'string' || !/^[a-z]{3}$/i.test(input.currency))
             throw fail('amount_required');
@@ -367,7 +368,7 @@ export class VaultClient {
                         || state.payment_status !== 'not_started' || state.amount_authority !== 'display_only'
                         || state.user !== input.user || state.merchant !== input.merchant || state.merchant_origin !== input.merchantOrigin
                         || state.amount_cents !== input.amountCents || state.currency !== input.currency.toLowerCase()
-                        || state.psp !== 'square' || state.mode !== 'token' || state.environment !== input.environment
+                        || state.psp !== input.psp || state.mode !== 'token' || state.environment !== input.environment
                         || state.checkout_key !== input.checkoutKey)
                         throw fail('ready_unconfirmed', id);
                     const prepared = Object.freeze({
@@ -416,13 +417,11 @@ export class VaultClient {
                 throw new CheckoutPreparationError(preparation.id ?? null, 'already_used_or_foreign');
             // Consume locally before any await, including OAuth, and never recycle it.
             this.usedPreparations.add(preparation);
-            const url = new URL(input.request.url);
-            const host = preparation.environment === 'production' ? 'pci-connect.squareup.com' : 'pci-connect.squareupsandbox.com';
             if (Date.parse(preparation.expiresAt) <= Date.now())
                 throw new CheckoutPreparationError(preparation.id, 'expired');
             if (input.user !== preparation.user || input.merchant !== preparation.merchant || input.amountCents !== preparation.amountCents
                 || input.currency?.toLowerCase() !== preparation.currency || input.cardId !== preparation.cardId
-                || url.origin !== `https://${host}` || url.pathname !== '/v2/card-nonce' || url.username || url.password)
+                || !matchesPreparedRequest(preparation.psp, preparation.environment, input.request.url, input.request.method ?? 'POST', input.request.body))
                 throw new CheckoutPreparationError(preparation.id, 'checkout_changed');
         }
         if (input.signal?.aborted)
@@ -437,6 +436,8 @@ export class VaultClient {
         // clientSideEncrypted entry (an older registry, a hand-built one) still
         // refuses here, exactly as before.
         const mode = rec.mode ?? 'token';
+        if (preparation && (rec.psp !== preparation.psp || mode !== 'token'))
+            throw new CheckoutPreparationError(preparation.id, 'checkout_changed');
         if (rec.clientSideEncrypted && mode !== 'cse')
             throw new CardEncryptedError(rec.psp);
         if (!SUPPORTED_MODES.includes(mode))

package/dist/preparation.d.ts

@@ -15,7 +15,7 @@ export declare class PreparationGate {
     constructor(opts: AttachOptions, lifecycle: CheckoutLifecycle, readDocumentUrl: () => Promise<string>);
     private prepare;
     /** Called for every recognized card mutation, before any await or local retry guard. */
-    claim(requestUrl: string): PreparedCheckout | undefined;
+    claim(requestUrl: string, requestBody?: string | null): PreparedCheckout | undefined;
     assertDocument(): Promise<void>;
     private readDocument;
     isEngaged(): boolean;

package/dist/preparation.js

@@ -1,4 +1,5 @@
 import { CheckoutPreparationError } from './client.js';
+import { matchesPreparedRequest, preparationEndpoint } from './prepared-processor.js';
 /** A local, one-use rendezvous. It never starts or retries a merchant request. */
 export class PreparationGate {
     opts;
@@ -33,9 +34,9 @@ export class PreparationGate {
         const onAbort = () => this.invalidate('cancelled');
         signal.addEventListener('abort', onAbort, { once: true });
         try {
-            if (!options || options.psp !== 'square' || !['production', 'sandbox'].includes(options.environment))
+            if (!options || !['square', 'braintree'].includes(options.psp) || !['production', 'sandbox'].includes(options.environment))
                 throw new CheckoutPreparationError(null, 'unsupported_processor');
-            const tokenizer = options.environment === 'production' ? 'https://pci-connect.squareup.com/v2/card-nonce' : 'https://pci-connect.squareupsandbox.com/v2/card-nonce';
+            const tokenizer = preparationEndpoint(options.psp, options.environment);
             if (!this.opts.vault.isCardRequest(tokenizer, 'POST'))
                 throw new CheckoutPreparationError(null, 'processor_interception_unavailable');
             if (!Number.isSafeInteger(this.opts.amountCents) || (this.opts.amountCents ?? 0) <= 0 || !/^[a-z]{3}$/i.test(this.opts.currency ?? ''))
@@ -62,6 +63,8 @@ export class PreparationGate {
                 },
             });
             this.prepared = prepared;
+            if (prepared.psp !== options.psp || prepared.environment !== options.environment)
+                throw new CheckoutPreparationError(prepared.id, 'checkout_changed');
             if (signal.aborted || this.state !== 'preparing') {
                 void this.opts.vault.cancelPreparation(prepared.id).catch(() => { });
                 throw new CheckoutPreparationError(prepared.id, 'cancelled');
@@ -86,7 +89,7 @@ export class PreparationGate {
         // Keep the signal listener after ready: caller cancellation retires the handle too.
     }
     /** Called for every recognized card mutation, before any await or local retry guard. */
-    claim(requestUrl) {
+    claim(requestUrl, requestBody) {
         this.observedRequest = true;
         if (this.state === 'unused')
             return undefined;
@@ -95,9 +98,7 @@ export class PreparationGate {
             throw new CheckoutPreparationError(this.prepared?.id ?? null, 'already_used_or_unavailable');
         }
         const prepared = this.prepared;
-        const request = new URL(requestUrl);
-        const origin = prepared.environment === 'production' ? 'https://pci-connect.squareup.com' : 'https://pci-connect.squareupsandbox.com';
-        if (Date.parse(prepared.expiresAt) <= Date.now() || request.origin !== origin || request.pathname !== '/v2/card-nonce' || request.username || request.password) {
+        if (Date.parse(prepared.expiresAt) <= Date.now() || !matchesPreparedRequest(prepared.psp, prepared.environment, requestUrl, 'POST', requestBody)) {
             const reason = Date.parse(prepared.expiresAt) <= Date.now() ? 'expired' : 'checkout_changed';
             this.invalidate(reason);
             throw new CheckoutPreparationError(prepared.id, reason);

package/dist/prepared-processor.d.ts

@@ -0,0 +1,5 @@
+export type PreparationProcessor = 'square' | 'braintree';
+export type PreparationEnvironment = 'production' | 'sandbox';
+export declare function preparationEndpoint(psp: PreparationProcessor, environment: PreparationEnvironment): string;
+/** Processor identity and environment are part of the device's prior consent. */
+export declare function matchesPreparedRequest(psp: PreparationProcessor, environment: PreparationEnvironment, requestUrl: string, method: string, body?: string | null): boolean;

package/dist/prepared-processor.js

@@ -0,0 +1,25 @@
+import { braintreeEnvironment, isPreparedBraintreeRequest } from './braintree.js';
+export function preparationEndpoint(psp, environment) {
+    if (psp === 'braintree')
+        return environment === 'production'
+            ? 'https://payments.braintree-api.com/graphql' : 'https://payments.sandbox.braintree-api.com/graphql';
+    return environment === 'production'
+        ? 'https://pci-connect.squareup.com/v2/card-nonce' : 'https://pci-connect.squareupsandbox.com/v2/card-nonce';
+}
+/** Processor identity and environment are part of the device's prior consent. */
+export function matchesPreparedRequest(psp, environment, requestUrl, method, body) {
+    if (method.toUpperCase() !== 'POST')
+        return false;
+    if (psp === 'braintree') {
+        return braintreeEnvironment(requestUrl) === environment && isPreparedBraintreeRequest(body ?? null);
+    }
+    if (psp !== 'square')
+        return false;
+    try {
+        const request = new URL(requestUrl), endpoint = new URL(preparationEndpoint(psp, environment));
+        return request.origin === endpoint.origin && request.pathname === endpoint.pathname && !request.username && !request.password;
+    }
+    catch {
+        return false;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-cards/checkout",
-  "version": "0.4.1",
+  "version": "0.5.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",
@@ -23,7 +23,7 @@
     "_comment_build": "TypeScript is fetched rather than declared as a devDependency ON PURPOSE. This package ships zero dependencies, which is why pnpm writes no importer for it in the workspace lockfile; adding any dep here creates one, and an importer the lockfile has not been regenerated for fails every Vercel build with ERR_PNPM_OUTDATED_LOCKFILE. Pinned so the published output is reproducible.",
     "build": "npx -y -p typescript@5.9.3 tsc",
     "prepublishOnly": "pnpm build",
-    "test": "node test.mjs && node --test lifecycle.test.mjs merchant-abort.test.mjs preparation.test.mjs",
+    "test": "node test.mjs && node --test lifecycle.test.mjs merchant-abort.test.mjs preparation.test.mjs braintree.test.mjs minimum-delay.test.mjs",
     "test:browser": "node browser.test.mjs && node stripe-browser.test.mjs && node preparation-browser.test.mjs"
   },
   "keywords": [