@openlup/platform 0.19.0 → 0.21.0

package/src/payments/paymentProviderReconciliationWorker.ts

@@ -0,0 +1,291 @@
+import { tryReopenPreparedAbsence } from "./paymentProviderReconciliationAbsenceReopen.js";
+import {
+  applyResultKey,
+  bucket,
+  clamp,
+  classificationOf,
+  evidencePayload,
+  observedEvidenceKey,
+  preparedAttemptEvidenceKey,
+  safeMessage,
+  terminalAmountMismatch,
+} from "./paymentProviderReconciliationEvidence.js";
+import { silenceIsOverdue } from "./paymentAttemptSilenceWindow.js";
+import type {
+  ClaimedPaymentAttempt,
+  PaymentProviderReconciliationPort,
+  PaymentProviderReconciliationWorkerInput,
+  PaymentProviderReconciliationWorkerResult,
+  ProviderReconciliationStatus,
+  SilenceWindowLookup,
+} from "./contracts/reconciliation.js";
+
+export type {
+  ClaimedPaymentAttempt,
+  PaymentProviderReconciliationPort,
+  PaymentProviderReconciliationProvider,
+  PaymentProviderReconciliationWorkerInput,
+  PaymentProviderReconciliationWorkerResult,
+  ProviderReconciliationStatus,
+  ProviderReconciliationStatusKind,
+  ReconciliationProviderKind,
+  SilenceWindowLookup,
+} from "./contracts/reconciliation.js";
+
+const MAX_ATTEMPTS_PER_RUN = 4;
+const DEFAULT_BATCH_SIZE = MAX_ATTEMPTS_PER_RUN;
+
+export const DEFAULT_STALE_AFTER_SECONDS = 15 * 60;
+
+export async function runPaymentProviderReconciliationWorker(
+  input: PaymentProviderReconciliationWorkerInput,
+): Promise<PaymentProviderReconciliationWorkerResult> {
+  const now = input.now ?? new Date().toISOString();
+  const staleAfterSeconds = clamp(input.staleAfterSeconds ?? DEFAULT_STALE_AFTER_SECONDS, 60, 86_400);
+  // Provider reads and optional prepared-absence probes are sequential and may
+  // be slow. Preserve the per-run ceiling even for an oversized requested batch.
+  const batchSize = clamp(input.batchSize ?? DEFAULT_BATCH_SIZE, 1, MAX_ATTEMPTS_PER_RUN);
+  const claimKey = input.claimKey ?? `payment-provider-reconciliation:${bucket(now)}`;
+  const result: PaymentProviderReconciliationWorkerResult = {
+    ok: true,
+    checked: 0,
+    corrected: 0,
+    succeeded: 0,
+    failed: 0,
+    pending: 0,
+    unknown: 0,
+    ignored: 0,
+    dunningOpened: 0,
+    replayed: 0,
+    providerCalls: 0,
+    preparedWithoutProviderAck: 0,
+    preparedAttemptsReopened: 0,
+    manualReview: 0,
+    silenceOverdue: 0,
+    amountCurrencyMismatches: 0,
+    failures: 0,
+    skipped: false,
+  };
+
+  // Prepared attempts can remain operator-manual indefinitely. Bound their
+  // share so they can never consume a whole worker batch and starve provider
+  // readback for finalized attempts. A batch of one intentionally prioritizes
+  // provider readback; normal scheduled runs use the larger default batch.
+  const preparedLimit = Math.floor(batchSize / 2);
+  const preparedAttempts = preparedLimit > 0
+    ? await input.port.claimPreparedAttempts({
+      now,
+      staleAfterSeconds,
+      limit: preparedLimit,
+      claimKey: `${claimKey}:prepared`,
+    })
+    : [];
+  for (const attempt of preparedAttempts) {
+    const providerStatus: ProviderReconciliationStatus = {
+      status: "unknown",
+      providerStatus: "prepared_without_provider_ack",
+      occurredAt: null,
+      failureReason: "prepared_without_provider_ack",
+      amountMinor: null,
+      currency: null,
+      rawPayload: {
+        source: "payment-provider-reconciliation.prepared-watchdog.v0",
+        provider: attempt.provider,
+        providerCallPlanned: true,
+        providerAcknowledged: false,
+      },
+    };
+    const evidence = await input.port.recordEvidence({
+      idempotencyKey: preparedAttemptEvidenceKey(attempt, now),
+      provider: attempt.provider,
+      providerPaymentId: null,
+      paymentIntentId: attempt.paymentIntentId,
+      paymentAttemptId: attempt.paymentAttemptId,
+      localStatus: attempt.attemptStatus,
+      providerStatus: providerStatus.providerStatus,
+      correctionStatus: "failed",
+      checkedAt: now,
+      payload: evidencePayload(attempt, providerStatus, {
+        applied: false,
+        operatorReviewRequired: true,
+      }),
+    });
+    if (evidence.replayed) result.replayed += 1;
+    result.preparedWithoutProviderAck += 1;
+    result.failures += 1;
+    result.ok = false;
+    result.reason = result.reason ?? "prepared_without_provider_ack";
+
+    // Auto-reopen after a GENUINE provider-side absence proof. A purely local
+    // "no ack recorded" signal cannot rule out the crash window between
+    // executionPort.execute() (provider charged) and finalizeProviderAttempt
+    // (refs persisted) — reopening in that window would mint a fresh PSP
+    // idempotency key and double-charge. Providers without an absence probe
+
+    if (input.autoReopenPreparedAbsence) {
+      const reopened = await tryReopenPreparedAbsence(input, attempt, now);
+      if (reopened) result.preparedAttemptsReopened += 1;
+    }
+  }
+
+  const remainingLimit = batchSize - preparedAttempts.length;
+  const attempts = remainingLimit > 0
+    ? await input.port.claimStaleAttempts({
+      now,
+      staleAfterSeconds,
+      limit: remainingLimit,
+      claimKey,
+    })
+    : [];
+  result.checked = preparedAttempts.length + attempts.length;
+
+  for (const attempt of attempts) {
+    const provider = input.providers[attempt.provider];
+    if (!provider) {
+      await recordNonTerminalEvidence(input.port, attempt, now, {
+        status: "unknown",
+        providerStatus: "provider_not_configured",
+        occurredAt: null,
+        failureReason: "provider_not_configured",
+        amountMinor: null,
+        currency: null,
+        rawPayload: { provider: attempt.provider, source: "payment-provider-reconciliation.v0" },
+      }, "failed");
+      result.unknown += 1;
+      result.failures += 1;
+      result.ok = false;
+      result.reason = result.reason ?? `${attempt.provider}_provider_not_configured`;
+      continue;
+    }
+
+    let providerStatus: ProviderReconciliationStatus;
+    try {
+      if (!attempt.providerPaymentId) {
+        throw new Error("provider_payment_id_missing");
+      }
+      result.providerCalls += 1;
+      providerStatus = await provider.readPayment({
+        providerPaymentId: attempt.providerPaymentId,
+        attempt,
+      });
+    } catch (error) {
+      providerStatus = {
+        status: "unknown",
+        providerStatus: "provider_read_failed",
+        occurredAt: null,
+        failureReason: safeMessage(error),
+        amountMinor: null,
+        currency: null,
+        rawPayload: {
+          provider: attempt.provider,
+          providerPaymentId: attempt.providerPaymentId,
+          readError: safeMessage(error),
+        },
+      };
+      await recordNonTerminalEvidence(input.port, attempt, now, providerStatus, "failed");
+      result.unknown += 1;
+      result.failures += 1;
+      result.ok = false;
+      result.reason = result.reason ?? safeMessage(error);
+      continue;
+    }
+
+    if (providerStatus.status === "pending" || providerStatus.status === "unknown") {
+      // Polling cannot separate "still running" from "stuck" - both answer
+      // non-terminally forever - so ask the rail how long its own silence stays
+      // normal and surface the attempt past that. NOT a terminal decision:
+      // elapsed time says nothing about whether money moved.
+      const overdue = silenceIsOverdue(input.capabilities, attempt, now);
+      await recordNonTerminalEvidence(input.port, attempt, now, providerStatus, "observed", overdue);
+      if (providerStatus.status === "pending") result.pending += 1;
+      else result.unknown += 1;
+      if (overdue) {
+        result.silenceOverdue += 1;
+        result.manualReview += 1;
+      }
+      continue;
+    }
+
+    const mismatch = terminalAmountMismatch(attempt, providerStatus);
+    if (mismatch) {
+      await recordNonTerminalEvidence(input.port, attempt, now, {
+        ...providerStatus,
+        failureReason: mismatch,
+        rawPayload: { ...providerStatus.rawPayload, reconciliationMismatch: mismatch },
+      }, "failed");
+      result.manualReview += 1;
+      result.amountCurrencyMismatches += 1;
+      continue;
+    }
+
+    const occurredAt = providerStatus.occurredAt ?? now;
+    const resultStatus = providerStatus.status;
+    try {
+      const applied = await input.port.applyTerminalResult({
+        idempotencyKey: applyResultKey(attempt, resultStatus),
+        expectedOrderId: attempt.orderId,
+        expectedPaymentIntentId: attempt.paymentIntentId,
+        expectedPaymentAttemptId: attempt.paymentAttemptId,
+        expectedPaymentId: attempt.paymentId,
+        provider: attempt.provider,
+        providerPaymentId: attempt.providerPaymentId,
+        localStatus: attempt.attemptStatus,
+        providerStatus: providerStatus.providerStatus,
+        resultStatus,
+        occurredAt,
+        failureReason: resultStatus === "failed"
+          ? providerStatus.failureReason ?? `provider_reconciliation_${providerStatus.providerStatus}`
+          : null,
+        ...classificationOf(resultStatus, providerStatus),
+        checkedAt: now,
+        payload: evidencePayload(attempt, providerStatus, { applied: true, resultStatus }),
+      });
+      if (applied.replayed) result.replayed += 1;
+
+      if (applied.correctionStatus === "ignored") {
+        result.ignored += 1;
+        continue;
+      }
+
+      result.corrected += applied.replayed ? 0 : 1;
+      if (resultStatus === "succeeded") result.succeeded += 1;
+      else result.failed += 1;
+      if (applied.subscriptionWebhookDunning?.opened && !applied.subscriptionWebhookDunning.replayed) {
+        result.dunningOpened += 1;
+      }
+    } catch (error) {
+      await recordNonTerminalEvidence(input.port, attempt, now, {
+        ...providerStatus,
+        failureReason: safeMessage(error),
+        rawPayload: { ...providerStatus.rawPayload, applyResultError: safeMessage(error) },
+      }, "failed");
+      result.failures += 1;
+      result.ok = false;
+      result.reason = result.reason ?? safeMessage(error);
+    }
+  }
+
+  return result;
+}
+
+function recordNonTerminalEvidence(
+  port: PaymentProviderReconciliationPort,
+  attempt: ClaimedPaymentAttempt,
+  checkedAt: string,
+  providerStatus: ProviderReconciliationStatus,
+  correctionStatus: "observed" | "failed",
+  silenceOverdue = false,
+): Promise<{ replayed: boolean }> {
+  return port.recordEvidence({
+    idempotencyKey: observedEvidenceKey(attempt, providerStatus.status, correctionStatus, checkedAt),
+    provider: attempt.provider,
+    providerPaymentId: attempt.providerPaymentId,
+    paymentIntentId: attempt.paymentIntentId,
+    paymentAttemptId: attempt.paymentAttemptId,
+    localStatus: attempt.attemptStatus,
+    providerStatus: providerStatus.providerStatus,
+    correctionStatus,
+    checkedAt,
+    payload: evidencePayload(attempt, providerStatus, { applied: false, silenceOverdue }),
+  });
+}

package/src/payments/paymentTruth.ts

@@ -0,0 +1,131 @@
+import type { PaymentTruthRefusalClass, PaymentSourceEvidence, PaymentTruthEvent, PaymentReconciliationResult, CanonicalPaymentSource } from "./contracts/truth.js";
+import { createHash } from "node:crypto";
+
+const PAYMENT_TRUTH_REFUSAL_CLASSES: readonly PaymentTruthRefusalClass[] = [
+  "authorization_refused",
+  "insufficient_funds",
+  "method_unavailable",
+  "risk_refused",
+  "unknown_refusal",
+];
+
+export function paymentReconciliationFingerprint(input: PaymentReconciliationResult): string {
+  if (!input.eventId.trim() || input.idempotencyKey.trim().length < 8 || !isInstant(input.occurredAt)) {
+    throw new Error("payment_reconciliation_input_invalid");
+  }
+  if (input.evidenceStatus === "failed" && input.outcome !== "indeterminate") {
+    throw new Error("payment_reconciliation_failure_cannot_terminalize");
+  }
+  if (input.outcome === "refused" && !input.failure) {
+    throw new Error("payment_truth_refusal_classification_required");
+  }
+  if (input.outcome !== "refused" && input.failure) {
+    throw new Error("payment_truth_failure_only_for_refusal");
+  }
+  assertPaymentFailure(input.failure);
+  assertPaymentSourceEvidence(input.evidence);
+  return digest({
+    eventId: input.eventId,
+    evidenceStatus: input.evidenceStatus,
+    outcome: input.outcome,
+    occurredAt: input.occurredAt,
+    failure: input.failure,
+    evidence: input.evidence,
+  });
+}
+
+/** Fingerprint accepted at a provider boundary before local ownership is known. */
+export function paymentSourceFingerprint(input: CanonicalPaymentSource): string {
+  if (!input.sourceEventId.trim() || !input.eventKind.trim()
+    || (input.occurredAt !== null && !isInstant(input.occurredAt))) {
+    throw new Error("payment_source_fingerprint_input_invalid");
+  }
+  if (!/^[0-9a-f]{64}$/.test(input.payloadFingerprint)) {
+    throw new Error("payment_truth_payload_fingerprint_invalid");
+  }
+  return digest(input);
+}
+
+export function paymentPayloadFingerprint(payload: unknown): string {
+  return digest(payload);
+}
+
+/** Canonical identity for one normalized event; idempotency is deliberately not part of it. */
+export function paymentTruthFingerprint(input: PaymentTruthEvent): string {
+  assertPaymentTruthEvent(input);
+  return digest({
+    sourceEventId: input.sourceEventId,
+    settlementIntentId: input.settlementIntentId,
+    outcome: input.outcome,
+    amountMinor: input.amountMinor,
+    currency: input.currency,
+    occurredAt: input.occurredAt,
+    failure: input.failure,
+    evidence: input.evidence,
+  });
+}
+
+export function assertPaymentTruthEvent(input: PaymentTruthEvent): void {
+  if (!input.sourceEventId.trim()) throw new Error("payment_truth_source_event_id_required");
+  if (input.idempotencyKey.trim().length < 8) throw new Error("payment_truth_idempotency_key_invalid");
+  if (!input.settlementIntentId.trim()) throw new Error("payment_truth_settlement_intent_required");
+  if (!Number.isSafeInteger(input.amountMinor) || input.amountMinor <= 0) {
+    throw new Error("payment_truth_amount_invalid");
+  }
+  if (!/^[A-Z]{3}$/.test(input.currency)) throw new Error("payment_truth_currency_invalid");
+  if (!isInstant(input.occurredAt) || !isInstant(input.evidence.observedAt)) {
+    throw new Error("payment_truth_time_invalid");
+  }
+  if (!input.evidence.sourceReference.trim() || !input.evidence.observedStatus.trim()) {
+    throw new Error("payment_truth_source_evidence_invalid");
+  }
+  if (!/^[0-9a-f]{64}$/.test(input.evidence.payloadFingerprint)) {
+    throw new Error("payment_truth_payload_fingerprint_invalid");
+  }
+  if (input.outcome === "refused" && !input.failure) {
+    throw new Error("payment_truth_refusal_classification_required");
+  }
+  if (input.outcome !== "refused" && input.failure) {
+    throw new Error("payment_truth_failure_only_for_refusal");
+  }
+  assertPaymentFailure(input.failure);
+  assertPaymentSourceEvidence(input.evidence);
+}
+
+function isInstant(value: string): boolean {
+  return value.trim().length > 0 && Number.isFinite(Date.parse(value));
+}
+
+function stableJson(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.entries(value as Record<string, unknown>)
+      .sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0)
+      .map(([key, entry]) => `${JSON.stringify(key)}:${stableJson(entry)}`)
+      .join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function assertPaymentFailure(failure: PaymentTruthEvent["failure"]): void {
+  if (failure && !PAYMENT_TRUTH_REFUSAL_CLASSES.includes(failure.classification)) {
+    throw new Error("payment_truth_failure_class_invalid");
+  }
+}
+
+function assertPaymentSourceEvidence(evidence: PaymentSourceEvidence): void {
+  if (evidence.sourceKind !== "accepted_event" && evidence.sourceKind !== "reconciliation_read") {
+    throw new Error("payment_truth_source_kind_invalid");
+  }
+  if (!evidence.sourceReference.trim() || !evidence.observedStatus.trim()) {
+    throw new Error("payment_truth_source_evidence_invalid");
+  }
+  if (!isInstant(evidence.observedAt)) throw new Error("payment_truth_time_invalid");
+  if (!/^[0-9a-f]{64}$/.test(evidence.payloadFingerprint)) {
+    throw new Error("payment_truth_payload_fingerprint_invalid");
+  }
+}
+
+function digest(value: unknown): string {
+  return createHash("sha256").update(stableJson(value)).digest("hex");
+}

package/src/payments/paymentVerifyNowHandler.ts

@@ -0,0 +1,94 @@
+import { z } from "zod";
+import type { HttpRequest, HttpResponse } from "../http/index.js";
+import type { BffResponder } from "../bff/index.js";
+import type {
+  PaymentProviderReconciliationProvider,
+  PaymentProviderReconciliationPort,
+} from "./contracts/reconciliation.js";
+import { verifyPaymentAttemptNow } from "./paymentVerifyNowService.js";
+import type { PaymentVerifyReadPort } from "./contracts/reconciliation.js";
+
+/**
+ * Buyer-triggered "verify now": after a CLIENT-side confirm failure the FE has
+ * the only copy of the outcome (a pre-charge provider rejection emits no
+ * webhook), so it asks the server to read the provider immediately instead of
+ * waiting for the next adopter-configured reconciliation pass. The client can never assert a result — truth is the live
+ * provider readback, and the only write path is the reconciliation apply RPC
+ * with the cron's own idempotency key, so both paths converge replay-safely.
+ */
+
+export const paymentVerifyRequestSchema = z.object({
+  orderId: z.guid(),
+  paymentIntentId: z.guid(),
+  clientId: z.guid(),
+});
+
+export type PaymentVerifyRequest = z.infer<typeof paymentVerifyRequestSchema>;
+
+
+
+export function createCommercePaymentVerifyHandler(deps: {
+  readPort: PaymentVerifyReadPort;
+  applyPort: Pick<PaymentProviderReconciliationPort, "applyTerminalResult">;
+  providers: Partial<Record<string, PaymentProviderReconciliationProvider>>;
+  mutationsEnabled: () => boolean;
+  now?: () => Date;
+  responder: BffResponder;
+}): (req: HttpRequest, res: HttpResponse) => Promise<void> {
+  const now = deps.now ?? (() => new Date());
+  const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = deps.responder;
+  return async (req, res) => {
+    if (req.method !== "POST") {
+      sendMethodNotAllowed(res, ["POST"]);
+      return;
+    }
+    if (!deps.mutationsEnabled()) {
+      sendBffError(res, "UPSTREAM_UNAVAILABLE", "Provider payment verify is disabled", {
+        details: {
+          feature: "payment-verify",
+          featureFlag: "COMMERCE_PROVIDER_PAYMENTS_ENABLED",
+          reason: "feature_flag_disabled",
+        },
+      });
+      return;
+    }
+
+    const parsed = paymentVerifyRequestSchema.safeParse(req.body);
+    if (!parsed.success) {
+      sendBffError(res, "BAD_REQUEST", "Invalid payment verify request", {
+        details: parsed.error.flatten(),
+      });
+      return;
+    }
+
+    const snapshot = await deps.readPort.readVerifiableAttempt(parsed.data);
+    if (!snapshot) {
+      sendBffError(res, "NOT_FOUND", "Payment not found");
+      return;
+    }
+    // Same non-leaking ownership shape as payment-status: a non-owning triple
+    // reads as absent rather than confirming the payment exists.
+    if (snapshot.orderClientId !== parsed.data.clientId) {
+      sendBffError(res, "NOT_FOUND", "Payment not found");
+      return;
+    }
+
+    const result = await verifyPaymentAttemptNow({
+      snapshot,
+      applyPort: deps.applyPort,
+      providers: deps.providers,
+      now,
+      // This route has exactly one kind of caller: a browser sitting in a live
+      // checkout, asking about the attempt it is currently waiting on. The
+      // reconciliation worker never comes through here — it holds the provider
+      // and calls `readPayment` itself — so the purpose is a property of the
+      // seam, not something a request may choose.
+      purpose: "active_checkout",
+    });
+    sendBffSuccess(res, {
+      status: result.status,
+      verified: result.verified,
+      applied: result.applied,
+    });
+  };
+}

package/src/payments/paymentVerifyNowService.ts

@@ -0,0 +1,125 @@
+import type { ProviderReadPurpose } from "./contracts/evidence.js";
+import type { VerifiableAttemptSnapshot, PaymentVerifyReadPort, PaymentVerifyNowResult } from "./contracts/reconciliation.js";
+import type {
+  ClaimedPaymentAttempt,
+  PaymentProviderReconciliationPort,
+  PaymentProviderReconciliationProvider,
+  ProviderReconciliationStatus,
+} from "./contracts/reconciliation.js";
+import { applyResultKey, evidencePayload, terminalAmountMismatch } from "./paymentProviderReconciliationEvidence.js";
+
+const LIVE_ATTEMPT_STATUSES = new Set(["sent_to_provider", "requires_action", "processing", "created"]);
+
+/**
+ * Shared buyer/cron-compatible live PSP read. It never accepts a browser
+ * outcome and terminal writes still pass through the canonical reconciliation
+ * RPC, so recovery cannot create a second payment truth path.
+ */
+export async function verifyPaymentAttemptNow(input: {
+  snapshot: VerifiableAttemptSnapshot;
+  applyPort: Pick<PaymentProviderReconciliationPort, "applyTerminalResult">;
+  providers: Partial<Record<string, PaymentProviderReconciliationProvider>>;
+  now: () => Date;
+  providerPaymentId?: string;
+  providerStatus?: ProviderReconciliationStatus;
+  /**
+   * Passed straight to the provider read. A caller that omits it gets the
+   * reconciliation reading, in which an intent still waiting for its first
+   * payment method is a finished, abandoned attempt.
+   */
+  purpose?: ProviderReadPurpose;
+}): Promise<PaymentVerifyNowResult> {
+  const { snapshot } = input;
+  if (!LIVE_ATTEMPT_STATUSES.has(snapshot.attemptStatus)) {
+    return { status: snapshot.attemptStatus, verified: false, applied: false, providerPaymentId: null, attempt: null };
+  }
+
+  const provider = input.providers[snapshot.provider];
+  const providerPaymentId = input.providerPaymentId
+    ?? snapshot.providerAttemptId
+    ?? snapshot.intentProviderPaymentId
+    ?? snapshot.providerSessionId;
+  if (!provider || !providerPaymentId) {
+    return { status: "unavailable", verified: false, applied: false, providerPaymentId, attempt: null };
+  }
+
+  const attempt = toClaimedAttemptShape(snapshot, providerPaymentId);
+  const providerStatus = input.providerStatus
+    ?? await provider.readPayment({
+      providerPaymentId,
+      attempt,
+      ...(input.purpose ? { purpose: input.purpose } : {}),
+    });
+  if (providerStatus.status !== "succeeded" && providerStatus.status !== "failed") {
+    return {
+      // Preserve the established payment-verify contract: an unknown provider
+      // vocabulary is still non-terminal and therefore reported as pending.
+      status: "pending",
+      verified: true,
+      applied: false,
+      providerPaymentId,
+      attempt,
+    };
+  }
+
+  if (terminalAmountMismatch(attempt, providerStatus)) {
+    return { status: "manual_review", verified: true, applied: false, providerPaymentId, attempt };
+  }
+
+  const checkedAt = input.now().toISOString();
+  const applied = await input.applyPort.applyTerminalResult({
+    idempotencyKey: applyResultKey(attempt, providerStatus.status),
+    expectedOrderId: snapshot.orderId,
+    expectedPaymentIntentId: snapshot.paymentIntentId,
+    expectedPaymentAttemptId: snapshot.paymentAttemptId,
+    expectedPaymentId: snapshot.paymentId,
+    provider: attempt.provider,
+    providerPaymentId,
+    localStatus: snapshot.attemptStatus,
+    providerStatus: providerStatus.providerStatus,
+    resultStatus: providerStatus.status,
+    occurredAt: providerStatus.occurredAt ?? checkedAt,
+    failureReason: providerStatus.status === "failed"
+      ? providerStatus.failureReason ?? `provider_verify_${providerStatus.providerStatus}`
+      : null,
+    checkedAt,
+    payload: evidencePayload(attempt, providerStatus, {
+      source: "commerce-payment-verify.v0",
+      trigger: "buyer_confirm_settled",
+    }),
+  });
+
+  return {
+    status: providerStatus.status,
+    verified: true,
+    applied: applied.correctionStatus === "corrected" && !applied.replayed,
+    providerPaymentId,
+    attempt,
+  };
+}
+
+export function toClaimedAttemptShape(
+  snapshot: VerifiableAttemptSnapshot,
+  providerPaymentId: string,
+): ClaimedPaymentAttempt {
+  return {
+    paymentAttemptId: snapshot.paymentAttemptId,
+    paymentIntentId: snapshot.paymentIntentId,
+    paymentId: snapshot.paymentId,
+    orderId: snapshot.orderId,
+    subscriptionId: null,
+    subscriptionCycleId: null,
+    provider: snapshot.provider as ClaimedPaymentAttempt["provider"],
+    providerPaymentId,
+    providerAttemptId: snapshot.providerAttemptId,
+    providerSessionId: snapshot.providerSessionId,
+    attemptStatus: snapshot.attemptStatus,
+    intentStatus: snapshot.intentStatus,
+    amountMinor: snapshot.amountMinor,
+    currency: snapshot.currency,
+    orderMode: snapshot.orderMode as ClaimedPaymentAttempt["orderMode"],
+    cycleRetryAttempt: 0,
+    cycleNextRetryAt: null,
+    localUpdatedAt: snapshot.localUpdatedAt,
+  };
+}

package/src/payments/paymentWebhookPostProcessing.ts

@@ -0,0 +1,36 @@
+export type PaymentRefusalHandoff = {
+  outcome: "refused" | "not_refused";
+  idempotencyKey: string;
+  paymentIntentId: string | null;
+  sourceEventId: string;
+  failureReason: string | null;
+  occurredAt: string;
+};
+
+export interface PaymentFailureDunningPort {
+  openFromExplicitRefusal(input: {
+    idempotencyKey: string;
+    paymentIntentId: string;
+    sourceEventId: string;
+    failureReason: string | null;
+    occurredAt: string;
+  }): Promise<void>;
+}
+
+/**
+ * Neutral terminal handoff. Only explicit refusal evidence may enter dunning;
+ * silence, timeout and every other non-terminal answer are deliberate no-ops.
+ */
+export async function handoffExplicitPaymentRefusal(
+  input: PaymentRefusalHandoff,
+  port: PaymentFailureDunningPort,
+): Promise<void> {
+  if (input.outcome !== "refused" || !input.paymentIntentId) return;
+  await port.openFromExplicitRefusal({
+    idempotencyKey: input.idempotencyKey,
+    paymentIntentId: input.paymentIntentId,
+    sourceEventId: input.sourceEventId,
+    failureReason: input.failureReason,
+    occurredAt: input.occurredAt,
+  });
+}