@piprail/sdk 2.6.0 → 2.7.0

package/CHANGELOG.md

@@ -4,6 +4,39 @@ All notable changes to `@piprail/sdk` are documented here. The format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the
 versions follow [Semantic Versioning](https://semver.org/).
 
+## [2.7.0] — 2026-06-19 — symmetric payment notifications (`onFailed`: both sides notified on success AND failure)
+
+Additive and backward-compatible — defaults and the zero-config 402 stay byte-identical; omit the new
+options and behaviour is unchanged.
+
+- **New merchant hook `onFailed(failure)`** on `createPaymentGate` / `requirePayment` — the mirror of
+  `onPaid`. It fires whenever a SUBMITTED proof is rejected (a `kind:'invalid'` verdict: wrong amount,
+  expired, replayed, unknown asset, …), so the merchant is notified of a failure exactly as the buyer's
+  client already is. The new `FailedPayment` it receives carries the SAME machine `code` (a
+  `VerifyErrorCode`) the buyer gets — one consistent reason on both sides.
+- **`onFailedError(error, failure)`** and **`awaitOnFailed`** mirror `onPaidError` / `awaitOnPaid`: the
+  hook is fully isolated (a sync throw or async rejection routes to `onFailedError` — it can never break
+  the request or escape as an unhandledRejection), and `awaitOnFailed` runs it before the 402 returns.
+- **Exported `FailedPayment` type** — `{ code, detail, transient }`. The `transient` flag is `true` for
+  `tx_not_found` / `insufficient_confirmations` (the proof may still be settling and the buyer's client
+  auto-retries — alert on `!transient` to avoid false alarms on RPC lag), `false` for a definitive
+  rejection (wrong amount, expired, replayed, bad signature, …). Nothing is hidden — every rejected
+  attempt still fires `onFailed`.
+- **Buyer side:** the `payment-failed` client event now also carries structured `code` / `detail` (the
+  server's parsed reason) alongside the existing human `reason`. It now ALSO fires on a **pre-send
+  decline** (policy / `onBeforePay` / no settleable rail) — previously those only threw — so a consumer
+  watching `onEvent` learns of EVERY failure, not just server rejections (the typed throw is unchanged).
+- **Fires only on a real rejection** — not on a normal first-request `challenge` (no proof yet), and not
+  on a transient/settlement error that throws (an RPC blip, or a 5xx `SettlementError`): those aren't
+  payment verdicts. A failure the merchant never receives a request for (insufficient funds, policy
+  decline, abandonment) reaches only the buyer — a backendless gate is passive by design.
+- **Examples + tests:** a complete `examples/payment-system/` reference (merchant + buyer — both sides,
+  success + failure → a SQLite ledger with a free `/ledger` dashboard); `onFailed` added to the Express +
+  Next.js examples. Coverage spans every `VerifyErrorCode`, both rails, the `requirePayment` middleware,
+  the `transient` flag, concurrency, replay-after-success, that a thrown `SettlementError`/transient error
+  does NOT fire `onFailed`, buyer declines, and a full client↔gate HTTP loop proving both sides receive
+  the same `code`.
+
 ## [2.6.0] — 2026-06-18 — keyless-gasless `exact` on 7 more EVM mainnets (6 → 13 chains)
 
 Additive and backward-compatible — defaults and the zero-config 402 stay byte-identical; this only

package/README.md

@@ -24,7 +24,7 @@ app.get('/report',
 )
 ```
 
-That route now costs **0.05 USDC on Base**, paid straight to your wallet. One parameter picks the chain. → [Accepting payments](https://docs.piprail.com/accepting-payments/require-payment-and-gate/)
+That route now costs **0.05 USDC on Base**, paid straight to your wallet. One parameter picks the chain. Add `onPaid` / `onFailed` to be notified the moment a payment settles or is rejected — both carry the same reason, and the buyer's client is notified too. → [Accepting payments](https://docs.piprail.com/accepting-payments/require-payment-and-gate/)
 
 ## Let an agent pay for it
 

package/dist/index.cjs

@@ -3212,7 +3212,9 @@ var PipRailClient = (_class2 = class {
     if (autoRoute) {
       const plan = await this.planFromChallenge(net, wallet, challenge, url, schemes);
       if (!plan.best) {
-        throw new (0, _chunkJG6KRAW6cjs.PaymentDeclinedError)(_nullishCoalesce(plan.fundingHint, () => ( "No rail is settleable for this payment.")));
+        const reason = _nullishCoalesce(plan.fundingHint, () => ( "No rail is settleable for this payment."));
+        this.safeEmit({ kind: "payment-failed", reason });
+        throw new (0, _chunkJG6KRAW6cjs.PaymentDeclinedError)(reason);
       }
       accept = plan.best.accept;
       quote = plan.best.quote;
@@ -3502,10 +3504,10 @@ var PipRailClient = (_class2 = class {
    *  TERMINAL expiry/approval decline it must not retry) without parsing prose. */
   async authorize(quote) {
     if (!quote.withinPolicy) {
-      throw new (0, _chunkJG6KRAW6cjs.PaymentDeclinedError)(
-        `Payment refused by policy: ${_nullishCoalesce(quote.policyReason, () => ( "not allowed"))}`,
-        { reasonCode: reasonCodeForPolicy(quote.policyCode) }
-      );
+      const reason = `Payment refused by policy: ${_nullishCoalesce(quote.policyReason, () => ( "not allowed"))}`;
+      const reasonCode = reasonCodeForPolicy(quote.policyCode);
+      this.safeEmit({ kind: "payment-failed", reason, code: reasonCode });
+      throw new (0, _chunkJG6KRAW6cjs.PaymentDeclinedError)(reason, { reasonCode });
     }
     const hook = this.opts.onBeforePay;
     if (!hook) return;
@@ -3513,16 +3515,14 @@ var PipRailClient = (_class2 = class {
     try {
       approved = await hook(quote);
     } catch (err) {
-      throw new (0, _chunkJG6KRAW6cjs.PaymentDeclinedError)("onBeforePay threw \u2014 refusing to pay.", {
-        cause: err,
-        reasonCode: "APPROVAL"
-      });
+      const reason = "onBeforePay threw \u2014 refusing to pay.";
+      this.safeEmit({ kind: "payment-failed", reason, code: "APPROVAL" });
+      throw new (0, _chunkJG6KRAW6cjs.PaymentDeclinedError)(reason, { cause: err, reasonCode: "APPROVAL" });
     }
     if (!approved) {
-      throw new (0, _chunkJG6KRAW6cjs.PaymentDeclinedError)(
-        `onBeforePay declined ${quote.amountFormatted} ${_nullishCoalesce(quote.symbol, () => ( ""))}`.trimEnd() + ` on ${quote.network}.`,
-        { reasonCode: "APPROVAL" }
-      );
+      const reason = `onBeforePay declined ${quote.amountFormatted} ${_nullishCoalesce(quote.symbol, () => ( ""))}`.trimEnd() + ` on ${quote.network}.`;
+      this.safeEmit({ kind: "payment-failed", reason, code: "APPROVAL" });
+      throw new (0, _chunkJG6KRAW6cjs.PaymentDeclinedError)(reason, { reasonCode: "APPROVAL" });
     }
   }
   /** Record a settled payment in the ledger (true decimals for the running total). */
@@ -3617,7 +3617,8 @@ var PipRailClient = (_class2 = class {
     const unconfirmedNote = confirmed ? "" : " (broadcast but NOT locally confirmed \u2014 it may still have settled on-chain)";
     this.safeEmit({
       kind: "payment-failed",
-      reason: `server returned 402 after broadcasting payment ${ref}${unconfirmedNote} (${why})`
+      reason: `server returned 402 after broadcasting payment ${ref}${unconfirmedNote} (${why})`,
+      ...lastReason ? { code: lastReason.error, detail: lastReason.detail } : {}
     });
     throw new (0, _chunkJG6KRAW6cjs.MaxRetriesExceededError)(
       `Server still returned 402 after ${attempts} attempt(s) with on-chain proof ref=${ref}${unconfirmedNote}. Last server rejection: ${why}. Re-verify or re-submit ref=${ref} before retrying \u2014 never re-pay (it would double-spend).`,
@@ -3652,7 +3653,7 @@ var PipRailClient = (_class2 = class {
     const headers = new Headers(_optionalChain([init, 'optionalAccess', _49 => _49.headers]));
     headers.set(HEADER_SIGNATURE, buildExactSignatureHeader({ accepted, payload }));
     const rejectDefinitive = (why2) => {
-      this.safeEmit({ kind: "payment-failed", reason: `exact: facilitator rejected nonce=${nonce} (${why2})` });
+      this.safeEmit({ kind: "payment-failed", reason: `exact: facilitator rejected nonce=${nonce} (${why2})`, code: why2 });
       throw new (0, _chunkJG6KRAW6cjs.MaxRetriesExceededError)(
         `exact: the facilitator rejected the payment (${why2}). Fix the cause, then re-present the SAME signed authorization (nonce=${nonce}) \u2014 do NOT re-sign a fresh nonce. ref=${nonce}.`,
         { ref: nonce }
@@ -3707,7 +3708,8 @@ var PipRailClient = (_class2 = class {
     const why = lastReason ? `${lastReason.error}${lastReason.detail ? ` \u2014 ${lastReason.detail}` : ""}` : "server gave no reason";
     this.safeEmit({
       kind: "payment-failed",
-      reason: `exact: 402 after submitting authorization nonce=${nonce} (${why})`
+      reason: `exact: 402 after submitting authorization nonce=${nonce} (${why})`,
+      ...lastReason ? { code: lastReason.error, detail: lastReason.detail } : {}
     });
     throw new (0, _chunkJG6KRAW6cjs.MaxRetriesExceededError)(
       `exact: server still returned 402 after submitting the signed authorization (nonce=${nonce}). Last rejection: ${why}. Re-present the SAME authorization \u2014 do NOT re-sign a fresh nonce; verify authorizationState(${payerFrom}, ${nonce}) first. ref=${nonce}.`,
@@ -5260,6 +5262,7 @@ function normaliseExactOption(exact) {
   if (exact === true) return { settle: "keyless" };
   return exact;
 }
+var TRANSIENT_VERIFY_CODES = /* @__PURE__ */ new Set(["tx_not_found", "insufficient_confirmations"]);
 function createPaymentGate(options) {
   const minConfirmations = _nullishCoalesce(options.minConfirmations, () => ( 1));
   const maxTimeoutSeconds = _nullishCoalesce(options.maxTimeoutSeconds, () => ( 600));
@@ -5544,6 +5547,32 @@ function createPaymentGate(options) {
     if (options.awaitOnPaid) await fireOnPaid(paid);
     else void fireOnPaid(paid);
   }
+  function reportOnFailedError(error, failure) {
+    if (!options.onFailedError) return;
+    try {
+      options.onFailedError(error, failure);
+    } catch (e38) {
+    }
+  }
+  function fireOnFailed(failure) {
+    if (!options.onFailed) return;
+    let outcome;
+    try {
+      outcome = options.onFailed(failure);
+    } catch (err) {
+      reportOnFailedError(err, failure);
+      return;
+    }
+    if (outcome != null && typeof outcome.then === "function") {
+      return Promise.resolve(outcome).catch((err) => reportOnFailedError(err, failure));
+    }
+  }
+  async function deliverOnFailed(result) {
+    const code = result.error;
+    const failure = { code, detail: result.detail, transient: TRANSIENT_VERIFY_CODES.has(code) };
+    if (options.awaitOnFailed) await fireOnFailed(failure);
+    else void fireOnFailed(failure);
+  }
   async function describe(resourceUrl = "") {
     const specs = await ready();
     const accepts = [];
@@ -5622,28 +5651,28 @@ function createPaymentGate(options) {
       nonce = [exact.payload.transaction, exact.payload.senderAuth].map((t) => {
         try {
           return Buffer.from(t, "base64").toString("base64");
-        } catch (e38) {
+        } catch (e39) {
           return t;
         }
       }).join("|");
     } else if ("transaction" in exact.payload) {
       try {
         nonce = Buffer.from(exact.payload.transaction, "base64").toString("base64");
-      } catch (e39) {
+      } catch (e40) {
         nonce = exact.payload.transaction;
       }
     } else if ("paymentGroup" in exact.payload) {
       nonce = exact.payload.paymentGroup.map((t) => {
         try {
           return Buffer.from(t, "base64").toString("base64");
-        } catch (e40) {
+        } catch (e41) {
           return t;
         }
       }).join("|");
     } else if ("signedDelegateAction" in exact.payload) {
       try {
         nonce = Buffer.from(exact.payload.signedDelegateAction, "base64").toString("base64");
-      } catch (e41) {
+      } catch (e42) {
         nonce = exact.payload.signedDelegateAction;
       }
     } else if ("permit2Authorization" in exact.payload) {
@@ -5707,6 +5736,11 @@ function createPaymentGate(options) {
     return { kind: "paid", receipt: result.receipt, receiptHeader: buildReceiptHeader(result.receipt) };
   }
   async function verify(paymentSignature) {
+    const result = await resolveVerdict(paymentSignature);
+    if (result.kind === "invalid") await deliverOnFailed(result);
+    return result;
+  }
+  async function resolveVerdict(paymentSignature) {
     const raw = normaliseHeader(paymentSignature);
     if (!raw) return asChallenge();
     const sig = parseSignatureHeader(raw);
@@ -5784,7 +5818,7 @@ async function signBody(secret, body) {
     const sig = await subtle.sign("HMAC", key, enc.encode(body));
     const hex = Array.from(new Uint8Array(sig)).map((b) => b.toString(16).padStart(2, "0")).join("");
     return `sha256=${hex}`;
-  } catch (e42) {
+  } catch (e43) {
     return null;
   }
 }
@@ -5845,7 +5879,7 @@ async function deliverReceipt(receipt, options) {
     const willRetry = !ok && retryable && attempt < maxAttempts;
     try {
       _optionalChain([onAttempt, 'optionalCall', _91 => _91({ attempt, ok, ...status !== void 0 ? { status } : {}, ...error ? { error } : {}, willRetry })]);
-    } catch (e43) {
+    } catch (e44) {
     }
     if (ok) return { delivered: true, attempts: attempt, status };
     if (!willRetry) {

package/dist/index.d.cts

@@ -5044,6 +5044,14 @@ type PipRailEvent = {
 } | {
     kind: 'payment-failed';
     reason: string;
+    /** A machine-readable failure code when one is known. For a SERVER rejection it's the SAME
+     *  code the merchant's `onFailed` hook receives (a canonical {@link VerifyErrorCode} from a
+     *  PipRail gate, or a foreign facilitator's reason string); for a pre-send client DECLINE
+     *  (policy / budget / approval) it's that decline reason (e.g. `'BUDGET'`, `'APPROVAL'`).
+     *  Absent when no structured code was given. */
+    code?: string;
+    /** Human-readable detail, when present (e.g. `"Paid 40000, required 500000."`). */
+    detail?: string;
 };
 /**
  * Wallet for the chosen chain family. **One field, every chain: `{ key }`** — the
@@ -6463,6 +6471,28 @@ interface ExactRailOption {
      *  "just works". Force `'eip3009'` or `'permit2'` to pin one. Ignored on Solana (always SVM). */
     method?: 'eip3009' | 'permit2' | 'auto';
 }
+/**
+ * The merchant-side mirror of {@link PaidReceipt}: what an {@link RequirePaymentOptions.onFailed}
+ * hook receives when a SUBMITTED payment proof is REJECTED. It carries the SAME machine-readable
+ * `code` the buyer's client is given for that rejection, so both sides are notified of one
+ * consistent reason. (A rejection has no settlement, so — unlike a receipt — there is no tx hash
+ * or settled amount to report.)
+ */
+interface FailedPayment {
+    /** The canonical rejection reason — the same {@link VerifyErrorCode} surfaced to the buyer
+     *  (e.g. `amount_too_low`, `payment_expired`, `tx_already_used`, `transfer_not_found`). */
+    code: VerifyErrorCode;
+    /** Human-readable detail, e.g. `"Paid 40000, required 500000."`. */
+    detail: string;
+    /**
+     * `true` for a **transient** rejection (`tx_not_found` / `insufficient_confirmations`): the proof
+     * may still be settling and the buyer's client **retries automatically** — you'll get `onPaid` if
+     * it then succeeds. `false` for a **definitive** rejection the buyer must fix (wrong amount,
+     * expired, replayed, bad signature, wrong recipient). Alert on `!transient` to avoid false alarms
+     * on normal RPC lag; nothing is hidden — every rejected attempt still fires `onFailed`.
+     */
+    transient: boolean;
+}
 interface RequirePaymentOptions {
     /**
      * Single-chain form: which chain to accept payment on. EVM ('bnb'|'base'|…),
@@ -6535,6 +6565,37 @@ interface RequirePaymentOptions {
      * via `onPaidError`; it never turns a settled payment into a 402.
      */
     awaitOnPaid?: boolean;
+    /**
+     * The merchant-side mirror of `onPaid`: fired when a SUBMITTED payment proof is REJECTED — a
+     * `kind:'invalid'` verdict (wrong amount, expired, replayed, unknown asset, …). Receives a
+     * {@link FailedPayment} carrying the SAME machine `code` the buyer's client is given, so the
+     * merchant and the buyer are notified of the same failure with the same reason.
+     *
+     * Fires ONLY on a rejected attempt — NOT on a normal first-request 402 `challenge` (no proof
+     * yet), and NOT on a transient/settlement error that throws (an RPC blip, or a 5xx
+     * `SettlementError`): those aren't payment verdicts. Like `onPaid`, it may be **sync or async**
+     * and is fully isolated — a throw OR a rejected promise is caught and routed to `onFailedError`,
+     * so it can never break the request or crash the process. Fire-and-forget by default; set
+     * `awaitOnFailed` to run it before the 402 is returned.
+     *
+     * NOTE: a failure the merchant never receives a request for — the buyer can't afford it, an
+     * `onBeforePay`/`policy` declines it, or the buyer abandons before paying — cannot reach a
+     * backendless gate (only the buyer's client sees it). `onFailed` covers every rejection that
+     * DOES reach the gate.
+     */
+    onFailed?: (failure: FailedPayment) => void | Promise<void>;
+    /**
+     * Observe a failure inside `onFailed` (sync throw or async rejection) — the mirror of
+     * `onPaidError`. Without it, a throwing `onFailed` is swallowed silently. Its own throws are
+     * also swallowed (it can never break a request).
+     */
+    onFailedError?: (error: unknown, failure: FailedPayment) => void;
+    /**
+     * Await `onFailed` before the 402 rejection is returned (mirror of `awaitOnPaid`), so
+     * "failure recorded" is guaranteed before the caller is told. Default `false` (fire-and-forget).
+     * A rejection inside the hook is still isolated via `onFailedError`.
+     */
+    awaitOnFailed?: boolean;
     /**
      * ALSO advertise a standard x402 `exact` rail so any standard x402 client can pay this
      * gate — opt-in, EVM (EIP-3009/Permit2) + Solana (SVM). See {@link ExactRailOption}.
@@ -6639,15 +6700,6 @@ interface PaymentGate {
      */
     landingPage(challenge: X402Challenge): string;
 }
-/**
- * Framework-agnostic core. Build one gate per gated resource and reuse it
- * — its in-memory used-tx set is what stops the same proof being redeemed
- * twice. Wrap it for Express with `requirePayment`, or call it directly
- * from Hono / Fastify / Adonis / Workers / etc.
- *
- * The chain's driver is resolved lazily on first `challenge()`/`verify()`,
- * which is what lets Solana (and future families) auto-mount with no setup.
- */
 declare function createPaymentGate(options: RequirePaymentOptions): PaymentGate;
 interface ExpressLikeRequest {
     headers: Record<string, string | string[] | undefined>;
@@ -7527,4 +7579,4 @@ declare const PERMIT2_WITNESS_TYPES: {
  */
 declare function renderLandingPage(sd: SelfDescription): string;
 
-export { type AcceptOption, type AddressId, type AgentTool, type AlgorandToken, type AptosToken, type AssetId, BRAND, type BazaarExtension, type BuildExactParams, CHAINS, type Caip2, type ChainFamily, type ChainInput, type ChainName, type ChainPreset, type ChainSelector, type ChallengeTriage, type ChallengeVerdict, type ConfirmInfo, ConfirmationTimeoutError, type CostEstimate, DIRECTORY_INFO, type DeclineReasonCode, type DeliverAttempt, type DeliverReceiptOptions, type DeliverResult, type DirectoryInfo, type DiscoverOptions, type DiscoveredRail, type DiscoveredResource, type DiscoveryDescriptor, type DiscoverySigner, type DiscoverySort, type DiscoverySource, type DomainClaim, type DomainVerification, EIP3009_TYPES, EXACT_NETWORK_SLUGS, type EvmToken, type ExactAccept, type ExactAuthorization, type ExactAuthorizationWire, type ExactPaymentPayload, type ExactPaymentPayloadAny, type ExactRailOption, type ExpressLikeMiddleware, type ExpressLikeNext, type ExpressLikeRequest, type ExpressLikeResponse, type FacilitatorConfig, type FacilitatorPaymentRequirements, type FacilitatorSupportedKind, GENERATOR, HEADER_REQUIRED, HEADER_RESPONSE, HEADER_RESPONSE_V1, HEADER_SIGNATURE, HEADER_SIGNATURE_V1, InsufficientFundsError, InvalidEnvelopeError, KNOWN_FACILITATORS, type KnownFacilitator, type ListingVisibility, type ManifestInput, MaxRetriesExceededError, MissingDriverError, MultiChainPayer, type MultiChainPayerOptions, type NearToken, NoCompatibleAcceptError, NonReplayableBodyError, type OpenApiDocument, type OpenApiOperation, PERMIT2_ADDRESS, PERMIT2_PROXY_CHAIN_IDS, PERMIT2_WITNESS_TYPES, PIPRAIL_AGENT_GUIDE, POWERED_BY, type PaidReceipt, type ParsedExactPayment, type PayBlocker, type PayOption, type PayWarning, type PayingClient, PaymentDeclinedError, type PaymentDriver, type PaymentGate, type PaymentIntent, type PaymentPlan, type PaymentPolicy, type PaymentRail, type PaymentScheme, PaymentTimeoutError, type Permit2Authorization, type Permit2PaymentPayload, PipRailClient, type PipRailClientOptions, type PipRailCostQuote, PipRailError, type PipRailEvent, type PipRailQuote, type PolicyDecision, type PolicyDenyCode, REGISTER_ATTRIBUTION, RecipientNotReadyError, type RecipientReason, type RegisterInput, type RegisterOptions, type RegisterOutcome, type RequirePaymentOptions, type ResolveOptions, type ResolvedChain, type ResolvedNetwork, type ResolvedToken, type ResourceDescription, type SearchOpenIndexesOptions, type SelfDescribeEndpoint, type SelfDescribeRail, type SelfDescription, type SessionBudget, type SettleOutcome, type SettleViaFacilitatorInput, SettlementError, type SolanaToken, type SpendAssetTotal, type SpendRecord, type SpendRemaining, type SpendSummary, type StellarToken, type SuiToken, type TokenInfo, type TokenInput, type TonToken, type ToolAnnotations, type TronToken, UnknownTokenError, UnsupportedNetworkError, UnsupportedSchemeError, type VerifyErrorCode, type VerifyPaymentResult, type VerifyResult, type WalletBalance, type WalletHandle, type WalletInput, WalletRequiredError, type WellKnownX402, WrongChainError, WrongFamilyError, type X402AcceptEntry, type X402AnyAccept, type X402Challenge, type X402DnsRecord, type X402ExactAcceptEntry, type X402InvalidBody, type X402PaymentSignature, type X402Receipt, type X402ResourceObject, X402_EXACT_PERMIT2_PROXY, type XrplToken, agentGuide, appendAttribution, appendKeywords, buildBazaarExtension, buildChallengeHeader, buildEndpointInfo, buildExactAuthorization, buildExactSignatureHeader, buildOpenApi, buildReceiptHeader, buildSelfDescription, buildSignatureHeader, buildWellKnownX402, buildX402DnsTxt, chainIdForExactNetwork, claim402IndexDomain, classifyChallenge, createPaymentGate, decorateOutcome, deliverReceipt, describeChallenge, discoveryHeaders, eip3009Abi, encodeXPaymentHeader, evaluatePolicy, explainDecline, facilitatorCoverage, fetchAcross, firstKeylessFacilitator, formatSpendReport, getDirectoryInfo, isPermit2ProxyChain, knownFacilitatorsFor, normalizeNetwork, parseChallenge, parseExactPaymentHeader, parseExactRequirements, parseFacilitatorSupported, parseReceipt, parseSettleResponse, parseSignatureHeader, paymentTools, pickAccept, planAcross, rankResources, readExactDomain, register402Index, registerDriver, registerX402Scan, renderLandingPage, requirePayment, resolveChain, scoreResource, searchOpenIndexes, settleViaFacilitator, summarizePlan, toInsufficientFundsError, toInvalidBody, verify402IndexDomain };
+export { type AcceptOption, type AddressId, type AgentTool, type AlgorandToken, type AptosToken, type AssetId, BRAND, type BazaarExtension, type BuildExactParams, CHAINS, type Caip2, type ChainFamily, type ChainInput, type ChainName, type ChainPreset, type ChainSelector, type ChallengeTriage, type ChallengeVerdict, type ConfirmInfo, ConfirmationTimeoutError, type CostEstimate, DIRECTORY_INFO, type DeclineReasonCode, type DeliverAttempt, type DeliverReceiptOptions, type DeliverResult, type DirectoryInfo, type DiscoverOptions, type DiscoveredRail, type DiscoveredResource, type DiscoveryDescriptor, type DiscoverySigner, type DiscoverySort, type DiscoverySource, type DomainClaim, type DomainVerification, EIP3009_TYPES, EXACT_NETWORK_SLUGS, type EvmToken, type ExactAccept, type ExactAuthorization, type ExactAuthorizationWire, type ExactPaymentPayload, type ExactPaymentPayloadAny, type ExactRailOption, type ExpressLikeMiddleware, type ExpressLikeNext, type ExpressLikeRequest, type ExpressLikeResponse, type FacilitatorConfig, type FacilitatorPaymentRequirements, type FacilitatorSupportedKind, type FailedPayment, GENERATOR, HEADER_REQUIRED, HEADER_RESPONSE, HEADER_RESPONSE_V1, HEADER_SIGNATURE, HEADER_SIGNATURE_V1, InsufficientFundsError, InvalidEnvelopeError, KNOWN_FACILITATORS, type KnownFacilitator, type ListingVisibility, type ManifestInput, MaxRetriesExceededError, MissingDriverError, MultiChainPayer, type MultiChainPayerOptions, type NearToken, NoCompatibleAcceptError, NonReplayableBodyError, type OpenApiDocument, type OpenApiOperation, PERMIT2_ADDRESS, PERMIT2_PROXY_CHAIN_IDS, PERMIT2_WITNESS_TYPES, PIPRAIL_AGENT_GUIDE, POWERED_BY, type PaidReceipt, type ParsedExactPayment, type PayBlocker, type PayOption, type PayWarning, type PayingClient, PaymentDeclinedError, type PaymentDriver, type PaymentGate, type PaymentIntent, type PaymentPlan, type PaymentPolicy, type PaymentRail, type PaymentScheme, PaymentTimeoutError, type Permit2Authorization, type Permit2PaymentPayload, PipRailClient, type PipRailClientOptions, type PipRailCostQuote, PipRailError, type PipRailEvent, type PipRailQuote, type PolicyDecision, type PolicyDenyCode, REGISTER_ATTRIBUTION, RecipientNotReadyError, type RecipientReason, type RegisterInput, type RegisterOptions, type RegisterOutcome, type RequirePaymentOptions, type ResolveOptions, type ResolvedChain, type ResolvedNetwork, type ResolvedToken, type ResourceDescription, type SearchOpenIndexesOptions, type SelfDescribeEndpoint, type SelfDescribeRail, type SelfDescription, type SessionBudget, type SettleOutcome, type SettleViaFacilitatorInput, SettlementError, type SolanaToken, type SpendAssetTotal, type SpendRecord, type SpendRemaining, type SpendSummary, type StellarToken, type SuiToken, type TokenInfo, type TokenInput, type TonToken, type ToolAnnotations, type TronToken, UnknownTokenError, UnsupportedNetworkError, UnsupportedSchemeError, type VerifyErrorCode, type VerifyPaymentResult, type VerifyResult, type WalletBalance, type WalletHandle, type WalletInput, WalletRequiredError, type WellKnownX402, WrongChainError, WrongFamilyError, type X402AcceptEntry, type X402AnyAccept, type X402Challenge, type X402DnsRecord, type X402ExactAcceptEntry, type X402InvalidBody, type X402PaymentSignature, type X402Receipt, type X402ResourceObject, X402_EXACT_PERMIT2_PROXY, type XrplToken, agentGuide, appendAttribution, appendKeywords, buildBazaarExtension, buildChallengeHeader, buildEndpointInfo, buildExactAuthorization, buildExactSignatureHeader, buildOpenApi, buildReceiptHeader, buildSelfDescription, buildSignatureHeader, buildWellKnownX402, buildX402DnsTxt, chainIdForExactNetwork, claim402IndexDomain, classifyChallenge, createPaymentGate, decorateOutcome, deliverReceipt, describeChallenge, discoveryHeaders, eip3009Abi, encodeXPaymentHeader, evaluatePolicy, explainDecline, facilitatorCoverage, fetchAcross, firstKeylessFacilitator, formatSpendReport, getDirectoryInfo, isPermit2ProxyChain, knownFacilitatorsFor, normalizeNetwork, parseChallenge, parseExactPaymentHeader, parseExactRequirements, parseFacilitatorSupported, parseReceipt, parseSettleResponse, parseSignatureHeader, paymentTools, pickAccept, planAcross, rankResources, readExactDomain, register402Index, registerDriver, registerX402Scan, renderLandingPage, requirePayment, resolveChain, scoreResource, searchOpenIndexes, settleViaFacilitator, summarizePlan, toInsufficientFundsError, toInvalidBody, verify402IndexDomain };

package/dist/index.d.ts

@@ -5044,6 +5044,14 @@ type PipRailEvent = {
 } | {
     kind: 'payment-failed';
     reason: string;
+    /** A machine-readable failure code when one is known. For a SERVER rejection it's the SAME
+     *  code the merchant's `onFailed` hook receives (a canonical {@link VerifyErrorCode} from a
+     *  PipRail gate, or a foreign facilitator's reason string); for a pre-send client DECLINE
+     *  (policy / budget / approval) it's that decline reason (e.g. `'BUDGET'`, `'APPROVAL'`).
+     *  Absent when no structured code was given. */
+    code?: string;
+    /** Human-readable detail, when present (e.g. `"Paid 40000, required 500000."`). */
+    detail?: string;
 };
 /**
  * Wallet for the chosen chain family. **One field, every chain: `{ key }`** — the
@@ -6463,6 +6471,28 @@ interface ExactRailOption {
      *  "just works". Force `'eip3009'` or `'permit2'` to pin one. Ignored on Solana (always SVM). */
     method?: 'eip3009' | 'permit2' | 'auto';
 }
+/**
+ * The merchant-side mirror of {@link PaidReceipt}: what an {@link RequirePaymentOptions.onFailed}
+ * hook receives when a SUBMITTED payment proof is REJECTED. It carries the SAME machine-readable
+ * `code` the buyer's client is given for that rejection, so both sides are notified of one
+ * consistent reason. (A rejection has no settlement, so — unlike a receipt — there is no tx hash
+ * or settled amount to report.)
+ */
+interface FailedPayment {
+    /** The canonical rejection reason — the same {@link VerifyErrorCode} surfaced to the buyer
+     *  (e.g. `amount_too_low`, `payment_expired`, `tx_already_used`, `transfer_not_found`). */
+    code: VerifyErrorCode;
+    /** Human-readable detail, e.g. `"Paid 40000, required 500000."`. */
+    detail: string;
+    /**
+     * `true` for a **transient** rejection (`tx_not_found` / `insufficient_confirmations`): the proof
+     * may still be settling and the buyer's client **retries automatically** — you'll get `onPaid` if
+     * it then succeeds. `false` for a **definitive** rejection the buyer must fix (wrong amount,
+     * expired, replayed, bad signature, wrong recipient). Alert on `!transient` to avoid false alarms
+     * on normal RPC lag; nothing is hidden — every rejected attempt still fires `onFailed`.
+     */
+    transient: boolean;
+}
 interface RequirePaymentOptions {
     /**
      * Single-chain form: which chain to accept payment on. EVM ('bnb'|'base'|…),
@@ -6535,6 +6565,37 @@ interface RequirePaymentOptions {
      * via `onPaidError`; it never turns a settled payment into a 402.
      */
     awaitOnPaid?: boolean;
+    /**
+     * The merchant-side mirror of `onPaid`: fired when a SUBMITTED payment proof is REJECTED — a
+     * `kind:'invalid'` verdict (wrong amount, expired, replayed, unknown asset, …). Receives a
+     * {@link FailedPayment} carrying the SAME machine `code` the buyer's client is given, so the
+     * merchant and the buyer are notified of the same failure with the same reason.
+     *
+     * Fires ONLY on a rejected attempt — NOT on a normal first-request 402 `challenge` (no proof
+     * yet), and NOT on a transient/settlement error that throws (an RPC blip, or a 5xx
+     * `SettlementError`): those aren't payment verdicts. Like `onPaid`, it may be **sync or async**
+     * and is fully isolated — a throw OR a rejected promise is caught and routed to `onFailedError`,
+     * so it can never break the request or crash the process. Fire-and-forget by default; set
+     * `awaitOnFailed` to run it before the 402 is returned.
+     *
+     * NOTE: a failure the merchant never receives a request for — the buyer can't afford it, an
+     * `onBeforePay`/`policy` declines it, or the buyer abandons before paying — cannot reach a
+     * backendless gate (only the buyer's client sees it). `onFailed` covers every rejection that
+     * DOES reach the gate.
+     */
+    onFailed?: (failure: FailedPayment) => void | Promise<void>;
+    /**
+     * Observe a failure inside `onFailed` (sync throw or async rejection) — the mirror of
+     * `onPaidError`. Without it, a throwing `onFailed` is swallowed silently. Its own throws are
+     * also swallowed (it can never break a request).
+     */
+    onFailedError?: (error: unknown, failure: FailedPayment) => void;
+    /**
+     * Await `onFailed` before the 402 rejection is returned (mirror of `awaitOnPaid`), so
+     * "failure recorded" is guaranteed before the caller is told. Default `false` (fire-and-forget).
+     * A rejection inside the hook is still isolated via `onFailedError`.
+     */
+    awaitOnFailed?: boolean;
     /**
      * ALSO advertise a standard x402 `exact` rail so any standard x402 client can pay this
      * gate — opt-in, EVM (EIP-3009/Permit2) + Solana (SVM). See {@link ExactRailOption}.
@@ -6639,15 +6700,6 @@ interface PaymentGate {
      */
     landingPage(challenge: X402Challenge): string;
 }
-/**
- * Framework-agnostic core. Build one gate per gated resource and reuse it
- * — its in-memory used-tx set is what stops the same proof being redeemed
- * twice. Wrap it for Express with `requirePayment`, or call it directly
- * from Hono / Fastify / Adonis / Workers / etc.
- *
- * The chain's driver is resolved lazily on first `challenge()`/`verify()`,
- * which is what lets Solana (and future families) auto-mount with no setup.
- */
 declare function createPaymentGate(options: RequirePaymentOptions): PaymentGate;
 interface ExpressLikeRequest {
     headers: Record<string, string | string[] | undefined>;
@@ -7527,4 +7579,4 @@ declare const PERMIT2_WITNESS_TYPES: {
  */
 declare function renderLandingPage(sd: SelfDescription): string;
 
-export { type AcceptOption, type AddressId, type AgentTool, type AlgorandToken, type AptosToken, type AssetId, BRAND, type BazaarExtension, type BuildExactParams, CHAINS, type Caip2, type ChainFamily, type ChainInput, type ChainName, type ChainPreset, type ChainSelector, type ChallengeTriage, type ChallengeVerdict, type ConfirmInfo, ConfirmationTimeoutError, type CostEstimate, DIRECTORY_INFO, type DeclineReasonCode, type DeliverAttempt, type DeliverReceiptOptions, type DeliverResult, type DirectoryInfo, type DiscoverOptions, type DiscoveredRail, type DiscoveredResource, type DiscoveryDescriptor, type DiscoverySigner, type DiscoverySort, type DiscoverySource, type DomainClaim, type DomainVerification, EIP3009_TYPES, EXACT_NETWORK_SLUGS, type EvmToken, type ExactAccept, type ExactAuthorization, type ExactAuthorizationWire, type ExactPaymentPayload, type ExactPaymentPayloadAny, type ExactRailOption, type ExpressLikeMiddleware, type ExpressLikeNext, type ExpressLikeRequest, type ExpressLikeResponse, type FacilitatorConfig, type FacilitatorPaymentRequirements, type FacilitatorSupportedKind, GENERATOR, HEADER_REQUIRED, HEADER_RESPONSE, HEADER_RESPONSE_V1, HEADER_SIGNATURE, HEADER_SIGNATURE_V1, InsufficientFundsError, InvalidEnvelopeError, KNOWN_FACILITATORS, type KnownFacilitator, type ListingVisibility, type ManifestInput, MaxRetriesExceededError, MissingDriverError, MultiChainPayer, type MultiChainPayerOptions, type NearToken, NoCompatibleAcceptError, NonReplayableBodyError, type OpenApiDocument, type OpenApiOperation, PERMIT2_ADDRESS, PERMIT2_PROXY_CHAIN_IDS, PERMIT2_WITNESS_TYPES, PIPRAIL_AGENT_GUIDE, POWERED_BY, type PaidReceipt, type ParsedExactPayment, type PayBlocker, type PayOption, type PayWarning, type PayingClient, PaymentDeclinedError, type PaymentDriver, type PaymentGate, type PaymentIntent, type PaymentPlan, type PaymentPolicy, type PaymentRail, type PaymentScheme, PaymentTimeoutError, type Permit2Authorization, type Permit2PaymentPayload, PipRailClient, type PipRailClientOptions, type PipRailCostQuote, PipRailError, type PipRailEvent, type PipRailQuote, type PolicyDecision, type PolicyDenyCode, REGISTER_ATTRIBUTION, RecipientNotReadyError, type RecipientReason, type RegisterInput, type RegisterOptions, type RegisterOutcome, type RequirePaymentOptions, type ResolveOptions, type ResolvedChain, type ResolvedNetwork, type ResolvedToken, type ResourceDescription, type SearchOpenIndexesOptions, type SelfDescribeEndpoint, type SelfDescribeRail, type SelfDescription, type SessionBudget, type SettleOutcome, type SettleViaFacilitatorInput, SettlementError, type SolanaToken, type SpendAssetTotal, type SpendRecord, type SpendRemaining, type SpendSummary, type StellarToken, type SuiToken, type TokenInfo, type TokenInput, type TonToken, type ToolAnnotations, type TronToken, UnknownTokenError, UnsupportedNetworkError, UnsupportedSchemeError, type VerifyErrorCode, type VerifyPaymentResult, type VerifyResult, type WalletBalance, type WalletHandle, type WalletInput, WalletRequiredError, type WellKnownX402, WrongChainError, WrongFamilyError, type X402AcceptEntry, type X402AnyAccept, type X402Challenge, type X402DnsRecord, type X402ExactAcceptEntry, type X402InvalidBody, type X402PaymentSignature, type X402Receipt, type X402ResourceObject, X402_EXACT_PERMIT2_PROXY, type XrplToken, agentGuide, appendAttribution, appendKeywords, buildBazaarExtension, buildChallengeHeader, buildEndpointInfo, buildExactAuthorization, buildExactSignatureHeader, buildOpenApi, buildReceiptHeader, buildSelfDescription, buildSignatureHeader, buildWellKnownX402, buildX402DnsTxt, chainIdForExactNetwork, claim402IndexDomain, classifyChallenge, createPaymentGate, decorateOutcome, deliverReceipt, describeChallenge, discoveryHeaders, eip3009Abi, encodeXPaymentHeader, evaluatePolicy, explainDecline, facilitatorCoverage, fetchAcross, firstKeylessFacilitator, formatSpendReport, getDirectoryInfo, isPermit2ProxyChain, knownFacilitatorsFor, normalizeNetwork, parseChallenge, parseExactPaymentHeader, parseExactRequirements, parseFacilitatorSupported, parseReceipt, parseSettleResponse, parseSignatureHeader, paymentTools, pickAccept, planAcross, rankResources, readExactDomain, register402Index, registerDriver, registerX402Scan, renderLandingPage, requirePayment, resolveChain, scoreResource, searchOpenIndexes, settleViaFacilitator, summarizePlan, toInsufficientFundsError, toInvalidBody, verify402IndexDomain };
+export { type AcceptOption, type AddressId, type AgentTool, type AlgorandToken, type AptosToken, type AssetId, BRAND, type BazaarExtension, type BuildExactParams, CHAINS, type Caip2, type ChainFamily, type ChainInput, type ChainName, type ChainPreset, type ChainSelector, type ChallengeTriage, type ChallengeVerdict, type ConfirmInfo, ConfirmationTimeoutError, type CostEstimate, DIRECTORY_INFO, type DeclineReasonCode, type DeliverAttempt, type DeliverReceiptOptions, type DeliverResult, type DirectoryInfo, type DiscoverOptions, type DiscoveredRail, type DiscoveredResource, type DiscoveryDescriptor, type DiscoverySigner, type DiscoverySort, type DiscoverySource, type DomainClaim, type DomainVerification, EIP3009_TYPES, EXACT_NETWORK_SLUGS, type EvmToken, type ExactAccept, type ExactAuthorization, type ExactAuthorizationWire, type ExactPaymentPayload, type ExactPaymentPayloadAny, type ExactRailOption, type ExpressLikeMiddleware, type ExpressLikeNext, type ExpressLikeRequest, type ExpressLikeResponse, type FacilitatorConfig, type FacilitatorPaymentRequirements, type FacilitatorSupportedKind, type FailedPayment, GENERATOR, HEADER_REQUIRED, HEADER_RESPONSE, HEADER_RESPONSE_V1, HEADER_SIGNATURE, HEADER_SIGNATURE_V1, InsufficientFundsError, InvalidEnvelopeError, KNOWN_FACILITATORS, type KnownFacilitator, type ListingVisibility, type ManifestInput, MaxRetriesExceededError, MissingDriverError, MultiChainPayer, type MultiChainPayerOptions, type NearToken, NoCompatibleAcceptError, NonReplayableBodyError, type OpenApiDocument, type OpenApiOperation, PERMIT2_ADDRESS, PERMIT2_PROXY_CHAIN_IDS, PERMIT2_WITNESS_TYPES, PIPRAIL_AGENT_GUIDE, POWERED_BY, type PaidReceipt, type ParsedExactPayment, type PayBlocker, type PayOption, type PayWarning, type PayingClient, PaymentDeclinedError, type PaymentDriver, type PaymentGate, type PaymentIntent, type PaymentPlan, type PaymentPolicy, type PaymentRail, type PaymentScheme, PaymentTimeoutError, type Permit2Authorization, type Permit2PaymentPayload, PipRailClient, type PipRailClientOptions, type PipRailCostQuote, PipRailError, type PipRailEvent, type PipRailQuote, type PolicyDecision, type PolicyDenyCode, REGISTER_ATTRIBUTION, RecipientNotReadyError, type RecipientReason, type RegisterInput, type RegisterOptions, type RegisterOutcome, type RequirePaymentOptions, type ResolveOptions, type ResolvedChain, type ResolvedNetwork, type ResolvedToken, type ResourceDescription, type SearchOpenIndexesOptions, type SelfDescribeEndpoint, type SelfDescribeRail, type SelfDescription, type SessionBudget, type SettleOutcome, type SettleViaFacilitatorInput, SettlementError, type SolanaToken, type SpendAssetTotal, type SpendRecord, type SpendRemaining, type SpendSummary, type StellarToken, type SuiToken, type TokenInfo, type TokenInput, type TonToken, type ToolAnnotations, type TronToken, UnknownTokenError, UnsupportedNetworkError, UnsupportedSchemeError, type VerifyErrorCode, type VerifyPaymentResult, type VerifyResult, type WalletBalance, type WalletHandle, type WalletInput, WalletRequiredError, type WellKnownX402, WrongChainError, WrongFamilyError, type X402AcceptEntry, type X402AnyAccept, type X402Challenge, type X402DnsRecord, type X402ExactAcceptEntry, type X402InvalidBody, type X402PaymentSignature, type X402Receipt, type X402ResourceObject, X402_EXACT_PERMIT2_PROXY, type XrplToken, agentGuide, appendAttribution, appendKeywords, buildBazaarExtension, buildChallengeHeader, buildEndpointInfo, buildExactAuthorization, buildExactSignatureHeader, buildOpenApi, buildReceiptHeader, buildSelfDescription, buildSignatureHeader, buildWellKnownX402, buildX402DnsTxt, chainIdForExactNetwork, claim402IndexDomain, classifyChallenge, createPaymentGate, decorateOutcome, deliverReceipt, describeChallenge, discoveryHeaders, eip3009Abi, encodeXPaymentHeader, evaluatePolicy, explainDecline, facilitatorCoverage, fetchAcross, firstKeylessFacilitator, formatSpendReport, getDirectoryInfo, isPermit2ProxyChain, knownFacilitatorsFor, normalizeNetwork, parseChallenge, parseExactPaymentHeader, parseExactRequirements, parseFacilitatorSupported, parseReceipt, parseSettleResponse, parseSignatureHeader, paymentTools, pickAccept, planAcross, rankResources, readExactDomain, register402Index, registerDriver, registerX402Scan, renderLandingPage, requirePayment, resolveChain, scoreResource, searchOpenIndexes, settleViaFacilitator, summarizePlan, toInsufficientFundsError, toInvalidBody, verify402IndexDomain };

package/dist/index.js

@@ -3212,7 +3212,9 @@ var PipRailClient = class {
     if (autoRoute) {
       const plan = await this.planFromChallenge(net, wallet, challenge, url, schemes);
       if (!plan.best) {
-        throw new PaymentDeclinedError(plan.fundingHint ?? "No rail is settleable for this payment.");
+        const reason = plan.fundingHint ?? "No rail is settleable for this payment.";
+        this.safeEmit({ kind: "payment-failed", reason });
+        throw new PaymentDeclinedError(reason);
       }
       accept = plan.best.accept;
       quote = plan.best.quote;
@@ -3502,10 +3504,10 @@ var PipRailClient = class {
    *  TERMINAL expiry/approval decline it must not retry) without parsing prose. */
   async authorize(quote) {
     if (!quote.withinPolicy) {
-      throw new PaymentDeclinedError(
-        `Payment refused by policy: ${quote.policyReason ?? "not allowed"}`,
-        { reasonCode: reasonCodeForPolicy(quote.policyCode) }
-      );
+      const reason = `Payment refused by policy: ${quote.policyReason ?? "not allowed"}`;
+      const reasonCode = reasonCodeForPolicy(quote.policyCode);
+      this.safeEmit({ kind: "payment-failed", reason, code: reasonCode });
+      throw new PaymentDeclinedError(reason, { reasonCode });
     }
     const hook = this.opts.onBeforePay;
     if (!hook) return;
@@ -3513,16 +3515,14 @@ var PipRailClient = class {
     try {
       approved = await hook(quote);
     } catch (err) {
-      throw new PaymentDeclinedError("onBeforePay threw \u2014 refusing to pay.", {
-        cause: err,
-        reasonCode: "APPROVAL"
-      });
+      const reason = "onBeforePay threw \u2014 refusing to pay.";
+      this.safeEmit({ kind: "payment-failed", reason, code: "APPROVAL" });
+      throw new PaymentDeclinedError(reason, { cause: err, reasonCode: "APPROVAL" });
     }
     if (!approved) {
-      throw new PaymentDeclinedError(
-        `onBeforePay declined ${quote.amountFormatted} ${quote.symbol ?? ""}`.trimEnd() + ` on ${quote.network}.`,
-        { reasonCode: "APPROVAL" }
-      );
+      const reason = `onBeforePay declined ${quote.amountFormatted} ${quote.symbol ?? ""}`.trimEnd() + ` on ${quote.network}.`;
+      this.safeEmit({ kind: "payment-failed", reason, code: "APPROVAL" });
+      throw new PaymentDeclinedError(reason, { reasonCode: "APPROVAL" });
     }
   }
   /** Record a settled payment in the ledger (true decimals for the running total). */
@@ -3617,7 +3617,8 @@ var PipRailClient = class {
     const unconfirmedNote = confirmed ? "" : " (broadcast but NOT locally confirmed \u2014 it may still have settled on-chain)";
     this.safeEmit({
       kind: "payment-failed",
-      reason: `server returned 402 after broadcasting payment ${ref}${unconfirmedNote} (${why})`
+      reason: `server returned 402 after broadcasting payment ${ref}${unconfirmedNote} (${why})`,
+      ...lastReason ? { code: lastReason.error, detail: lastReason.detail } : {}
     });
     throw new MaxRetriesExceededError(
       `Server still returned 402 after ${attempts} attempt(s) with on-chain proof ref=${ref}${unconfirmedNote}. Last server rejection: ${why}. Re-verify or re-submit ref=${ref} before retrying \u2014 never re-pay (it would double-spend).`,
@@ -3652,7 +3653,7 @@ var PipRailClient = class {
     const headers = new Headers(init?.headers);
     headers.set(HEADER_SIGNATURE, buildExactSignatureHeader({ accepted, payload }));
     const rejectDefinitive = (why2) => {
-      this.safeEmit({ kind: "payment-failed", reason: `exact: facilitator rejected nonce=${nonce} (${why2})` });
+      this.safeEmit({ kind: "payment-failed", reason: `exact: facilitator rejected nonce=${nonce} (${why2})`, code: why2 });
       throw new MaxRetriesExceededError(
         `exact: the facilitator rejected the payment (${why2}). Fix the cause, then re-present the SAME signed authorization (nonce=${nonce}) \u2014 do NOT re-sign a fresh nonce. ref=${nonce}.`,
         { ref: nonce }
@@ -3707,7 +3708,8 @@ var PipRailClient = class {
     const why = lastReason ? `${lastReason.error}${lastReason.detail ? ` \u2014 ${lastReason.detail}` : ""}` : "server gave no reason";
     this.safeEmit({
       kind: "payment-failed",
-      reason: `exact: 402 after submitting authorization nonce=${nonce} (${why})`
+      reason: `exact: 402 after submitting authorization nonce=${nonce} (${why})`,
+      ...lastReason ? { code: lastReason.error, detail: lastReason.detail } : {}
     });
     throw new MaxRetriesExceededError(
       `exact: server still returned 402 after submitting the signed authorization (nonce=${nonce}). Last rejection: ${why}. Re-present the SAME authorization \u2014 do NOT re-sign a fresh nonce; verify authorizationState(${payerFrom}, ${nonce}) first. ref=${nonce}.`,
@@ -5260,6 +5262,7 @@ function normaliseExactOption(exact) {
   if (exact === true) return { settle: "keyless" };
   return exact;
 }
+var TRANSIENT_VERIFY_CODES = /* @__PURE__ */ new Set(["tx_not_found", "insufficient_confirmations"]);
 function createPaymentGate(options) {
   const minConfirmations = options.minConfirmations ?? 1;
   const maxTimeoutSeconds = options.maxTimeoutSeconds ?? 600;
@@ -5544,6 +5547,32 @@ function createPaymentGate(options) {
     if (options.awaitOnPaid) await fireOnPaid(paid);
     else void fireOnPaid(paid);
   }
+  function reportOnFailedError(error, failure) {
+    if (!options.onFailedError) return;
+    try {
+      options.onFailedError(error, failure);
+    } catch {
+    }
+  }
+  function fireOnFailed(failure) {
+    if (!options.onFailed) return;
+    let outcome;
+    try {
+      outcome = options.onFailed(failure);
+    } catch (err) {
+      reportOnFailedError(err, failure);
+      return;
+    }
+    if (outcome != null && typeof outcome.then === "function") {
+      return Promise.resolve(outcome).catch((err) => reportOnFailedError(err, failure));
+    }
+  }
+  async function deliverOnFailed(result) {
+    const code = result.error;
+    const failure = { code, detail: result.detail, transient: TRANSIENT_VERIFY_CODES.has(code) };
+    if (options.awaitOnFailed) await fireOnFailed(failure);
+    else void fireOnFailed(failure);
+  }
   async function describe(resourceUrl = "") {
     const specs = await ready();
     const accepts = [];
@@ -5707,6 +5736,11 @@ function createPaymentGate(options) {
     return { kind: "paid", receipt: result.receipt, receiptHeader: buildReceiptHeader(result.receipt) };
   }
   async function verify(paymentSignature) {
+    const result = await resolveVerdict(paymentSignature);
+    if (result.kind === "invalid") await deliverOnFailed(result);
+    return result;
+  }
+  async function resolveVerdict(paymentSignature) {
     const raw = normaliseHeader(paymentSignature);
     if (!raw) return asChallenge();
     const sig = parseSignatureHeader(raw);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@piprail/sdk",
-  "version": "2.6.0",
+  "version": "2.7.0",
   "description": "Accept x402 crypto payments across 29 chains — every major EVM chain plus Solana, TON, Tron, NEAR, Sui, Aptos, Algorand, Stellar & XRPL — in a couple of lines. No backend, no database, no fee; payments settle straight to your wallet.",
   "type": "module",
   "main": "./dist/index.cjs",