@openlup/platform 0.20.0 → 0.22.0

package/src/payments/stripe/stripeWebhookNormalizer.ts

@@ -0,0 +1,277 @@
+import { stripeWebhookPayload } from "./stripeFailureEvidence.js";
+import { stripeRefundEvidence } from "./stripeRefundEvidence.js";
+import { expiryInstantFromMonthYear, type PaymentMethodLifecycleEvent, type PaymentMethodLifecycleEventKind, type PaymentMethodReplacementFacts } from "@openlup/core/payment";
+import type { NormalizedProviderPaymentWebhook } from "./donorContracts.js";
+import { methodFactSnapshotKeys, type ProviderWebhookWithMethodLifecycle } from "./methodFacts.js";
+
+const PROVIDER_KIND = "stripe";
+
+/**
+ * Method-family events, mapped to the neutral lifecycle vocabulary. They carry
+ * no money and match no local attempt, so they ride the canonical `setup.*`
+ * kinds and the ingest ledger's allowlist does not move. `attached` is the
+ * first delivery carrying the instrument's own facts (the setup event carries
+ * only its id); `automatically_updated` is the network rotating those facts
+ * under an UNCHANGED consent, never a death; `detached` is the method leaving
+ * the payer's file for good. ⚠️ Deploy note: the endpoint's subscribed event
+ * list must include these three names or none of them ever arrive — an
+ * operator console change, not a code change.
+ */
+type MethodLifecycleMapping = { kind: PaymentMethodLifecycleEventKind; canonical: NormalizedProviderPaymentWebhook["eventType"] };
+const METHOD_LIFECYCLE_EVENTS: Record<string, MethodLifecycleMapping> = {
+  "payment_method.attached": { kind: "method_registered", canonical: "setup.succeeded" },
+  "payment_method.automatically_updated": { kind: "method_updated", canonical: "setup.succeeded" },
+  "payment_method.detached": { kind: "method_revoked", canonical: "setup.failed" },
+};
+
+const SUPPORTED_EVENT_TYPES = new Set<NormalizedProviderPaymentWebhook["eventType"]>([
+  "payment.requires_action",
+  "payment.succeeded",
+  "payment.failed",
+  "payment.refunded",
+  "payment.disputed",
+  "setup.succeeded",
+  "setup.failed",
+  "setup.requires_action",
+]);
+
+/**
+ * Convert a verified raw Stripe webhook payload into the plural handler's
+ * `NormalizedProviderPaymentWebhook` shape.
+ *
+ * Reusable method extraction (Wave C): populated for `setup_intent.succeeded`
+ * always, and for `payment_intent.succeeded` when `setup_future_usage` was
+ * requested at PaymentIntent creation. Requires `metadata.clientId` to be set
+ * (the adapter does this when the runtime caller passes `clientId` through
+ * `PaymentExecutionInput`). When metadata is missing, `reusableMethod` stays
+ * null and the plural handler skips the method-ref upsert — safe degradation
+ * rather than crashing the webhook.
+ */
+export function normalizeStripeWebhookEvent(
+  rawPayload: Record<string, unknown>,
+): ProviderWebhookWithMethodLifecycle {
+  const providerEventId = readString(rawPayload, "id");
+  const eventType = readString(rawPayload, "type");
+  const data = readObject(rawPayload, "data");
+  const object = readObject(data, "object");
+
+  const canonicalEventType = mapStripeEventType(eventType, object);
+  const providerPaymentId = resolveLinkagePaymentId(eventType, object);
+  // Payment-control compares this against the intent's `amount_cents` (the order
+  // total) as a tamper guard, so we want the PaymentIntent's authorized `amount`,
+  // not `amount_received`. On a declined/canceled PI Stripe reports
+  // `amount_received: 0` while `amount` still holds the full total — and `??`
+  // does NOT treat `0` as nullish, so reading `amount_received` first yielded a
+  // `0` that tripped the amount-mismatch guard and left every failed event
+  // unreconciled (intent stuck `processing`, inventory holds leaked). Prefer
+  // `amount`; fall back to `amount_received` only when `amount` is absent.
+  const amountMinor =
+    readOptionalNumber(object, "amount") ??
+    readOptionalNumber(object, "amount_received") ??
+    null;
+  const currency = readOptionalString(object, "currency")?.toUpperCase() ?? null;
+  const occurredAt = readOccurredAt(rawPayload);
+  const reusableMethod = extractReusableMethod(canonicalEventType, object);
+  const refund = stripeRefundEvidence(eventType, object);
+
+  return {
+    provider: PROVIDER_KIND,
+    providerEventId,
+    eventType: canonicalEventType,
+    providerPaymentId,
+    paymentIntentId: null,
+    paymentAttemptId: null,
+    amountMinor,
+    currency,
+    occurredAt,
+    refundKind: refund.refundKind,
+    rawPayload: {
+      ...stripeWebhookPayload({ eventId: providerEventId, eventType, providerPaymentId, amountMinor, currency }, object),
+      ...(refund.snapshot ? { stripeRefundSnapshot: refund.snapshot } : {}),
+    },
+    reusableMethod,
+    methodLifecycle: extractMethodLifecycle(eventType, object, providerEventId, occurredAt),
+  };
+}
+
+/** The neutral transition this delivery reports, or null when it reports none. */
+function extractMethodLifecycle(
+  rawEventType: string,
+  object: Record<string, unknown>,
+  providerEventId: string,
+  occurredAt: string,
+): PaymentMethodLifecycleEvent | null {
+  const mapping = METHOD_LIFECYCLE_EVENTS[rawEventType];
+  // On a method-family event the webhook object IS the method, so its own id is
+  // the reference the stored row is keyed by.
+  const providerMethodRef = readOptionalString(object, "id");
+  if (!mapping || !providerMethodRef) return null;
+  const replacement = readMethodFacts(object);
+  return { kind: mapping.kind, providerKind: PROVIDER_KIND, providerMethodRef, providerEventId, occurredAt, replacement };
+}
+
+/**
+ * Scheme label, trailing digits and expiry, from whichever of the three shapes
+ * the payload carries them in: the method object itself at the top level, an
+ * expanded method one level down, or a charge-shaped object's method details.
+ * A payload carrying none of them yields null, not a row of empty facts.
+ */
+function readMethodFacts(object: Record<string, unknown>): PaymentMethodReplacementFacts | null {
+  const card = readOptionalObject(object, "card")
+    ?? readOptionalObject(readOptionalObject(object, "payment_method") ?? {}, "card")
+    ?? readOptionalObject(readOptionalObject(object, "payment_method_details") ?? {}, "card");
+  if (!card) return null;
+  const schemeLabel = readOptionalString(card, "brand") ?? null;
+  const lastDigits = readOptionalString(card, "last4") ?? null;
+  const expiresAt = expiryInstantFromMonthYear(readOptionalNumber(card, "exp_month") ?? null, readOptionalNumber(card, "exp_year") ?? null);
+  if (!schemeLabel && !lastDigits && !expiresAt) return null;
+  return { schemeLabel, lastDigits, expiresAt };
+}
+
+/**
+ * Resolve the provider payment id used to LINK this event to the local payment
+ * attempt. Payment-control matches inbound events to an attempt by
+ * `commerce_payment_attempts.provider_attempt_id`, which holds the Stripe
+ * PaymentIntent id (`pi_…`).
+ *
+ * For `payment_intent.*` events the webhook object IS the PaymentIntent, so its
+ * `id` is already the linkage key. For `charge.*` (incl. `charge.dispute.*`)
+ * the object is a Charge (`ch_…`) or Dispute (`dp_…`) whose own id never
+ * matches an attempt — but it carries `payment_intent` pointing back at the PI.
+ * Using that field is what lets `charge.refunded` / `charge.dispute.created`
+ * resolve to the order and drive `applyPaymentResult`; without it refunds and
+ * disputes were ingested but silently never applied. Falls back to the object
+ * id when `payment_intent` is absent (defensive — keeps the event recordable).
+ */
+function resolveLinkagePaymentId(
+  stripeEventType: string,
+  object: Record<string, unknown>,
+): string {
+  if (stripeEventType.startsWith("charge.")) {
+    const paymentIntentId = readOptionalString(object, "payment_intent");
+    if (paymentIntentId) return paymentIntentId;
+  }
+  return readString(object, "id");
+}
+
+function mapStripeEventType(
+  stripeEventType: string,
+  object: Record<string, unknown>,
+): NormalizedProviderPaymentWebhook["eventType"] {
+  if (stripeEventType === "payment_intent.succeeded") return "payment.succeeded";
+  if (stripeEventType === "payment_intent.payment_failed") return "payment.failed";
+  if (stripeEventType === "payment_intent.canceled") return "payment.failed";
+  if (stripeEventType === "payment_intent.requires_action") return "payment.requires_action";
+  if (stripeEventType === "setup_intent.succeeded") return "setup.succeeded";
+  if (stripeEventType === "setup_intent.setup_failed") return "setup.failed";
+  if (stripeEventType === "setup_intent.requires_action") return "setup.requires_action";
+  if (stripeEventType === "charge.refunded") return "payment.refunded";
+  if (stripeEventType.startsWith("charge.dispute.")) return "payment.disputed";
+  const methodLifecycle = METHOD_LIFECYCLE_EVENTS[stripeEventType];
+  if (methodLifecycle) return methodLifecycle.canonical;
+  const status = readOptionalString(object, "status");
+  if (status === "requires_action") return "payment.requires_action";
+  const guess = `payment.${stripeEventType}` as NormalizedProviderPaymentWebhook["eventType"];
+  if (SUPPORTED_EVENT_TYPES.has(guess)) return guess;
+  throw new Error(`Unsupported Stripe webhook event: ${stripeEventType}`);
+}
+
+function extractReusableMethod(
+  canonicalEventType: NormalizedProviderPaymentWebhook["eventType"],
+  object: Record<string, unknown>,
+): NormalizedProviderPaymentWebhook["reusableMethod"] {
+  const isSetupSucceeded = canonicalEventType === "setup.succeeded";
+  const isPaymentSucceededWithSaveCard =
+    canonicalEventType === "payment.succeeded" &&
+    readOptionalString(object, "setup_future_usage") === "off_session";
+  if (!isSetupSucceeded && !isPaymentSucceededWithSaveCard) return null;
+
+  const customer = readOptionalString(object, "customer");
+  // The method arrives as a bare id, or as an expanded object when the payload
+  // also carries its facts; both address the same stored method.
+  const paymentMethod = readOptionalString(object, "payment_method")
+    ?? readOptionalString(readOptionalObject(object, "payment_method") ?? {}, "id");
+  const metadata = readOptionalObject(object, "metadata");
+  const clientId = metadata ? readOptionalString(metadata, "clientId") : undefined;
+  const subscriptionId = metadata ? readOptionalString(metadata, "subscriptionId") : undefined;
+  const mode = metadata ? readOptionalString(metadata, "mode") : undefined;
+  const recoveryCaseId = metadata ? readOptionalString(metadata, "recoveryCaseId") : undefined;
+  const metadataSource = metadata ? readOptionalString(metadata, "source") : undefined;
+  if (!customer || !paymentMethod || !clientId) return null;
+
+  return {
+    clientId,
+    // W11.7 Wave D-4a — recovery setup-method flow tags `subscriptionId` in
+    // SetupIntent metadata so this upsert binds the new method to the
+    // subscription the dunning case targets. One-time + initial save-card
+    // (Wave C) flows leave the field null because no subscription exists yet.
+    subscriptionId: subscriptionId ?? null,
+    providerCustomerRef: customer,
+    providerMethodRef: paymentMethod,
+    providerMandateRef: null,
+    methodKind: "card",
+    status: "active",
+    consentSnapshot: {
+      source: "stripe_webhook",
+      eventType: canonicalEventType,
+      checkoutMode: mode ?? null,
+      recoveryCaseId: recoveryCaseId ?? null,
+      metadataSource: metadataSource ?? null,
+      // Additive facts only, and only when the payload actually carried them.
+      // The setup event carries the method's id and nothing else, so this is
+      // usually empty there and filled later by the method-family delivery.
+      ...methodFactSnapshotKeys(readMethodFacts(object)),
+    },
+  };
+}
+
+function readOccurredAt(rawPayload: Record<string, unknown>): string {
+  const created = rawPayload.created;
+  if (typeof created === "number" && Number.isFinite(created)) {
+    return new Date(created * 1000).toISOString();
+  }
+  if (typeof created === "string") {
+    const parsed = new Date(created);
+    if (!Number.isNaN(parsed.getTime())) return parsed.toISOString();
+  }
+  // Stripe always sends `created` on event payloads; fall back defensively if
+  // missing rather than refusing the event — downstream RPC still records the
+  // signature-verified facts.
+  return new Date(0).toISOString();
+}
+
+function readObject(value: Record<string, unknown>, key: string): Record<string, unknown> {
+  const raw = value[key];
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error(`Stripe payload missing object ${key}`);
+  }
+  return raw as Record<string, unknown>;
+}
+
+function readOptionalObject(
+  value: Record<string, unknown>,
+  key: string,
+): Record<string, unknown> | null {
+  const raw = value[key];
+  return raw && typeof raw === "object" && !Array.isArray(raw)
+    ? (raw as Record<string, unknown>)
+    : null;
+}
+
+function readString(value: Record<string, unknown>, key: string): string {
+  const raw = value[key];
+  if (typeof raw !== "string" || raw.length === 0) {
+    throw new Error(`Stripe payload missing string ${key}`);
+  }
+  return raw;
+}
+
+function readOptionalString(value: Record<string, unknown>, key: string): string | undefined {
+  const raw = value[key];
+  return typeof raw === "string" && raw.length > 0 ? raw : undefined;
+}
+
+function readOptionalNumber(value: Record<string, unknown>, key: string): number | undefined {
+  const raw = value[key];
+  return typeof raw === "number" ? raw : undefined;
+}

package/src/payments/stripe/webhookSignature.ts

@@ -0,0 +1,55 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+export const STRIPE_TIMESTAMP_TOLERANCE_SECONDS = 300;
+
+export function verifyStripeSignature(input: {
+  rawBody: string;
+  signatureHeader: string | undefined;
+  /**
+   * One or many endpoint secrets to accept. Multi-secret support lets a single
+   * route accept signatures from both the dashboard webhook endpoint and a
+   * local `stripe listen` CLI tunnel; the signature is accepted if ANY secret
+   * verifies. An empty array (or missing single secret) fails closed.
+   */
+  endpointSecret: string | readonly string[];
+  /** Injectable clock (UTC seconds) for deterministic tests; defaults to now. */
+  now?: () => number;
+}): boolean {
+  const parts = Object.fromEntries(
+    (input.signatureHeader ?? "")
+      .split(",")
+      .map((part) => part.split("="))
+      .filter(([key, value]) => key && value) as Array<[string, string]>,
+  );
+  const timestamp = parts.t;
+  const signature = parts.v1;
+  if (!timestamp || !signature) return false;
+  // Reject replays outside the tolerance window before doing the HMAC work. A
+  // valid signature on a stale timestamp (captured-and-replayed event) must not
+  // pass; the future-skew bound tolerates small clock drift between Stripe and us.
+  const timestampSec = Number(timestamp);
+  if (!Number.isFinite(timestampSec)) return false;
+  const now = input.now ?? (() => Math.floor(Date.now() / 1000));
+  const ageSec = now() - timestampSec;
+  if (ageSec > STRIPE_TIMESTAMP_TOLERANCE_SECONDS) return false;
+  if (ageSec < -STRIPE_TIMESTAMP_TOLERANCE_SECONDS) return false;
+  const secrets = Array.isArray(input.endpointSecret)
+    ? input.endpointSecret
+    : input.endpointSecret
+      ? [input.endpointSecret]
+      : [];
+  return secrets.some((secret) => {
+    if (!secret) return false;
+    const expected = hmac(`${timestamp}.${input.rawBody}`, secret);
+    return timingSafeStringEqual(signature, expected);
+  });
+}
+
+function hmac(value: string, secret: string): string {
+  return createHmac("sha256", secret).update(value).digest("hex");
+}
+
+function timingSafeStringEqual(left: string, right: string): boolean {
+  const leftBuffer = Buffer.from(left);
+  const rightBuffer = Buffer.from(right);
+  return leftBuffer.length === rightBuffer.length && timingSafeEqual(leftBuffer, rightBuffer);
+}

package/src/payments/tpay/blikRecurringMapper.ts

@@ -0,0 +1,42 @@
+export interface TpayBlikAliasRegistrationInput {
+  orderRef: string;
+  amountMinor: number;
+  currency: string;
+  customerEmail: string;
+  staticWebhookUrl: string;
+  consentRef: string;
+}
+
+export interface TpayBlikAliasChargeInput {
+  orderRef: string;
+  payId: string;
+  amountMinor: number;
+  currency: string;
+  staticWebhookUrl: string;
+}
+
+export function buildTpayBlikAliasRegistrationDraft(input: TpayBlikAliasRegistrationInput) {
+  return {
+    provider: "tpay",
+    requestKind: "blik_alias_registration",
+    orderRef: input.orderRef,
+    amount: input.amountMinor,
+    currency: input.currency,
+    customer: { email: input.customerEmail },
+    webhookUrl: input.staticWebhookUrl,
+    consentRef: input.consentRef,
+    fallbackRequiredWhenAliasUnavailable: true,
+  };
+}
+
+export function buildTpayBlikAliasChargeDraft(input: TpayBlikAliasChargeInput) {
+  return {
+    provider: "tpay",
+    requestKind: "blik_alias_charge",
+    orderRef: input.orderRef,
+    payId: input.payId,
+    amount: input.amountMinor,
+    currency: input.currency,
+    webhookUrl: input.staticWebhookUrl,
+  };
+}

package/src/payments/tpay/capabilities.ts

@@ -0,0 +1,21 @@
+import type { PaymentAdapterCapabilities } from "../contracts/index.js";
+
+/** Bank-redirect, one-time-code and unattended Model O attempts are supported with host payer/method input; account availability remains verification_pending. */
+export const tpayPaymentCapabilities: Readonly<PaymentAdapterCapabilities> = Object.freeze<PaymentAdapterCapabilities>({
+  providerKind: "tpay",
+  captureFlows: Object.freeze([
+    Object.freeze({ kind: "bank_redirect", handoff: "redirect", methodFamilies: Object.freeze(["bank-redirect"] as const) }),
+    Object.freeze({ kind: "one_time_code", handoff: "customer-authorization", methodFamilies: Object.freeze(["one-time-code"] as const) }),
+  ]),
+  requiresStoredMandateEvidence: true,
+  assessMandate: snapshot => snapshot.recurringModel === "O" ? { chargeable: true }
+    : { chargeable: false, blockReason: "mandate_model_unsupported_for_unattended_charge" },
+  unattendedChargeFlow: "recurring_charge",
+  payerContext: Object.freeze({ requiresPayerBlock: true, customerRefFallsBackToContactEmail: false }),
+  methodHealth: Object.freeze({ requiresCustomerRef: false, requiredMethodKind: "blik_payid", requiresPayerContact: true }),
+  terminalOutcomeReporting: Object.freeze({ kind: "attempt_records", silenceBecomesSuspectAfterMinutes: 360 }),
+  mandateUpsertIsSubscriptionScoped: true,
+  supportedCurrencies: Object.freeze(["PLN"]), unattended: "supported", readback: "supported", close: "unsupported",
+  exactAbsence: "unsupported", refundObservation: "supported", refundCreate: "unsupported", authorizationCaptureSplit: "unsupported",
+});
+

package/src/payments/tpay/classifyDecline.ts

@@ -0,0 +1,62 @@
+import { classifyPaymentFailure, type PaymentExecutionProviderDecline, type PaymentFailureClassification, type PaymentFailureHint } from "@openlup/core/payment";
+export const DECLINE_FAILURE_REASONS = {
+  /** The payer's bank cannot register a reusable mandate — offer a card instead. */
+  mandateUnsupported: "blik_recurring_unsupported_bank",
+  /** Declined for a reason the provider did not distinguish. */
+  generic: "provider_declined",
+} as const;
+
+/** Maps a provider refusal to the stable code persisted as `failure_reason`. */
+export function declineFailureReason(decline: PaymentExecutionProviderDecline): string {
+  return decline.mandateUnsupported
+    ? DECLINE_FAILURE_REASONS.mandateUnsupported
+    : DECLINE_FAILURE_REASONS.generic;
+}
+
+/**
+ * The one place a refused payment gets a class, for every rail that consumes a
+ * synchronous decline: interactive checkout, checkout recovery, and the
+ * off-session renewal cron.
+ *
+ * Provider-agnostic on purpose. Every code the adapter understood has already
+ * been translated into `adviceCode` and `neutralReasonHints` by the adapter that
+ * owns the vocabulary, so nothing here needs to know which provider refused.
+ *
+ * The one reading this seam adds is the mandate flag. `mandateUnsupported` is a
+ * neutral capability statement any adapter may set, and it is what produces the
+ * scheme-named failure reason below; asserting the matching hint is what turns
+ * that reason into `mandate_dead` instead of leaving it unclassified. Doing it
+ * here rather than per adapter means a second adapter setting the same flag gets
+ * the same class without repeating the mapping.
+ *
+ * DISPLAY-LOAD-BEARING, and NOT a cadence input. Three live readers turn the
+ * class this seam decides into what the payer is told: `dunningFailureClassPort`
+ * reads it off the case, `customerAccountActionRequiredReadModel` selects it into
+ * the account surface, and `paymentRecoverySetupHandler` renders it as the cause
+ * sentence on the recovery page. What still does NOT read it is the retry ladder:
+ * no cadence, retry decision or scheduling branch consults the class, and that
+ * wave stays gated on validating this taxonomy against the historical corpus.
+ *
+ * `failureReasonKey` overrides the reason this seam would derive itself, and is
+ * supplied by a rail that persists a DIFFERENT reason string with the attempt:
+ * the reconciliation rail writes its own adapter-prefixed key, not
+ * `provider_declined`. That key is the classifier's weakest evidence tier, so
+ * the override changes a class only where the rail's own key is mapped; what it
+ * always changes is `decidedBy`, and that is the point. The historical-corpus
+ * replay reproduces a verdict from the stored attempt row, so the key named in
+ * the telemetry has to be the key actually on that row rather than one this seam
+ * invented for itself.
+ */
+export function classifyDecline(
+  decline: PaymentExecutionProviderDecline,
+  options: { failureReasonKey?: string } = {},
+): PaymentFailureClassification {
+  const asserted: PaymentFailureHint[] = [...(decline.neutralReasonHints ?? [])];
+  if (decline.mandateUnsupported) asserted.push("mandateUnsupported");
+  return classifyPaymentFailure({
+    adviceCode: decline.adviceCode,
+    declineCode: decline.declineCode,
+    neutralReasonHints: asserted,
+    failureReasonKey: options.failureReasonKey ?? declineFailureReason(decline),
+  });
+}

package/src/payments/tpay/declineFailureHints.ts

@@ -0,0 +1,90 @@
+import type { PaymentFailureHint, PaymentRetryAdviceCode } from "@openlup/core/payment";
+
+/**
+ * ⚠️ UNOFFICIAL INFERENCE — the whole table below.
+ *
+ * The provider publishes no retryable-versus-terminal classification for these
+ * numeric refusal codes. Every row is this adapter's reading of the code's
+ * documented MEANING, not a documented retry verdict, and one of them
+ * (`"100"`) appears in no published table at all. Treat the table as a
+ * hypothesis under test. The class it produces is already DISPLAY-load-bearing:
+ * it becomes the sentence the payer reads about their own refusal, so a wrong
+ * row here misinforms a customer today. It is still not a cadence input: the
+ * dunning programme validates this table against the historical refusal corpus
+ * before anything in the retry ladder is allowed to branch on it.
+ *
+ * The contract that would end the inference is OUTSTANDING, not absent: the
+ * dunning programme's letter to the provider asks for the official meaning of
+ * these codes, and is tracked there as an open item. Until it is answered, a row
+ * may be read more narrowly than it is written — see `assertableHints` in
+ * `tpayDeclineEvidence.ts`, where each observation decides how much of its own
+ * reading it is entitled to state — but no row may be read more widely.
+ *
+ * Two rails read this table, and both reach it through the attempt log's
+ * `paymentErrorCode`: the reconciliation poll, and — since the 2026-08-26
+ * incident — the synchronous execution path, which until then decided a
+ * mandate refusal by pattern-matching the refusal MESSAGE.
+ *
+ * Codes arrive as strings because that is how they leave the transport layer.
+ *
+ * Two rows carry a decision worth stating rather than a lookup:
+ *
+ *   - `"101"` (refused by the payer) and `"107"` (refused on security grounds)
+ *     are NOT credential death — the instrument may be in perfect health and
+ *     the payer may approve the very next charge on it. There is no hint for
+ *     "terminal for this attempt, instrument fine", so this adapter instead
+ *     states the retry verdict directly, as advice: an unattended repeat of a
+ *     refusal the payer or their bank made deliberately is the retry that
+ *     cannot succeed and still costs a scheme fee. Naming it as advice is also
+ *     the more honest shape — it records what this adapter concludes about
+ *     RETRYING, without asserting anything about the instrument.
+ *   - `"100"` and `"102"` get NO reading. Nothing published says what they mean
+ *     precisely enough to classify, and `indeterminate` is the correct answer to
+ *     a code we cannot read. They are named in
+ *     `KNOWN_UNREADABLE_DECLINE_CODES` below, so their absence stays a recorded
+ *     decision rather than an oversight.
+ */
+export interface DeclineCodeReading {
+  hints?: readonly PaymentFailureHint[];
+  adviceCode?: PaymentRetryAdviceCode;
+}
+
+export const DECLINE_CODE_READING_TABLE: Readonly<Record<string, DeclineCodeReading>> = Object.freeze({
+  "101": Object.freeze({ adviceCode: "do_not_try_again" } as const),
+  "103": Object.freeze({ hints: Object.freeze(["transient"] as const) } as const),
+  "104": Object.freeze({ hints: Object.freeze(["transient"] as const) } as const),
+  "105": Object.freeze({ hints: Object.freeze(["mandateUnsupported"] as const) } as const),
+  "106": Object.freeze({ hints: Object.freeze(["limitExceeded"] as const) } as const),
+  "107": Object.freeze({ adviceCode: "do_not_try_again" } as const),
+});
+
+/**
+ * Codes this adapter has SEEN and still cannot read. They are deliberately absent
+ * from the table above rather than mapped to a guess: a row there must state
+ * vocabulary the kernel declares, and `indeterminate` is the honest answer to a
+ * code whose meaning is unconfirmed. Listing them here separates "we have met
+ * this code and refuse to invent its semantics" from "we have never seen it",
+ * which read identically at the lookup.
+ *
+ *   - `"100"` — observed in production on 2026-08-26, as the first attempt of a
+ *     refused mandate registration whose second attempt was `"105"`. Nothing
+ *     published says what it means, so it maps to no hint and no advice.
+ *   - `"102"` — same standing, from the same unpublished range.
+ *
+ * A code moving out of this list into the table is a semantics decision backed by
+ * evidence, not a lookup edit.
+ */
+export const KNOWN_UNREADABLE_DECLINE_CODES: readonly string[] = Object.freeze(["100", "102"]);
+
+const NO_READING: DeclineCodeReading = Object.freeze({});
+
+/**
+ * This adapter's reading of one refusal code. Own-property lookup, so an
+ * inherited key (`constructor`, `toString`) is not a mapping.
+ */
+export function declineCodeReading(code: string | undefined): DeclineCodeReading {
+  if (code === undefined) return NO_READING;
+  return Object.prototype.hasOwnProperty.call(DECLINE_CODE_READING_TABLE, code)
+    ? DECLINE_CODE_READING_TABLE[code]
+    : NO_READING;
+}

package/src/payments/tpay/donorContracts.ts

@@ -0,0 +1,104 @@
+/** Private structural contracts for the unchanged execution and observation slices. */
+import type { PaymentExecutionBaseInput, PaymentExecutionBaseResult } from "@openlup/core/payment";
+import type { ProviderReadPurpose } from "../contracts/index.js";
+export type PaymentProviderFlow = "one_time_payment" | "setup_reusable_method" | "off_session_payment" | "blik_one_time" | "blik_one_click" | "pbl_one_time" | "blik_recurring_activation" | "recurring_charge";
+export const PAYMENT_NEXT_ACTION_KINDS = ["redirect", "3ds_challenge", "sca_required"] as const;
+export type PaymentNextActionKind = (typeof PAYMENT_NEXT_ACTION_KINDS)[number];
+export interface PaymentExecutionInput extends PaymentExecutionBaseInput {
+  orderRef: string;
+  orderId?: string;
+  subjectId?: string | null;
+  returnContext?: "public" | "account";
+  payer?: { email: string; name: string; ip?: string | null; userAgent?: string | null };
+  transientProviderInput?: TpayTransientProviderInput | null;
+  paymentMethodAliasType?: "UID" | "PAYID";
+  paymentMethodRecurringModel?: "O" | "M";
+  providerFlow?: PaymentProviderFlow;
+  customerRef?: string;
+  paymentMethodRef?: string;
+  saveForFutureUse?: boolean;
+  clientId?: string;
+}
+export interface PaymentExecutionResult extends PaymentExecutionBaseResult {
+  nextActionKind: PaymentNextActionKind | null;
+  redirectUrl?: string | null;
+  clientSecret?: string | null;
+  customerProviderRef?: string | null;
+  paymentMethodRef?: string | null;
+  webhookExpected?: boolean;
+  recoveryRequired?: boolean;
+}
+export interface PaymentExecutionPort {
+  validateInput?(input: PaymentExecutionInput): void;
+  execute(input: PaymentExecutionInput): Promise<PaymentExecutionResult>;
+}
+export type PaymentWebhookEventType = "payment.succeeded" | "payment.failed" | "payment.refunded" |
+  "payment.requires_action" | "payment.disputed" | "setup.succeeded" | "setup.failed" | "setup.requires_action";
+export interface CanonicalPaymentEvent {
+  provider_event_id: string;
+  event_type: PaymentWebhookEventType;
+  payment_provider_id: string;
+  amount_minor?: number;
+  next_action_kind?: PaymentNextActionKind;
+  raw_payload: Record<string, unknown>;
+}
+export interface NormalizedProviderPaymentWebhook {
+  provider: string;
+  providerEventId: string;
+  eventType: PaymentWebhookEventType;
+  providerPaymentId: string;
+  paymentIntentId?: string | null;
+  paymentAttemptId?: string | null;
+  amountMinor?: number | null;
+  currency?: string | null;
+  occurredAt: string;
+  refundKind?: "full" | "partial" | null;
+  rawPayload: Record<string, unknown>;
+  reusableMethod?: {
+    clientId: string;
+    subscriptionId?: string | null;
+    providerCustomerRef?: string | null;
+    providerMethodRef: string;
+    providerMandateRef?: string | null;
+    methodKind: "card";
+    status: "active";
+    consentSnapshot?: Record<string, unknown>;
+  } | null;
+}
+export interface ProviderReconciliationStatus {
+  status: "succeeded" | "failed" | "pending" | "unknown";
+  providerStatus: string;
+  occurredAt: string | null;
+  failureReason: string | null;
+  amountMinor: number | null;
+  currency: string | null;
+  rawPayload: Record<string, unknown>;
+}
+export interface ClaimedPaymentAttempt {
+  paymentAttemptId: string; paymentIntentId: string; paymentId: string; orderId: string;
+  subscriptionId: string | null; subscriptionCycleId: string | null; provider: string;
+  providerPaymentId: string | null; providerAttemptId: string | null; providerSessionId: string | null;
+  attemptStatus: string; intentStatus: string; amountMinor: number; currency: string;
+  orderMode: "one_time" | "subscription_cycle"; cycleRetryAttempt: number; cycleNextRetryAt: string | null;
+  localUpdatedAt: string;
+}
+export type ProviderRecoveryAction = { kind: "redirect"; url: string };
+export interface PaymentProviderRecoveryProvider {
+  resolvePaymentReference(input: { providerAttemptId: string | null; intentProviderPaymentId: string | null;
+    providerSessionId: string | null }): string | null;
+  readPayment(input: { providerPaymentId: string; attempt?: ClaimedPaymentAttempt;
+    purpose?: ProviderReadPurpose }): Promise<ProviderReconciliationStatus>;
+  readRecoveryPayment(input: { providerPaymentId: string; attempt: Pick<ClaimedPaymentAttempt, "amountMinor" | "currency">;
+    purpose?: ProviderReadPurpose }): Promise<{ status: ProviderReconciliationStatus; identityMatches: boolean;
+      configuredMoneyMatches: boolean; manualReviewRequired: boolean; clientAction: ProviderRecoveryAction | null }>;
+  closePayment?(input: { providerPaymentId: string }): Promise<ProviderReconciliationStatus>;
+  findPaymentByLocalIntent?(input: { attempt: ClaimedPaymentAttempt }): Promise<"found" | "absent">;
+}
+
+export interface TpayTransientProviderInput {
+  provider: "tpay";
+  flow: "blik_one_time" | "blik_one_click" | "pbl_one_time" | "blik_recurring_activation" | "recurring_charge";
+  blikToken?: string;
+  channelId?: string;
+  recurringModel?: "O" | "M";
+}