@agent-cards/checkout 0.4.0 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 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

@@ -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).

package/dist/cdp.js

@@ -1,5 +1,5 @@
 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 { substituteEncryptedFields } from './substitute.js';
 import { hostedFormSubmittedPage } from './hosted-form.js';
@@ -80,6 +80,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 +103,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

package/dist/client.d.ts

@@ -271,20 +271,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

@@ -128,25 +128,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.`;
     }
 }
 /**
@@ -611,7 +635,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-cards/checkout",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Let browser agents pay with the user's own card, without your infrastructure ever touching card data.",
   "type": "module",
   "main": "dist/index.js",