@agent-cards/checkout 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # 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.

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,7 +127,7 @@ 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 |
+| 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 |
@@ -352,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),
@@ -395,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.
@@ -417,7 +415,7 @@ Prepare a Square, Braintree, Worldpay, Bambora or Mercado Pago checkout before t
 ```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({
@@ -429,7 +427,7 @@ const preparation = await checkout.prepare({
 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 |
 | --- | --- | --- |

package/dist/cdp.d.ts

@@ -75,16 +75,28 @@ 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. */

package/dist/cdp.js

@@ -274,6 +274,59 @@ export function withCorsHeaders(headers, cors) {
 function headerEntries(headers) {
     return Object.entries(headers).map(([name, value]) => ({ name, value: String(value) }));
 }
+/**
+ * The origin of the top-level document the payment form is on, read when a
+ * card request pauses: the fact that names the merchant for the company's
+ * presets (the API's checkout_origin). An https origin, or http://localhost
+ * for local checkout; anything else, or a page that cannot be read, yields
+ * undefined and the authorization goes out without one (a merchant, category
+ * or place rule then refuses it as unknown, never the request itself).
+ */
+async function pageOriginOf(readDocumentUrl) {
+    try {
+        const url = new URL(await readDocumentUrl());
+        if (url.username || url.password)
+            return undefined;
+        if (url.protocol === 'https:' || (url.protocol === 'http:' && url.hostname === 'localhost'))
+            return url.origin;
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The page total, the lowest amount authority, through the integrator's own
+ * reader (AttachOptions.pageAmount): an integer in the smallest unit with its
+ * currency, or nothing. A read is a courtesy, never a wait: it gets one
+ * second, and anything unreadable yields undefined so the authorization goes
+ * out without a page total.
+ */
+const PAGE_AMOUNT_READ_MS = 1_000;
+async function pageAmountOf(opts) {
+    if (!opts.pageAmount)
+        return undefined;
+    let timer;
+    try {
+        const raw = await Promise.race([
+            Promise.resolve().then(() => opts.pageAmount()).catch(() => undefined),
+            new Promise((resolve) => { timer = setTimeout(() => resolve(undefined), PAGE_AMOUNT_READ_MS); }),
+        ]);
+        if (!raw || typeof raw !== 'object')
+            return undefined;
+        const { amount, currency } = raw;
+        if (!Number.isSafeInteger(amount) || amount < 0 || typeof currency !== 'string' || !/^[A-Za-z]{3}$/.test(currency))
+            return undefined;
+        return { amount: amount, currency: currency.toLowerCase() };
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
 /**
  * Last-resort patterns: the built-in recognizers' hosts, derived the same way
  * as everything else. Used only when the vault hands back nothing at all (a
@@ -335,13 +388,14 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
     let setupFailureReported = false;
     const lifecycle = new CheckoutLifecycle(opts);
     let preparationFrameId;
-    const preparationGate = new PreparationGate(opts, lifecycle, async () => {
+    const readDocumentUrl = async () => {
         const tree = await cdp.send('Page.getFrameTree', {}, pageSessionId);
         if (typeof tree?.frameTree?.frame?.url !== 'string')
             throw new Error('merchant_document_unavailable');
         preparationFrameId = tree.frameTree.frame.id;
         return tree.frameTree.frame.url;
-    });
+    };
+    const preparationGate = new PreparationGate(opts, lifecycle, readDocumentUrl);
     const guards = paymentEndpointGuards(opts.paymentEndpoints);
     const armed = new Set();
     const arming = new Map();
@@ -533,14 +587,17 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
             activeRequest = { attempt, networkId, sessionId, frameId };
             if (preparation)
                 await preparationGate.assertDocument();
+            const pageOrigin = await pageOriginOf(readDocumentUrl);
+            const pageAmount = await pageAmountOf(opts);
             attempt.assertLive();
             const replay = await opts.vault.authorize({
                 user: opts.user,
                 merchant: opts.merchant,
                 amount: opts.amount,
-                amountCents: opts.amountCents,
                 currency: opts.currency,
                 cardId: preparation?.cardId ?? opts.cardId,
+                pageOrigin,
+                pageAmount,
                 preparation,
                 timeoutMs: opts.timeoutMs,
                 signal: lifecycle.abort.signal,
@@ -675,11 +732,12 @@ export async function attachToPlaywright(page, opts) {
         throw new Error('Service workers are active; use a checkout context created with serviceWorkers: "block".');
     }
     const lifecycle = new CheckoutLifecycle(opts);
-    const preparationGate = new PreparationGate(opts, lifecycle, async () => {
+    const readDocumentUrl = async () => {
         if (page.isClosed?.() || typeof page.url !== 'function')
             throw new Error('merchant_document_unavailable');
         return page.url();
-    });
+    };
+    const preparationGate = new PreparationGate(opts, lifecycle, readDocumentUrl);
     const guards = paymentEndpointGuards(opts.paymentEndpoints);
     // Playwright's own routing, NOT a hand-rolled CDP session.
     //
@@ -800,14 +858,17 @@ export async function attachToPlaywright(page, opts) {
                 activeRequest = { request, frames, attempt };
                 if (preparation)
                     await preparationGate.assertDocument();
+                const pageOrigin = await pageOriginOf(readDocumentUrl);
+                const pageAmount = await pageAmountOf(opts);
                 assertRequestLive();
                 const replay = await opts.vault.authorize({
                     user: opts.user,
                     merchant: opts.merchant,
                     amount: opts.amount,
-                    amountCents: opts.amountCents,
                     currency: opts.currency,
                     cardId: preparation?.cardId ?? opts.cardId,
+                    pageOrigin,
+                    pageAmount,
                     preparation,
                     timeoutMs: opts.timeoutMs,
                     signal: lifecycle.abort.signal,

package/dist/client.d.ts

@@ -19,7 +19,16 @@ export declare const SUPPORTED_MODES: readonly CheckoutMode[];
  * (hosted_form: the bytes the device submits name the amount), or a display
  * fact on a template that carries no amount.
  */
-export type AmountAuthority = 'stripe_payment_intent' | 'hosted_form_sum' | 'display_only';
+/**
+ * Who named the amount an authorization carries: `processor` (the paused
+ * request's own bytes, or the Stripe intent it names, read back by Agentcard),
+ * `agent` (the `amount` you passed), `page` (the total read off the checkout
+ * page), or `none` (nobody yet; the processor is read right before the card
+ * is sent).
+ */
+export type AmountAuthority = 'processor' | 'agent' | 'page' | 'none';
+/** An integer in the smallest unit, or a decimal string in normal units with a point; nothing else. */
+export declare function validAmountInput(amount: unknown): amount is number | string;
 /**
  * The token flow: the cardholder's device called the processor itself, and
  * this is the processor's answer to replay into the paused request.
@@ -41,17 +50,18 @@ export interface TokenReplay {
      * moved) and Agentcard also sent your server checkout_authorization.amount_mismatch.
      */
     amountVerified?: boolean | null;
-    chargedAmountCents?: number | null;
+    /** What the processor collected, an integer in the currency's smallest unit (Stripe's `amount`). */
+    chargedAmount?: number | null;
     chargedCurrency?: string | null;
     /**
-     * What `chargedAmountCents` is: 'captured' (the intent succeeded; this is
+     * What `chargedAmount` is: 'captured' (the intent succeeded; this is
      * amount_received), 'authorized' (requires_capture; amount_capturable, the
      * merchant captures later), 'none' (a PaymentIntent was reported but
      * nothing is collected yet: processing, requires_action), or null when no
      * PaymentIntent was reported at all (a tokenization request).
      */
     chargedKind?: 'captured' | 'authorized' | 'none' | null;
-    /** 'stripe_payment_intent' when the amount was held to a Stripe intent; 'display_only' otherwise. */
+    /** Who named the amount the person approved. */
     amountAuthority?: AmountAuthority;
 }
 /**
@@ -108,7 +118,8 @@ export interface PrepareCheckoutOptions {
 export interface PrepareCheckoutInput extends PrepareCheckoutOptions {
     user: string;
     merchant: string;
-    amountCents: number;
+    /** An integer in the currency's smallest unit (2306 for $23.06), or a decimal string in normal units ("23.06"). */
+    amount: number | string;
     currency: string;
     cardId?: string;
     merchantOrigin: string;
@@ -127,12 +138,14 @@ export interface PreparedCheckout {
     readonly cardId: string;
     readonly user: string;
     readonly merchant: string;
-    readonly amountCents: number;
+    /** The approved amount, an integer in the currency's smallest unit, as the API confirmed it. */
+    readonly amount: number;
+    readonly amountDisplay: string | null;
     readonly currency: string;
     readonly merchantOrigin: string;
     readonly checkoutKey: string;
     readonly paymentStatus: 'not_started';
-    readonly amountAuthority: 'display_only';
+    readonly amountAuthority: 'agent';
 }
 export declare class CheckoutPreparationError extends Error {
     preparationId: string | null;
@@ -142,27 +155,31 @@ export declare class CheckoutPreparationError extends Error {
 export interface AuthorizeInput {
     /** Your identifier for the person whose card should pay. */
     user: string;
-    /** Shown to the user on the approval screen. */
+    /** Shown to the user on the approval screen. Judged by nothing: the merchant comes from the checkout page. */
     merchant: string;
     /**
-     * The display string the approval screen shows ("$23.06"). Optional when
-     * amountCents + currency are given, and IGNORED then: Agentcard derives the
-     * string from the number so every surface shows one amount.
+     * Your hint at the amount: an integer in the currency's smallest unit (2306
+     * for $23.06), or a decimal string in normal units ("23.06"), with its ISO
+     * 4217 code ("usd"). Optional: the processor's own amount is the higher
+     * authority, read from the paused request or from the Stripe intent it
+     * 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
+     * you open it, and a hint that disagrees with the processor beyond one
+     * smallest unit is refused with nothing charged (an AmountMismatchError;
+     * `stage` says which check). Agentcard derives the display string; you
+     * never send one. Both or neither: one without the other is refused.
      */
-    amount?: string;
+    amount?: number | string;
+    currency?: string;
     /**
-     * The amount as a number in the smallest currency unit (2306 for $23.06)
-     * with its ISO 4217 code ("usd"). On a Stripe PaymentIntent confirm this
-     * pair is BOUND to the intent: Agentcard reads the intent back from Stripe
-     * at create and again right before the cardholder's device replays, and a
-     * different amount is refused with nothing charged (an AmountMismatchError
-     * either way: `stage` says which check). After the replay the charge is
-     * reconciled against the approval (see ReplayResponse.amountVerified).
-     * Tokenization requests carry no amount, so there it is display-only.
-     * Both or neither: one without the other is refused.
+     * The total read off the checkout page, the lowest authority: used only
+     * when neither the processor's request nor your hint names an amount. The
+     * adapters fill it from `[data-agentcard-amount]` when a page carries one.
      */
-    amountCents?: number;
-    currency?: string;
+    pageAmount?: {
+        amount: number;
+        currency: string;
+    };
     /**
      * WHICH stored card should pay — a vault card id from
      * GET /api/v2/vault_cards. The approval page preselects it (the human can
@@ -171,6 +188,14 @@ export interface AuthorizeInput {
      * `card_not_found`.
      */
     cardId?: string;
+    /**
+     * The origin of the checkout page the payment form was on
+     * (https://shop.example.com). The adapters read it from the page; pass it
+     * yourself when you run your own interception. With the processor identity
+     * in the paused request this is what names the merchant for the company's
+     * presets; `merchant` above is shown to the person and judged by nothing.
+     */
+    pageOrigin?: string;
     request: PausedRequest;
     /** Abort if the user has not approved within this many ms. Default 15 min. */
     timeoutMs?: number;
@@ -300,6 +325,69 @@ export declare class ProcessorRefusedError extends ApprovalDeclinedError {
  * retrying is worth anything: a 404 `connection_not_found` will answer the same
  * way forever, while a 429 or a 502 will not.
  */
+/**
+ * The company's preset refused the purchase. The company that runs this
+ * integration put rules on its users' Vault purchases (a merchant list, a
+ * currency, a spend cap, a time window); this purchase is outside them.
+ * Nothing was charged. Two stages:
+ *   - 'create': refused before any authorization existed (`authorizationId`
+ *     is null); nobody was asked to approve. Per purchase, not per page: the
+ *     next request on the same page is judged afresh.
+ *   - 'pre_replay': refused right before the cardholder's device would have
+ *     sent the card; the authorization is `declined` with `code` as reason.
+ * `code` is the rule's reason (merchant_denied, currency_denied,
+ * spend_rate_exceeded, time_window_denied, ...), `message` the rule's own
+ * statement with the company's next step, `preset` the version that judged
+ * it. When several presets refused the same purchase, `code`, `preset`,
+ * `rule` and `attachment` are the first, and `refusals` names every one. A
+ * decline in every structural sense (the adapters quiet the page's retry as
+ * for a person's "no"), so it extends ApprovalDeclinedError.
+ */
+export declare class PresetRefusedError extends ApprovalDeclinedError {
+    readonly authorizationId: string | null;
+    readonly code: string;
+    readonly detail: string | null;
+    readonly preset: {
+        id: string;
+        version: number;
+        name: string;
+    } | null;
+    readonly rule: string | null;
+    readonly stage: 'create' | 'pre_replay';
+    /** The stored card the preset that refused is attached to, with its last four digits. */
+    readonly attachment: PresetAttachment | null;
+    /** The preset's name. */
+    readonly presetName: string | null;
+    /** Every preset that refused, each with its attachment, rule, code and statement; one entry when one refused. */
+    readonly refusals: readonly PresetRefusal[];
+    constructor(authorizationId: string | null, code: string, detail: string | null, preset: {
+        id: string;
+        version: number;
+        name: string;
+    } | null, rule: string | null, stage: 'create' | 'pre_replay', 
+    /** The stored card the preset that refused is attached to, with its last four digits. */
+    attachment?: PresetAttachment | null, refusals?: readonly PresetRefusal[]);
+}
+/** The stored card a preset is attached to, with its last four digits. */
+export interface PresetAttachment {
+    kind: 'card';
+    targetId: string | null;
+    last4: string | null;
+}
+/** One preset's refusal of a purchase. */
+export interface PresetRefusal {
+    preset: {
+        id: string;
+        version: number;
+        name: string;
+    };
+    attachment: PresetAttachment | null;
+    rule: string | null;
+    code: string;
+    detail: string | null;
+}
+/** A decline reason only the company presets stamp (see PresetRefusedError). */
+export declare const PRESET_REFUSAL_REASONS: ReadonlySet<string>;
 export declare class CheckoutApiError extends Error {
     status: number;
     path: string;

package/dist/client.js

@@ -6,7 +6,13 @@ import { matchesPreparedRequest, validPreparationEnvironment } from './prepared-
  * is never paused) and sent on every create.
  */
 export const SUPPORTED_MODES = ['token', 'cse', 'hosted_form'];
-const AMOUNT_AUTHORITIES = ['stripe_payment_intent', 'hosted_form_sum', 'display_only'];
+/** An integer in the smallest unit, or a decimal string in normal units with a point; nothing else. */
+export function validAmountInput(amount) {
+    if (typeof amount === 'number')
+        return Number.isSafeInteger(amount) && amount >= 0;
+    return typeof amount === 'string' && /^\d{1,15}\.\d{1,3}$/.test(amount.trim());
+}
+const AMOUNT_AUTHORITIES = ['processor', 'agent', 'page', 'none'];
 export class CheckoutPreparationError extends Error {
     preparationId;
     reason;
@@ -180,6 +186,94 @@ export class ProcessorRefusedError extends ApprovalDeclinedError {
  * retrying is worth anything: a 404 `connection_not_found` will answer the same
  * way forever, while a 429 or a 502 will not.
  */
+/**
+ * The company's preset refused the purchase. The company that runs this
+ * integration put rules on its users' Vault purchases (a merchant list, a
+ * currency, a spend cap, a time window); this purchase is outside them.
+ * Nothing was charged. Two stages:
+ *   - 'create': refused before any authorization existed (`authorizationId`
+ *     is null); nobody was asked to approve. Per purchase, not per page: the
+ *     next request on the same page is judged afresh.
+ *   - 'pre_replay': refused right before the cardholder's device would have
+ *     sent the card; the authorization is `declined` with `code` as reason.
+ * `code` is the rule's reason (merchant_denied, currency_denied,
+ * spend_rate_exceeded, time_window_denied, ...), `message` the rule's own
+ * statement with the company's next step, `preset` the version that judged
+ * it. When several presets refused the same purchase, `code`, `preset`,
+ * `rule` and `attachment` are the first, and `refusals` names every one. A
+ * decline in every structural sense (the adapters quiet the page's retry as
+ * for a person's "no"), so it extends ApprovalDeclinedError.
+ */
+export class PresetRefusedError extends ApprovalDeclinedError {
+    authorizationId;
+    code;
+    detail;
+    preset;
+    rule;
+    stage;
+    attachment;
+    /** The preset's name. */
+    presetName;
+    /** Every preset that refused, each with its attachment, rule, code and statement; one entry when one refused. */
+    refusals;
+    constructor(authorizationId, code, detail, preset, rule, stage, 
+    /** The stored card the preset that refused is attached to, with its last four digits. */
+    attachment = null, refusals = []) {
+        super(code);
+        this.authorizationId = authorizationId;
+        this.code = code;
+        this.detail = detail;
+        this.preset = preset;
+        this.rule = rule;
+        this.stage = stage;
+        this.attachment = attachment;
+        this.name = 'PresetRefusedError';
+        this.presetName = preset?.name ?? null;
+        this.refusals = refusals.length ? refusals : preset ? [{ preset, attachment, rule, code, detail }] : [];
+        const others = this.refusals.slice(1).map((r) => `"${r.preset.name}"`);
+        const also = others.length ? ` Also refused by ${others.length === 1 ? 'preset' : 'presets'} ${others.join(', ')}.` : '';
+        this.message = `refused by the company preset${preset ? ` "${preset.name}"` : ''} (${code}${stage === 'create' ? ', before any authorization was created' : ''}): ${detail ?? 'this purchase is outside the rules the company set'}${also}`;
+    }
+}
+/** A decline reason only the company presets stamp (see PresetRefusedError). */
+export const PRESET_REFUSAL_REASONS = new Set([
+    'spend_total_exceeded', 'spend_rate_exceeded', 'spend_rate_unknown',
+    'category_denied', 'category_unknown', 'merchant_denied', 'merchant_unknown',
+    'geo_denied', 'geo_unknown', 'currency_denied', 'currency_unknown',
+    'time_window_denied', 'surface_denied', 'surface_unknown',
+]);
+function presetOf(v) {
+    if (!v || typeof v !== 'object')
+        return null;
+    const p = v;
+    if (typeof p.id !== 'string' || typeof p.version !== 'number' || typeof p.name !== 'string')
+        return null;
+    return { id: p.id, version: p.version, name: p.name };
+}
+function attachmentOf(v) {
+    if (!v || typeof v !== 'object')
+        return null;
+    const a = v;
+    if (a.kind !== 'card')
+        return null;
+    return { kind: a.kind, targetId: typeof a.target_id === 'string' ? a.target_id : null, last4: typeof a.last4 === 'string' ? a.last4 : null };
+}
+/** The `refusals` list of a refusal envelope: every entry that names a preset. */
+function refusalsOf(v) {
+    if (!Array.isArray(v))
+        return [];
+    const out = [];
+    for (const item of v) {
+        if (!item || typeof item !== 'object')
+            continue;
+        const r = item;
+        const preset = presetOf(r.preset);
+        if (!preset || typeof r.reason !== 'string')
+            continue;
+        out.push({ preset, attachment: attachmentOf(r.attachment), rule: typeof r.rule === 'string' ? r.rule : null, code: r.reason, detail: typeof r.message === 'string' ? r.message : null });
+    }
+    return out;
+}
 export class CheckoutApiError extends Error {
     status;
     path;
@@ -218,6 +312,12 @@ export class CheckoutApiError extends Error {
     get permanent() {
         if (this.code === 'amount_mismatch' || this.code === 'duplicate_submission')
             return false;
+        // Nor a refusal by the company preset (a 403 carrying `preset` in the
+        // envelope): the company's rules refused THIS purchase, at this merchant,
+        // for this amount, at this hour. The next one on the same page may pass,
+        // so the page is quieted like a decline, never latched.
+        if (this.details.preset && typeof this.details.preset === 'object')
+            return false;
         return this.status >= 400 && this.status < 500 && this.status !== 429;
     }
 }
@@ -317,7 +417,7 @@ export class VaultClient {
         const fail = (reason, id = null) => new CheckoutPreparationError(id, reason);
         if (!validPreparationEnvironment(input.psp, 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))
+        if (!validAmountInput(input.amount) || typeof input.currency !== 'string' || !/^[a-z]{3}$/i.test(input.currency))
             throw fail('amount_required');
         const origin = new URL(input.merchantOrigin);
         if (!(origin.protocol === 'https:' || (origin.protocol === 'http:' && origin.hostname === 'localhost')) || origin.origin !== input.merchantOrigin)
@@ -336,7 +436,7 @@ export class VaultClient {
             // Drain a sent creation even after caller cancellation to retire its ID.
             // The separate stop signal prevents dispatch after a slow OAuth exchange.
             const created = await this.post('/v2/checkout/preparations', {
-                user: input.user, merchant: input.merchant, amount_cents: input.amountCents, currency: input.currency.toLowerCase(),
+                user: input.user, merchant: input.merchant, amount: input.amount, currency: input.currency.toLowerCase(),
                 ...(input.cardId ? { card_id: input.cardId } : {}), psp: input.psp, mode: 'token',
                 environment: input.environment, checkout_key: input.checkoutKey, merchant_origin: input.merchantOrigin,
             }, AbortSignal.timeout(30_000), signal);
@@ -365,17 +465,18 @@ export class VaultClient {
                 if (state.status === 'ready') {
                     const expiry = Date.parse(state.ready_expires_at);
                     if (!Number.isFinite(expiry) || expiry <= Date.now() || typeof state.card_id !== 'string' || !state.card_id
-                        || state.payment_status !== 'not_started' || state.amount_authority !== 'display_only'
+                        || state.payment_status !== 'not_started' || state.amount_authority !== 'agent'
                         || state.user !== input.user || state.merchant !== input.merchant || state.merchant_origin !== input.merchantOrigin
-                        || state.amount_cents !== input.amountCents || state.currency !== input.currency.toLowerCase()
+                        || !Number.isSafeInteger(state.amount) || (typeof input.amount === 'number' && state.amount !== input.amount) || state.currency !== input.currency.toLowerCase()
                         || 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({
                         id: preparationId, status: 'ready', psp: input.psp, environment: input.environment, expiresAt: state.ready_expires_at,
-                        cardId: state.card_id, user: input.user, merchant: input.merchant, amountCents: input.amountCents,
+                        cardId: state.card_id, user: input.user, merchant: input.merchant, amount: state.amount,
+                        amountDisplay: typeof state.amount_display === 'string' ? state.amount_display : null,
                         currency: input.currency.toLowerCase(), merchantOrigin: input.merchantOrigin, checkoutKey: input.checkoutKey,
-                        paymentStatus: 'not_started', amountAuthority: 'display_only',
+                        paymentStatus: 'not_started', amountAuthority: 'agent',
                     });
                     this.preparations.add(prepared);
                     ready = true;
@@ -419,7 +520,7 @@ export class VaultClient {
             this.usedPreparations.add(preparation);
             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
+            if (input.user !== preparation.user || input.merchant !== preparation.merchant || (typeof input.amount === 'number' && input.amount !== preparation.amount) || (typeof input.amount === 'string' && !validAmountInput(input.amount))
                 || input.currency?.toLowerCase() !== preparation.currency || input.cardId !== preparation.cardId
                 || !matchesPreparedRequest(preparation.psp, preparation.environment, input.request.url, input.request.method ?? 'POST', input.request.body))
                 throw new CheckoutPreparationError(preparation.id, 'checkout_changed');
@@ -452,16 +553,16 @@ export class VaultClient {
             throw new Error(`checkout authorization is POST-only; got ${method} for ${redactUrl(input.request.url)}. ` +
                 'A non-POST tokenizer needs recognizer support before it can be intercepted.');
         }
-        // The amount travels as a display string, a number with its currency, or
-        // both. Refuse half a pair here, before a network call: the API would too,
-        // and a retry loop cannot fix a missing field.
-        const hasCents = input.amountCents != null;
+        // The amount is a hint: a pair or nothing. Refuse half a pair here, before
+        // a network call: the API would too, and a retry loop cannot fix a
+        // missing field. The processor's own amount is read by Agentcard.
+        const hasAmount = input.amount != null;
         const hasCurrency = typeof input.currency === 'string' && input.currency.length > 0;
-        if (hasCents !== hasCurrency) {
-            throw new Error('amountCents and currency go together: pass both or neither.');
+        if (hasAmount !== hasCurrency) {
+            throw new Error('amount and currency go together: pass both or neither.');
         }
-        if (!input.amount && !hasCents) {
-            throw new Error('authorize needs amount (a display string), or amountCents with currency.');
+        if (hasAmount && !validAmountInput(input.amount)) {
+            throw new Error('amount is an integer in the currency\'s smallest unit (2306 for $23.06), or a decimal string in normal units ("23.06").');
         }
         const timeoutMs = input.timeoutMs ?? 15 * 60_000;
         if (!Number.isInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > 2_147_483_647)
@@ -473,15 +574,18 @@ export class VaultClient {
         const payload = {
             user: input.user,
             merchant: input.merchant,
-            ...(input.amount ? { amount: input.amount } : {}),
             // snake_case on the wire; camelCase is this SDK's convention.
-            ...(hasCents ? { amount_cents: input.amountCents, currency: input.currency } : {}),
+            ...(hasAmount ? { amount: input.amount, currency: input.currency } : {}),
+            ...(input.pageAmount ? { page_amount: input.pageAmount.amount, page_currency: input.pageAmount.currency } : {}),
             psp: rec.psp,
             // The mode this request will be finished in. The API checks it against
             // the recognizer and refuses a disagreement before a row exists.
             mode,
             ...(input.cardId ? { cardId: input.cardId } : {}),
-            ...(preparation ? { preparation_id: preparation.id, checkout_key: preparation.checkoutKey, merchant_origin: preparation.merchantOrigin } : {}),
+            // A prepared checkout already carries the page origin as merchant_origin.
+            ...(preparation
+                ? { preparation_id: preparation.id, checkout_key: preparation.checkoutKey, merchant_origin: preparation.merchantOrigin }
+                : input.pageOrigin ? { checkout_origin: input.pageOrigin } : {}),
             request: {
                 url: input.request.url,
                 method: input.request.method,
@@ -621,7 +725,7 @@ export class VaultClient {
                         authorizationId,
                         ...response,
                         amountVerified: typeof s.amount_verified === 'boolean' ? s.amount_verified : null,
-                        chargedAmountCents: typeof s.charged_amount_cents === 'number' ? s.charged_amount_cents : null,
+                        chargedAmount: typeof s.charged_amount === 'number' ? s.charged_amount : null,
                         chargedCurrency: typeof s.charged_currency === 'string' ? s.charged_currency : null,
                         chargedKind: s.charged_kind === 'captured' || s.charged_kind === 'authorized' || s.charged_kind === 'none' ? s.charged_kind : null,
                         ...amountAuthority,
@@ -635,6 +739,9 @@ export class VaultClient {
                     }
                     if (s.reason === 'intent_not_confirmable')
                         throw new IntentNotConfirmableError(String(created.id));
+                    if (typeof s.reason === 'string' && PRESET_REFUSAL_REASONS.has(s.reason)) {
+                        throw new PresetRefusedError(String(created.id), s.reason, typeof s.message === 'string' ? s.message : null, presetOf(s.preset), typeof s.rule === 'string' ? s.rule : null, 'pre_replay', attachmentOf(s.attachment), refusalsOf(s.refusals));
+                    }
                     if (s.reason === 'processor_refused') {
                         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);
                     }
@@ -718,6 +825,11 @@ export class VaultClient {
                 return await this.post('/v2/checkout/authorizations', payload, signal, stopRetries);
             }
             catch (err) {
+                if (err instanceof CheckoutApiError && err.code && err.status === 403 && presetOf(err.details.preset)) {
+                    // A company preset refused this purchase before a row existed.
+                    const d = err.details;
+                    throw new PresetRefusedError(null, err.code, typeof d.message === 'string' ? d.message : null, presetOf(d.preset), typeof d.rule === 'string' ? d.rule : null, 'create', attachmentOf(d.attachment), refusalsOf(d.refusals));
+                }
                 if (err instanceof CheckoutApiError && err.code === 'amount_mismatch') {
                     const d = err.details;
                     throw new AmountMismatchError(null, Number(d.expected_cents), Number(d.actual_cents), String(d.currency ?? currency ?? ''), d.actual_currency != null ? String(d.actual_currency) : undefined, 'create');

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { VaultClient, CardEncryptedError, UnsupportedModeError, ApprovalTimeoutError, ApprovalDeclinedError, AmountMismatchError, IntentNotConfirmableError, ProcessorRefusedError, CheckoutApiError, redactUrl, SUPPORTED_MODES, PaymentOutcomeUnknownError, CheckoutCancelledError, CheckoutPreparationError, } from './client.js';
+export { VaultClient, CardEncryptedError, UnsupportedModeError, ApprovalTimeoutError, ApprovalDeclinedError, AmountMismatchError, PresetRefusedError, PRESET_REFUSAL_REASONS, 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, RazorpayProcessorError, } from './client.js';
 export { attachToCdp, attachToPlaywright, corsHeadersFor, corsDecision, withCorsHeaders } from './cdp.js';
 export { CheckoutAttachmentError } from './attachment.js';

package/dist/index.js

@@ -1,4 +1,4 @@
-export { VaultClient, CardEncryptedError, UnsupportedModeError, ApprovalTimeoutError, ApprovalDeclinedError, AmountMismatchError, IntentNotConfirmableError, ProcessorRefusedError, CheckoutApiError, redactUrl, SUPPORTED_MODES, PaymentOutcomeUnknownError, CheckoutCancelledError, CheckoutPreparationError, } from './client.js';
+export { VaultClient, CardEncryptedError, UnsupportedModeError, ApprovalTimeoutError, ApprovalDeclinedError, AmountMismatchError, PresetRefusedError, PRESET_REFUSAL_REASONS, IntentNotConfirmableError, ProcessorRefusedError, CheckoutApiError, redactUrl, SUPPORTED_MODES, PaymentOutcomeUnknownError, CheckoutCancelledError, CheckoutPreparationError, } from './client.js';
 export { attachToCdp, attachToPlaywright, corsHeadersFor, corsDecision, withCorsHeaders } from './cdp.js';
 export { CheckoutAttachmentError } from './attachment.js';
 export { substituteEncryptedFields, SubstitutionError } from './substitute.js';

package/dist/preparation.js

@@ -1,4 +1,5 @@
 import { CheckoutPreparationError } from './client.js';
+import { validAmountInput } from './client.js';
 import { matchesPreparedRequest, validPreparationEnvironment, preparationEndpoint } from './prepared-processor.js';
 /** A local, one-use rendezvous. It never starts or retries a merchant request. */
 export class PreparationGate {
@@ -39,7 +40,7 @@ export class PreparationGate {
             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 ?? ''))
+            if (!validAmountInput(this.opts.amount) || this.opts.amount === 0 || !/^[a-z]{3}$/i.test(this.opts.currency ?? ''))
                 throw new CheckoutPreparationError(null, 'amount_required');
             if (signal.aborted)
                 throw new CheckoutPreparationError(null, 'cancelled');
@@ -49,7 +50,7 @@ export class PreparationGate {
                 throw new CheckoutPreparationError(null, 'merchant_origin_invalid');
             const prepared = await this.opts.vault.prepareCheckout({
                 ...options, user: this.opts.user, merchant: this.opts.merchant,
-                amountCents: this.opts.amountCents, currency: this.opts.currency, cardId: this.opts.cardId,
+                amount: this.opts.amount, currency: this.opts.currency, cardId: this.opts.cardId,
                 merchantOrigin: page.origin, checkoutKey: crypto.randomUUID(), timeoutMs: this.opts.timeoutMs, signal,
                 onPreparationCreated: id => this.lifecycle.preparationCreated(id),
                 onApprovalUrl: url => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-cards/checkout",
-  "version": "0.6.0",
+  "version": "0.7.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",