@agent-cards/checkout 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # 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.
+- Hold further card requests within the attachment after a processor refusal, including when the merchant retries after the approval cooldown. Reconcile the merchant payment; only an explicit `retryAfterMerchantFailure({ status: 'failed' })` releases this hold and permits an immediate new attempt. This also applies to clear card declines. Ordinary user declines keep their approval cooldown. Do not automatically replace the attachment to bypass reconciliation.
+- Add deterministic refusal, diagnostic sanitization and retry-guard regressions. These tests do not establish a successful Razorpay purchase or processor capture.
+
 ## 0.4.0
 
 - Add `controller.prepare({ psp: 'square', environment: 'production' | 'sandbox' })` to both browser adapters. The caller awaits cardholder consent and unlock before starting its first native Pay action. This requires the matching preparation API and Vault deployment.

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 |
@@ -248,11 +248,19 @@ one. `amountAuthority` on every replay is `stripe_payment_intent`,
   refused to replay a confirm at it. An `ApprovalDeclinedError` with
   `code: 'intent_not_confirmable'`. Deliberately not "nothing was charged":
   check the intent at Stripe before retrying.
-- `ProcessorRefusedError`: the cardholder's device sent the card and the
-  processor refused it outright (`pspErrorCode` is the processor's own code,
-  such as Stripe's `card_declined`). Nothing was charged. An
-  `ApprovalDeclinedError` with `code: 'processor_refused'`; the page's next
-  attempt raises a fresh approval where the person can pick another card.
+- `ProcessorRefusedError`: the cardholder's device reported a processor
+  request rejection. `pspErrorCode` carries the processor's code; optional
+  `processorError` carries bounded Razorpay reason, source, step and payment/order
+  identifiers when the API has them. A generic code such as `BAD_REQUEST_ERROR`
+  does not establish an issuer decline or prove no money moved. Reconcile the
+  merchant payment before retrying. This remains an `ApprovalDeclinedError`
+  with `code: 'processor_refused'` for compatibility.
+  The attachment records `status: 'declined', reason: 'processor_refused'`
+  and holds further card requests. After confirming merchant failure, call
+  `retryAfterMerchantFailure({ status: 'failed' })` to permit a deliberate new
+  attempt immediately, without waiting for the user-decline cooldown. Do not
+  automatically create a new attachment after this error;
+  the guard applies only within the existing attachment.
 - `CheckoutApiError` with `code === 'amount_unverifiable'`: Stripe could not
   be asked (502; the SDK retries twice, 500ms then 1500ms, before throwing)
   or the paused request lacked its client secret or publishable key (400).
@@ -392,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, {
@@ -401,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, UnsupportedModeError, redactUrl, } from './client.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';
@@ -80,6 +81,11 @@ const APPROVAL_COOLDOWN_MS = 5_000;
  * quiet window absorbs the burst; the next request past it is judged afresh.
  */
 function isApprovalOutcome(err) {
+    // Processor refusals are held by the lifecycle until explicit merchant
+    // reconciliation and retry. A second timer would outlive that release and
+    // reject the application's deliberate retry even after confirmed failure.
+    if (err instanceof ProcessorRefusedError)
+        return false;
     if (err instanceof CheckoutApiError)
         return err.code === 'duplicate_submission';
     return err instanceof ApprovalDeclinedError || err instanceof ApprovalTimeoutError;
@@ -98,7 +104,9 @@ function isApprovalOutcome(err) {
  * a misconfiguration or an unsupported PSP. Nothing a person does changes
  * those, so asking again is pure waste.
  *
- * Everything else stays retryable. A 5xx or a 429 clears on its own, and a
+ * Other errors may be retryable unless the lifecycle holds the attachment
+ * for merchant reconciliation, as it does after a processor refusal.
+ * A 5xx or a 429 clears on its own, and a
  * decline or a timeout is answered by the cooldown above rather than by
  * killing the page: the person said no to one authorization, not to every
  * checkout they will ever make in this session. A 409 duplicate_submission
@@ -406,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');
@@ -419,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) });
@@ -639,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())) {
@@ -652,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;
@@ -271,20 +272,27 @@ export declare class IntentNotConfirmableError extends ApprovalDeclinedError {
     readonly code: "intent_not_confirmable";
     constructor(authorizationId: string);
 }
+/** Bounded processor identifiers, never a raw response or free-form description. */
+export interface RazorpayProcessorError {
+    reason?: string;
+    source?: string;
+    step?: string;
+    payment_id?: string;
+    order_id?: string;
+}
 /**
- * The cardholder's device sent the card and the processor refused it
- * outright (a card decline, a bad CVC, an invalid request). Nothing was
- * charged; the authorization is `declined` with reason `processor_refused`
- * and the processor's own code in `pspErrorCode` (Stripe's `card_declined`,
- * `incorrect_cvc`, …). A decline like any other for the adapters: the paused
- * request is aborted and the page's retry gets a fresh approval, where the
- * person can pick another card.
+ * The device reported a processor request rejection. A generic processor
+ * code does not establish an issuer decline or prove no money moved. Read
+ * the bounded processor evidence and reconcile the merchant before retrying.
+ * The authorization remains `declined` with reason `processor_refused` for
+ * compatibility; no successful processor response is handed to the merchant.
  */
 export declare class ProcessorRefusedError extends ApprovalDeclinedError {
     authorizationId: string;
     pspErrorCode: string | null;
     readonly code: "processor_refused";
-    constructor(authorizationId: string, pspErrorCode: string | null);
+    readonly processorError: RazorpayProcessorError | null;
+    constructor(authorizationId: string, pspErrorCode: string | null, processorError?: RazorpayProcessorError | null);
 }
 /**
  * A non-2xx from the Agentcard API, carrying the status so callers can tell a

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
@@ -128,25 +129,49 @@ export class IntentNotConfirmableError extends ApprovalDeclinedError {
             + 'it cannot be confirmed again. Check the intent at Stripe before retrying.';
     }
 }
+function parseProcessorError(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    const fields = value;
+    const result = {};
+    const exact = (pattern, field) => pattern.exec(field)?.[0] === field;
+    for (const [key, field] of Object.entries(fields)) {
+        if (typeof field !== 'string')
+            return null;
+        if (key === 'reason' || key === 'source' || key === 'step') {
+            if (!exact(/^[a-z][a-z_]{0,63}$/, field))
+                return null;
+            result[key] = field;
+        }
+        else if (key === 'payment_id' || key === 'order_id') {
+            if (!exact(key === 'payment_id' ? /^pay_[A-Za-z0-9]{1,128}$/ : /^order_[A-Za-z0-9]{1,128}$/, field))
+                return null;
+            result[key] = field;
+        }
+        else
+            return null;
+    }
+    return Object.keys(result).length ? result : null;
+}
 /**
- * The cardholder's device sent the card and the processor refused it
- * outright (a card decline, a bad CVC, an invalid request). Nothing was
- * charged; the authorization is `declined` with reason `processor_refused`
- * and the processor's own code in `pspErrorCode` (Stripe's `card_declined`,
- * `incorrect_cvc`, …). A decline like any other for the adapters: the paused
- * request is aborted and the page's retry gets a fresh approval, where the
- * person can pick another card.
+ * The device reported a processor request rejection. A generic processor
+ * code does not establish an issuer decline or prove no money moved. Read
+ * the bounded processor evidence and reconcile the merchant before retrying.
+ * The authorization remains `declined` with reason `processor_refused` for
+ * compatibility; no successful processor response is handed to the merchant.
  */
 export class ProcessorRefusedError extends ApprovalDeclinedError {
     authorizationId;
     pspErrorCode;
     code = 'processor_refused';
-    constructor(authorizationId, pspErrorCode) {
+    processorError;
+    constructor(authorizationId, pspErrorCode, processorError = null) {
         super('processor_refused');
         this.authorizationId = authorizationId;
         this.pspErrorCode = pspErrorCode;
         this.name = 'ProcessorRefusedError';
-        this.message = `the processor refused the card on ${authorizationId}${pspErrorCode ? ` (${pspErrorCode})` : ''}. Nothing was charged.`;
+        this.processorError = parseProcessorError(processorError);
+        this.message = `the processor rejected the payment request on ${authorizationId}${pspErrorCode ? ` (${pspErrorCode})` : ''}. Check the merchant payment status before retrying.`;
     }
 }
 /**
@@ -290,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');
@@ -343,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({
@@ -392,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)
@@ -413,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))
@@ -611,7 +636,7 @@ export class VaultClient {
                     if (s.reason === 'intent_not_confirmable')
                         throw new IntentNotConfirmableError(String(created.id));
                     if (s.reason === 'processor_refused') {
-                        throw new ProcessorRefusedError(String(created.id), typeof s.psp_error_code === 'string' ? s.psp_error_code : null);
+                        throw new ProcessorRefusedError(String(created.id), typeof s.psp_error_code === 'string' ? s.psp_error_code : null, s.psp === 'razorpay' ? parseProcessorError(s.processor_error) : null);
                     }
                     throw new ApprovalDeclinedError(s.reason ?? 'no reason given');
                 }

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { VaultClient, CardEncryptedError, UnsupportedModeError, ApprovalTimeoutError, ApprovalDeclinedError, AmountMismatchError, IntentNotConfirmableError, ProcessorRefusedError, CheckoutApiError, redactUrl, SUPPORTED_MODES, PaymentOutcomeUnknownError, CheckoutCancelledError, CheckoutPreparationError, } from './client.js';
-export type { PausedRequest, ReplayResponse, TokenReplay, CseReplay, HostedFormReplay, AmountAuthority, AuthorizeInput, VaultClientOptions, PrepareCheckoutOptions, PrepareCheckoutInput, PreparedCheckout, } from './client.js';
+export type { PausedRequest, ReplayResponse, TokenReplay, CseReplay, HostedFormReplay, AmountAuthority, AuthorizeInput, VaultClientOptions, PrepareCheckoutOptions, PrepareCheckoutInput, PreparedCheckout, RazorpayProcessorError, } from './client.js';
 export { attachToCdp, attachToPlaywright, corsHeadersFor, corsDecision, withCorsHeaders } from './cdp.js';
 export type { CdpLike, AttachOptions, CorsOutcome } from './cdp.js';
 export { substituteEncryptedFields, SubstitutionError } from './substitute.js';

package/dist/lifecycle.js

@@ -1,4 +1,4 @@
-import { ApprovalDeclinedError, ApprovalTimeoutError, CheckoutCancelledError, CheckoutPreparationError, IntentNotConfirmableError, PaymentOutcomeUnknownError } from './client.js';
+import { ApprovalDeclinedError, ApprovalTimeoutError, CheckoutCancelledError, CheckoutPreparationError, IntentNotConfirmableError, PaymentOutcomeUnknownError, ProcessorRefusedError } from './client.js';
 /** Shared by the raw CDP and Playwright transports. No browser ownership or payment execution lives here. */
 export class CheckoutLifecycle {
     options;
@@ -115,7 +115,7 @@ export class CheckoutLifecycle {
             this.merchantRequestAborted();
             return;
         }
-        const authorizationId = error instanceof PaymentOutcomeUnknownError ? error.authorizationId : this.state.authorizationId;
+        const authorizationId = error instanceof PaymentOutcomeUnknownError || error instanceof ProcessorRefusedError ? error.authorizationId : this.state.authorizationId;
         if (handoffStarted || error instanceof PaymentOutcomeUnknownError || error instanceof IntentNotConfirmableError) {
             this.held = true;
             this.set({ ...this.state, authorizationId, status: 'outcome_unknown', reason: error instanceof PaymentOutcomeUnknownError ? error.reason : error instanceof IntentNotConfirmableError ? 'intent_not_confirmable' : 'browser_handoff_failed' });
@@ -129,6 +129,13 @@ export class CheckoutLifecycle {
         else if (error instanceof ApprovalTimeoutError) {
             this.set({ ...this.state, status: 'timed_out', reason: 'approval_expired' });
         }
+        else if (error instanceof ProcessorRefusedError) {
+            // A rejected processor request is not proof that the merchant cannot
+            // collect this payment. Keep native retries held until the application
+            // checks the merchant and explicitly starts another attempt.
+            this.held = true;
+            this.set({ ...this.state, authorizationId, status: 'declined', reason: 'processor_refused' });
+        }
         else if (error instanceof ApprovalDeclinedError) {
             this.set({ ...this.state, status: 'declined', reason: 'approval_declined' });
         }

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.0",
+  "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": [