@agent-cards/checkout 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## Unreleased
+
+- A company can put rules on the Vault purchases it chooses (a merchant list, a currency, a spend cap, a time window) by attaching a named preset to a stored card. A purchase the rules refuse now surfaces as `PresetRefusedError`, a typed decline: at stage `create` no authorization exists and nobody was asked; at stage `pre_replay` the authorization is `declined` with the rule's reason. It carries `code`, `presetName`, `rule`, `preset`, `attachment` (the card with its last four digits) and the rule's own statement; when several presets refuse the same purchase, `refusals` names every one and the other fields are the first. The adapters quiet the page's retry as for any decline, and a create-time refusal is never treated as a permanent misconfiguration.
+- Requires the matching API and Vault release.
+
+## 0.6.0
+
+- Recognize Paysafe Checkout 1.8's exact hosted tokenization endpoints and preserve its native credential and correlation headers. The matching API registry and Vault deployment are required.
+- Recognize Checkout.com card tokenization at `card-acquisition-gateway.checkout.com/tokens` and its sandbox counterpart alongside the existing API hosts. The matching backend registry and Vault deployment are required; this entry does not establish native merchant payment completion.
+- Prepare Worldpay, Bambora and Mercado Pago checkout before the merchant's first Pay action. Use `psp: 'worldpay'` with `environment: 'production' | 'sandbox'`, or `psp: 'bambora' | 'mercado_pago'` with `environment: 'shared'`. Shared endpoints do not establish processor test mode. The merchant's credentials and checkout configuration determine that mode.
+- Keep the existing selected-card, merchant, document, amount, currency and one-use consent checks. The native request begins only after approval, and approval readiness lasts at most 30 seconds. The SDK does not extend processor deadlines or automatically retry after payment uncertainty. Matching API, Vault and preparation migration are required.
+- Bound Playwright and CDP setup with `attachmentTimeoutMs`, defaulting to 30 seconds. A stalled setup throws a sanitized `CheckoutAttachmentError`; late acknowledgements cannot start approval or retry setup, and concurrent setup failures report once. Close the failed checkout page and start a fresh context before trying again.
+- Preserve the original setup failure across attached frames: a transport failure reports `unavailable`, a deadline reports `timeout`, and an observed page closure reports `closed`.
+- Reject processor URLs with credentials or nondefault ports consistently across SDK and API discovery. Registry synchronization updates endpoint recognition; upgrading the SDK is required for the new preparation and setup behavior.
+
+The matching Vault/API release adds Mollie card-token and supported Airwallex intent-confirmation replay through browser-owned TLS, preserves Worldpay's native session media type and Bambora's `cvd` field, and reports Nuvei's unambiguous validation error as processor refusal. Local regression and Chromium fixture results do not establish native processor acceptance or a completed merchant purchase.
+
 ## 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.

package/README.md

@@ -54,30 +54,28 @@ await attachToCdp(cdp, pageSessionId, {
   vault,
   user: 'usr_123',                 // whose card should pay
   merchant: 'vanman.shop',
-  amountCents: 583,                // what the user approves, smallest currency unit
+  amount: 583,                     // your hint, an integer in the currency's smallest unit (or a decimal string: '5.83')
   currency: 'usd',                 // "$5.83" is derived for the approval screen
   onApprovalUrl: (url) => sendToUser(url),   // iMessage, SMS, push, your call
 });
 ```
 
-`amount: '$5.83'` (a display string) still works on its own. Pass
-`amountCents` + `currency` when you want the amount enforced: on a Stripe
-PaymentIntent confirm, Agentcard reads the intent back from Stripe at create
-and again right before the cardholder's device replays, a different amount is
-refused with nothing charged, and after the replay the charge is reconciled
-against the approval (`ReplayResponse.amountVerified`, with
-`chargedAmountCents` and `chargedKind`: `captured` for a succeeded intent's
-`amount_received`, `authorized` for a manual-capture intent's
-`amount_capturable`, `none` when nothing is collected yet; plus the
-`checkout_authorization.amount_mismatch` webhook to your server when it
-disagrees). Amounts are Stripe minor units up to 2^53-1. `onEvent` payloads
-name URLs by origin and path only, so a client secret in a paused request's
-query string never reaches your telemetry. When you pass the pair, any
-`amount` string you also pass is
-ignored: Agentcard derives the display string from the number, following
-Stripe's minor units, so the approval screen, the notifications and every
-read show one amount. Tokenization requests carry no amount, so there the
-pair is shown and reported (`amountAuthority: 'display_only'`), not enforced.
+`amount` is your hint: an integer in the currency's smallest unit (583 for
+$5.83), or a decimal string in normal units ('5.83'), with `currency`. The
+processor's own amount is the higher authority: Agentcard reads it from the
+paused request where the processor puts it there, or from the Stripe intent
+the request names, right before the cardholder's device replays, and the
+company's caps are judged on it. A hint lets a bad purchase be refused the
+moment it opens; a hint more than one smallest unit away from the processor's
+amount is refused with nothing charged (`AmountMismatchError`), and after the
+replay the charge is reconciled against the approval
+(`ReplayResponse.amountVerified`, `chargedAmount`, and `chargedKind`:
+`captured` for a succeeded intent's `amount_received`, `authorized` for a
+manual-capture intent's `amount_capturable`, `none` when nothing is collected
+yet; plus the `checkout_authorization.amount_mismatch` webhook to your server
+when the charge disagreed). Every result carries `amountAuthority`:
+`processor`, `agent`, `page`, or `none`. A display string is never sent;
+Agentcard derives it.
 
 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
@@ -129,8 +127,8 @@ Coverage is specific to the processor request format, merchant setup, browser tr
 | Processor | Status |
 |---|---|
 | 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 card tokenization | prepared checkout supported; production paid-order validation pending |
+| Stripe | tokenization replay and direct card-bearing PaymentIntent confirms are implemented; direct confirms read the intent's amount back from Stripe; a hint sent as `amount` + `currency` must agree with it. Browser token-to-intent continuation is unsupported and held. Validate the exact merchant flow before pilot use |
+| Braintree card tokenization | Prepared checkout supported; one live Haymarket Books ebook purchase with SDK `0.5.0` confirmed merchant fulfillment and SDK `completed` using a merchant receipt resolver. Independent processor capture/settlement, live 3DS and PayPal wallet flows remain unverified. |
 | 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 |
@@ -327,6 +325,16 @@ Playwright `CDPSession` is not the `CdpLike` interface. Raw CDP must preserve th
 Initial arming errors reject `attachToCdp`; a child that cannot be armed remains
 paused and reports `browser_interception_unavailable` for operator recovery.
 
+Await attachment before clicking Pay. Both adapters stop waiting for browser
+setup after 30 seconds and throw `CheckoutAttachmentError` with
+`code: 'checkout_attachment_failed'` and `reason: 'timeout'`, `'closed'` or
+`'unavailable'`. Use `attachmentTimeoutMs` to choose a setup deadline from 1 to
+300000 milliseconds, separately from the approval's `timeoutMs`.
+Close the failed checkout page and create a fresh browser context before
+trying again. A late setup response cannot reopen the failed attachment or
+request approval; intercepted card requests remain blocked. A setup failure
+does not establish the status of any earlier purchase.
+
 Use a checkout context created with `serviceWorkers: 'block'`. Playwright cannot
 route requests intercepted by a service worker. The SDK rejects already active
 service workers, but that check cannot prevent a site from registering one
@@ -342,7 +350,7 @@ value continues to work. Choose `requireMerchantResult: true` for a pilot:
 
 ```ts
 const checkout = await attachToPlaywright(page, {
-  vault, user, merchant, amountCents, currency,
+  vault, user, merchant, amount, currency,
   requireMerchantResult: true,
   onStateChange: state => recordState(state),
   onUserAction: action => deliverPrivatelyToUser(action),
@@ -385,7 +393,7 @@ Unrecognized merchant-server endpoints remain outside this guard unless listed
 in `paymentEndpoints`; this is not a guarantee against a merchant charging a
 saved token on its own server.
 A direct card-bearing PaymentIntent confirm remains supported with the backend's
-existing amount verification when `amountCents` and `currency` are supplied.
+existing amount verification when `amount` and `currency` are supplied.
 
 Hosted-form submissions also always stay blocked because their payment outcome
 is unverified. `reconcile()` calls the resolver once, coalescing concurrent calls.
@@ -400,24 +408,36 @@ 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.
 
-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:
+Worldpay, Bambora and Mercado Pago preparation requires SDK 0.6.0 or later and the matching API and Vault release.
+
+Prepare a Square, Braintree, Worldpay, Bambora or Mercado Pago 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, {
   vault, user: 'your-user-id', merchant: 'Example merchant',
-  amountCents: 100, currency: 'USD',
+  amount: 100, currency: 'USD',
   onApprovalUrl: deliverPrivatelyToCardholder,
 });
 const preparation = await checkout.prepare({
-  psp: 'braintree', // use 'square' for Square
-  environment: 'production', // explicit; use 'sandbox' for the processor's sandbox
+  psp: 'braintree',
+  environment: 'production', // Square, Braintree and Worldpay: production or 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, processor and environment bind one fresh request. The amount remains `display_only`; a card token does not enforce the merchant's eventual charge amount.
+`prepare()` is available on both Playwright and raw CDP controllers. It requires `amount` 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's authority is `agent`; a card token does not enforce the merchant's eventual charge amount.
+
+| Processor | `environment` | Fresh native request |
+| --- | --- | --- |
+| Square | `production` or `sandbox` | Matching Square `/v2/card-nonce` host |
+| Braintree | `production` or `sandbox` | Matching Braintree GraphQL host and guest `TokenizeCreditCard` mutation |
+| Worldpay | `production` or `sandbox` | Matching Access Worldpay host and `/sessions/card` |
+| Bambora | `shared` | `/scripts/tokenization/tokens` on `api.bam.shift4api.net` or `api.na.bambora.com` |
+| Mercado Pago | `shared` | `api.mercadopago.com/v1/card_tokens` with a fresh card body |
+
+Use `environment: 'shared'` for Bambora and Mercado Pago because the same endpoint serves test and live requests. Agentcard cannot establish the processor's test mode from that URL or a credential prefix. Configure test mode through the merchant's processor account when testing. Agentcard's own `sandbox` flag remains separate. Prepared Worldpay, Bambora and Mercado Pago requests reject saved-card and recurring request bodies; a refused request retires the local preparation. Reconcile any existing merchant attempt before creating a new attachment.
 
 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.
 
@@ -472,9 +492,7 @@ The browser fixtures never contact a payment service. The general suite uses
 allowlisted loopback proxy and a temporary self-signed TLS stub (requires the
 `openssl` CLI). All other proxy destinations are rejected. These suites use an
 in-process Agentcard API fixture and loopback merchant pages. The preparation
-fixture denies all external traffic, waits more than ten seconds before any
-card request, and then checks one fresh request with an unchanged ten-second
-fixture abort timer. It exercises SDK ordering, not the native Square SDK. It proves nested-frame pause/resume, agent control during approval,
+fixture denies all external traffic and waits beyond each modeled request deadline before any card request: eleven seconds for Square, sixty-one seconds for Braintree, and six and a half seconds for Worldpay, Bambora and Mercado Pago. Each fixture then checks one fresh request with an unchanged abort timer. The five-second timer matches the inspected Worldpay and Bambora source; the Mercado Pago timer is a test boundary, not a measured native deadline. The fixture exercises SDK ordering with native-shaped request bodies and synthetic responses, not processor acceptance. It proves nested-frame pause/resume, agent control during approval,
 post-payment tasks in the same page, decline/expiry/cancel, unknown-outcome retry
 blocking, explicit unsupported endpoint behavior, and blocking an immediate real-browser
 Stripe token-to-intent fetch chain, including unrelated first intents, changed

package/dist/attachment.d.ts

@@ -0,0 +1,11 @@
+/** An attachment failure has no payment or browser credentials in its message. */
+export declare class CheckoutAttachmentError extends Error {
+    readonly reason: 'timeout' | 'closed' | 'unavailable';
+    readonly code = "checkout_attachment_failed";
+    constructor(reason: 'timeout' | 'closed' | 'unavailable');
+}
+/** Preserve a known setup cause without exposing raw transport errors. */
+export declare function attachmentFailure(error: unknown): CheckoutAttachmentError;
+export declare function attachmentDeadline(value: number | undefined): number;
+/** Stop waiting, then reject every late continuation before its next command. */
+export declare function withinAttachmentDeadline(arm: (assertActive: () => void) => Promise<void>, timeoutMs: number, signal: AbortSignal): Promise<void>;

package/dist/attachment.js

@@ -0,0 +1,50 @@
+/** An attachment failure has no payment or browser credentials in its message. */
+export class CheckoutAttachmentError extends Error {
+    reason;
+    code = 'checkout_attachment_failed';
+    constructor(reason) {
+        super('Could not attach checkout interception. Close this checkout page and retry in a fresh browser context.');
+        this.reason = reason;
+        this.name = 'CheckoutAttachmentError';
+    }
+}
+/** Preserve a known setup cause without exposing raw transport errors. */
+export function attachmentFailure(error) {
+    return error instanceof CheckoutAttachmentError ? error : new CheckoutAttachmentError('unavailable');
+}
+export function attachmentDeadline(value) {
+    if (value === undefined)
+        return 30_000;
+    if (!Number.isSafeInteger(value) || value <= 0 || value > 300_000) {
+        throw new Error('attachmentTimeoutMs must be an integer between 1 and 300000.');
+    }
+    return value;
+}
+/** Stop waiting, then reject every late continuation before its next command. */
+export async function withinAttachmentDeadline(arm, timeoutMs, signal) {
+    let stopped;
+    let timer;
+    let onAbort = () => { };
+    const assertActive = () => { if (stopped)
+        throw stopped; };
+    const deadline = new Promise((_resolve, reject) => {
+        const stop = (failure) => { stopped ??= failure; reject(stopped); };
+        onAbort = () => stop(attachmentFailure(signal.reason));
+        signal.addEventListener('abort', onAbort, { once: true });
+        if (signal.aborted)
+            onAbort();
+        else
+            timer = setTimeout(() => stop(new CheckoutAttachmentError('timeout')), timeoutMs);
+    });
+    try {
+        await Promise.race([deadline, Promise.resolve().then(() => { assertActive(); return arm(assertActive); })]);
+    }
+    catch (error) {
+        stopped ??= attachmentFailure(error);
+        throw stopped;
+    }
+    finally {
+        clearTimeout(timer);
+        signal.removeEventListener('abort', onAbort);
+    }
+}

package/dist/braintree.d.ts

@@ -2,6 +2,8 @@
 export type BraintreeEnvironment = 'production' | 'sandbox';
 export type BraintreeRequestKind = 'configuration' | 'tokenization' | 'invalid';
 export declare function braintreeEnvironment(url: string): BraintreeEnvironment | undefined;
+/** Bounded duplicate-aware JSON for fresh-card preparation bodies. */
+export declare function readTokenizationJson(body: string | null): Record<string, unknown> | null;
 /** 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. */

package/dist/braintree.js

@@ -115,6 +115,18 @@ class JsonReader {
         return value;
     }
 }
+/** Bounded duplicate-aware JSON for fresh-card preparation bodies. */
+export function readTokenizationJson(body) {
+    if (typeof body !== 'string' || body.length === 0 || body.length > MAX_BODY_LENGTH)
+        return null;
+    try {
+        const value = new JsonReader(body).read();
+        return record(value) ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
 /** Native operations need names, punctuation and variables, never literals. */
 function lex(query) {
     const tokens = [];

package/dist/cdp.d.ts

@@ -75,18 +75,32 @@ export interface AttachOptions extends LifecycleOptions {
     vault: VaultClient;
     user: string;
     merchant: string;
-    /** Display string for the approval screen. Optional when amountCents + currency are given. */
-    amount?: string;
     /**
-     * The amount as a number (smallest currency unit) with its ISO 4217 code.
-     * See AuthorizeInput.amountCents: on a Stripe PaymentIntent confirm this
-     * binds the approval to the intent's amount, checked at create and again
-     * right before replay, so a larger charge is refused with nothing charged.
+     * Your hint at the amount, an integer in the currency's smallest unit or a
+     * decimal string in normal units, with its ISO 4217 code. See
+     * AuthorizeInput.amount: the processor's own amount is the higher authority
+     * and is read right before the card is sent; a hint lets a bad purchase be
+     * refused the moment it opens, and one that disagrees with the processor is
+     * refused with nothing charged.
      */
-    amountCents?: number;
+    amount?: number | string;
     currency?: string;
+    /**
+     * The total the checkout page shows, the lowest authority: used only when
+     * neither the processor's request nor your `amount` names one. Pass a reader
+     * that returns an integer in the currency's smallest unit with its code
+     * (`{ amount: 4210, currency: 'usd' }`), read off the page however your
+     * page spells it; the adapters call it when a card request pauses, give it
+     * one second, and send nothing when it yields nothing. Absent: no page total.
+     */
+    pageAmount?: () => Promise<{
+        amount: number;
+        currency: string;
+    } | undefined>;
     cardId?: string;
     timeoutMs?: number;
+    /** Browser interception setup deadline, separate from approval. Defaults to 30000 ms; maximum 300000 ms. */
+    attachmentTimeoutMs?: number;
     /** Explicit payment endpoints to block if the registry cannot handle their method/format. Unlisted traffic is untouched. */
     paymentEndpoints?: readonly PaymentEndpointGuard[];
     onApprovalUrl?: (url: string) => void;