@openlup/platform 0.20.0 → 0.21.0

package/src/payments/tpay/tpayPaymentExecutionAdapter.ts

@@ -0,0 +1,297 @@
+import { failureEvidencePayload } from "./paymentFailureEvidence.js";
+import { tpayFailureEvidence } from "./tpayFailureEvidence.js";
+import type { PaymentExecutionPort } from "./donorContracts.js";
+import type {
+  PaymentExecutionInput,
+  PaymentExecutionResult,
+  TpayTransientProviderInput,
+} from "./donorContracts.js";
+import {
+  aliasValue,
+  buildCreateTransactionInput,
+  resolveRecurringModel,
+} from "./tpayCreateTransactionInput.js";
+import { declineCodeReading } from "./declineFailureHints.js";
+import {
+  assertableHints,
+  isMandateRefusal,
+  mandateCapabilityReadable,
+  readAttemptDeclineObservation,
+  declineEvidenceSource,
+  states,
+} from "./tpayDeclineEvidence.js";
+import type {
+  TpayHttpClient,
+  TpayPayerInput,
+  TpayTransactionCreateInput,
+} from "./tpayHttpClient.js";
+import {
+  tpayTrustedPreDispatchFailure,
+  tpayTrustedRefusalFailure,
+} from "./tpayDispatchFailure.js";
+import { ProviderAttemptPreDispatchError } from "./preparedProviderAttempt.js";
+
+/** The one place this adapter spells its own provider identity. */
+export const PROVIDER_KIND = "tpay" as const;
+
+export interface TpayPaymentExecutionAdapterOptions {
+  client: TpayHttpClient;
+  notificationUrl: string;
+  successUrl: string;
+  errorUrl: string;
+  oneClickEnabled?: boolean;
+  aliasRegistrationOnCodeEnabled?: boolean;
+  /** One public switch for admitting new subscription BLIK Model O mandates. */
+  modelOActivationEnabled?: boolean;
+  resolvePayer?: (input: PaymentExecutionInput) => TpayPayerInput | null;
+}
+
+export function createTpayPaymentExecutionAdapter({
+  client,
+  notificationUrl,
+  successUrl,
+  errorUrl,
+  oneClickEnabled = false,
+  aliasRegistrationOnCodeEnabled = false,
+  modelOActivationEnabled = false,
+  resolvePayer = defaultPayer,
+}: TpayPaymentExecutionAdapterOptions): PaymentExecutionPort {
+  const validateInput = (input: PaymentExecutionInput) => {
+    const transient = requireTpayTransientInput(input, {
+      oneClickEnabled,
+      modelOActivationEnabled,
+    });
+    if (input.currency !== "PLN") throw new TpayExecutionInputError("tpay_currency_not_supported");
+    const payer = resolvePayer(input);
+    if (!payer) throw new TpayExecutionInputError("tpay_payer_missing");
+    return { transient, payer };
+  };
+
+  return {
+    validateInput(input): void {
+      validateInput(input);
+    },
+    async execute(input): Promise<PaymentExecutionResult> {
+      const { transient, payer } = validateInput(input);
+
+      const request = buildCreateTransactionInput({
+        input,
+        transient,
+        payer,
+        notificationUrl,
+        successUrl,
+        errorUrl,
+        aliasRegistrationOnCodeEnabled,
+        modelOActivationEnabled,
+      });
+      let response;
+      try {
+        response = await client.createTransaction(request);
+      } catch (error) {
+        // Two independent proofs Tpay holds no transaction: never asked, or it refused the request
+        // document. Both release the attempt; everything else stays ambiguous and rethrows.
+        const noCharge = tpayTrustedPreDispatchFailure(error) ?? tpayTrustedRefusalFailure(error);
+        if (noCharge) throw new ProviderAttemptPreDispatchError(noCharge);
+        throw error;
+      }
+      const providerAttemptId = response.title || response.transactionId;
+      // This provider reports a synchronous decline ONLY here. `result`, `status`
+      // and `payments.status` all still read "success"/"pending" on a rejected
+      // transaction, so they cannot be used to detect one.
+      const rejections = response.errors ?? [];
+      const rejection = rejections[0] ?? null;
+      // The provider has carried a hard refusal code since the first minute, but
+      // only in the transaction's attempt log — never in the create response,
+      // whose codes are generic. So ask for it the moment the provider says no,
+      // instead of learning it hours later from the reconciliation poll.
+      // Fail-open: `null` means "read nothing", and every branch below then
+      // behaves exactly as it did before this read existed.
+      const observation = rejection
+        ? await readAttemptDeclineObservation(client, response.transactionId)
+        : null;
+      const attemptCode = observation?.code ?? null;
+      // A code the table cannot read decides nothing. Promoting a known-unknown
+      // such as `"100"` to a verdict would silence the message fallback for the
+      // one code we openly admit we cannot read — a regression, not a fix.
+      const attemptReading = attemptCode === null ? null : declineCodeReading(attemptCode);
+      const decidingAttemptReading = attemptReading !== null && states(attemptReading)
+        ? attemptReading
+        : null;
+      const mandateUnsupported = decidingAttemptReading
+        ? mandateCapabilityReadable(transient.flow)
+          && response.payIdEligible !== true
+          && (decidingAttemptReading.hints?.includes("mandateUnsupported") ?? false)
+        : rejection !== null && rejections.some((error) =>
+          isMandateRefusal(transient.flow, response.payIdEligible, error.errorMessage)
+        );
+      // Read here, where the code vocabulary is owned, so the control plane
+      // classifies the refusal without ever seeing a provider-native code. The
+      // attempt log wins when it says something, because it is the carrier the
+      // provider itself writes the refusal into; the create response's own code
+      // is the fallback reading.
+      // The advice half is suppressed when this adapter is already asserting a
+      // mandate refusal: advice outranks hints by design in the taxonomy, and
+      // the identity code is only the FIRST error, so a generic terminal code
+      // arriving ahead of the mandate explanation would otherwise mask the one
+      // reading that says the stored reference — not the instrument — is dead.
+      const reading = decidingAttemptReading ?? declineCodeReading(rejection?.errorCode);
+      const declineEvidence = rejection ? declineEvidenceSource({
+        attemptCode, decidingAttemptReading, mandateUnsupported, reading, errorCode: rejection.errorCode,
+      }) : null;
+      // A capability code is read as mandate evidence only while registering a
+      // mandate. The same opaque code on one-time or stored-mandate charges must
+      // not claim that a mandate is dead. The rule itself lives beside the
+      // refusal evidence it qualifies, because the reconciliation rail funnels
+      // its hints through the same one — a refusal must not classify by which
+      // rail saw it.
+      const neutralReasonHints = assertableHints(reading.hints, transient.flow);
+      const providerDecline = rejection
+        ? {
+            code: rejection.errorCode,
+            // Preserve the first provider code as the stable decline identity, but
+            // inspect every error for the capability signal. The provider may put a
+            // generic payment failure first and the mandate explanation later.
+            mandateUnsupported,
+            ...(reading.adviceCode && !mandateUnsupported ? { adviceCode: reading.adviceCode } : {}),
+            ...(neutralReasonHints?.length ? { neutralReasonHints } : {}),
+          }
+        : null;
+
+      return {
+        provider: PROVIDER_KIND,
+        providerAttemptId,
+        providerSessionId: response.transactionId,
+        // Stays non-terminal even on a decline: the control plane owns terminal
+        // transitions and reads `providerDecline` below to make one.
+        attemptStatus: "processing",
+        providerDecline,
+        nextActionKind: !providerDecline && transient.flow === "pbl_one_time" && response.transactionPaymentUrl
+          ? "redirect"
+          : null,
+        redirectUrl: providerDecline ? null : response.transactionPaymentUrl,
+        // A rejected activation must not publish a payment method reference.
+        paymentMethodRef: transient.flow === "blik_recurring_activation" && !providerDecline
+          ? aliasValue(input.paymentIntentId)
+          : null,
+        // A declined transaction produces no webhook at all: Tpay's `tr_status`
+        // only ever carries `true` or `chargeback`. Claiming otherwise would
+        // strand the attempt waiting for a callback that never arrives.
+        webhookExpected: !providerDecline,
+        recoveryRequired: false,
+        requestPayload: {
+          providerIdempotencyKey: input.providerIdempotencyKey,
+          providerRequestFingerprint: input.providerRequestFingerprint,
+          providerFlow: transient.flow,
+          amountMinor: input.amountMinor,
+          currency: input.currency,
+          orderRef: input.orderRef,
+          channelId: transient.flow === "pbl_one_time" ? transient.channelId : undefined,
+          // The model actually sent, not the one the client asked for — the single
+          // activation switch can make those diverge, and this field is where a
+          // diagnosis looks for the truth.
+          recurringModel: transient.flow === "blik_recurring_activation"
+            ? resolveRecurringModel(transient.recurringModel, modelOActivationEnabled)
+            : undefined,
+          methodRefPresent: transient.flow === "recurring_charge" || transient.flow === "blik_one_click"
+            ? Boolean(input.paymentMethodRef)
+            : undefined,
+          methodRefAliasType: transient.flow === "recurring_charge" || transient.flow === "blik_one_click"
+            ? input.paymentMethodAliasType ?? "PAYID"
+            : undefined,
+          aliasRegistrationRequested: transient.flow === "blik_one_time"
+            ? aliasRegistrationOnCodeEnabled
+            : undefined,
+        },
+        responsePayload: {
+          providerStatus: response.status,
+          providerAttemptId,
+          providerSessionId: response.transactionId,
+          requestId: response.requestId,
+          redirectUrlPresent: Boolean(response.transactionPaymentUrl),
+          payIdEligible: response.payIdEligible,
+          // Codes only. `errorMessage` is free-form prose that can carry
+          // payer-identifying text, so it never reaches our stored payload.
+          providerErrorCodes: (response.errors ?? []).map((error) => error.errorCode),
+          ...(declineEvidence ? { declineEvidence } : {}),
+          ...failureEvidencePayload(observation ? tpayFailureEvidence({
+            source: "execution", providerPaymentId: response.transactionId, refusalVerified: true,
+            flow: transient.flow, observation, errorCode: rejection?.errorCode, reading,
+          }) : null),
+        },
+      };
+    },
+  };
+}
+
+function requireTpayTransientInput(
+  input: PaymentExecutionInput,
+  options: { oneClickEnabled: boolean; modelOActivationEnabled: boolean },
+): TpayTransientProviderInput {
+  if (input.providerFlow === "blik_one_click") {
+    if (!options.oneClickEnabled) throw new TpayExecutionInputError("tpay_blik_one_click_not_enabled");
+    if (input.mode !== "one_time") throw new TpayExecutionInputError("tpay_blik_one_click_requires_one_time");
+    if (!input.paymentMethodRef) throw new TpayExecutionInputError("tpay_blik_one_click_payid_missing");
+    if (input.transientProviderInput && input.transientProviderInput.flow !== "blik_one_click") {
+      throw new TpayExecutionInputError("tpay_provider_flow_mismatch");
+    }
+    return { provider: PROVIDER_KIND, flow: "blik_one_click" };
+  }
+
+  if (input.providerFlow === "recurring_charge") {
+    if (input.mode !== "subscription_cycle") throw new TpayExecutionInputError("tpay_recurring_charge_requires_cycle");
+    if (!input.paymentMethodRef) throw new TpayExecutionInputError("tpay_recurring_charge_payid_missing");
+    if (input.paymentMethodAliasType && input.paymentMethodAliasType !== "PAYID") {
+      throw new TpayExecutionInputError("tpay_recurring_charge_requires_payid");
+    }
+    if (input.paymentMethodRecurringModel !== "O") {
+      throw new TpayExecutionInputError("tpay_recurring_charge_requires_model_o");
+    }
+    if (input.transientProviderInput && input.transientProviderInput.flow !== "recurring_charge") {
+      throw new TpayExecutionInputError("tpay_provider_flow_mismatch");
+    }
+    return { provider: PROVIDER_KIND, flow: "recurring_charge" };
+  }
+
+  const transient = input.transientProviderInput;
+  if (!transient || transient.provider !== PROVIDER_KIND) throw new TpayExecutionInputError("tpay_transient_input_missing");
+  if (input.providerFlow && input.providerFlow !== transient.flow) {
+    throw new TpayExecutionInputError("tpay_provider_flow_mismatch");
+  }
+  if (transient.flow === "blik_one_time" || transient.flow === "blik_recurring_activation") {
+    if (!transient.blikToken) throw new TpayExecutionInputError("tpay_blik_token_missing");
+  }
+  if (transient.flow === "pbl_one_time" && !transient.channelId) {
+    throw new TpayExecutionInputError("tpay_channel_id_missing");
+  }
+  if (transient.flow === "pbl_one_time" && input.mode !== "one_time") {
+    throw new TpayExecutionInputError("tpay_pbl_recurring_not_supported");
+  }
+  if (transient.flow === "blik_recurring_activation") {
+    if (!options.modelOActivationEnabled) {
+      throw new TpayExecutionInputError("tpay_blik_recurring_activation_not_enabled");
+    }
+    if (transient.recurringModel !== "O") {
+      throw new TpayExecutionInputError("tpay_blik_model_o_required");
+    }
+    if (input.mode !== "subscription_cycle") {
+      throw new TpayExecutionInputError("tpay_blik_recurring_activation_requires_subscription_cycle");
+    }
+    if (input.saveForFutureUse !== true) {
+      throw new TpayExecutionInputError("tpay_blik_recurring_activation_requires_save_for_future_use");
+    }
+  }
+  return transient;
+}
+
+function defaultPayer(input: PaymentExecutionInput): TpayPayerInput | null {
+  if (input.payer) return input.payer;
+  if (!input.customerRef) return null;
+  return { email: input.customerRef, name: "Customer" };
+}
+
+export class TpayExecutionInputError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "TpayExecutionInputError";
+  }
+}

package/src/payments/tpay/tpayPaymentReconciliationProvider.ts

@@ -0,0 +1,285 @@
+import type {
+  ProviderReconciliationStatus,
+} from "./donorContracts.js";
+import type {
+  PaymentProviderRecoveryProvider,
+  ProviderRecoveryAction,
+} from "./donorContracts.js";
+import type { TpayHttpClient } from "./tpayHttpClient.js";
+import { refusalCapture, tpayFailureEvidence } from "./tpayFailureEvidence.js";
+import { failureEvidencePayload } from "./paymentFailureEvidence.js";
+import { parseInstant, wallClockToUtc } from "./wallClockTime.js";
+import { declineCodeReading, type DeclineCodeReading } from "./declineFailureHints.js";
+import { attemptDeclineObservation, lastRefusalRow } from "./tpayDeclineEvidence.js";
+
+export function createTpayPaymentReconciliationProvider(
+  client: Pick<TpayHttpClient, "getTransaction">,
+): PaymentProviderRecoveryProvider {
+  return {
+    resolvePaymentReference(input) {
+      // Tpay's API address is its transactionId. `title`/TR-* is merchant
+      // display data, not a readback identifier.
+      return input.providerSessionId;
+    },
+    async readRecoveryPayment(input) {
+      const transaction = await client.getTransaction(input.providerPaymentId);
+      const status = normalizeTpayTransaction(transaction);
+      const identityMatches = tpayIdentityMatches(transaction, input.providerPaymentId);
+      const configuredMoneyMatches = tpayConfiguredMoneyMatches(transaction, input.attempt);
+      const manualReviewRequired = tpayMoneyMoved(transaction);
+      let clientAction: ProviderRecoveryAction | null = null;
+      if (identityMatches && !manualReviewRequired && status.status === "pending") {
+        const url = validatedTpayPaymentUrl(transaction);
+        clientAction = url ? { kind: "redirect", url } : null;
+      }
+      return { status, identityMatches, configuredMoneyMatches, manualReviewRequired, clientAction };
+    },
+    async readPayment(input) {
+      const transaction = await client.getTransaction(input.providerPaymentId);
+      return normalizeTpayTransaction(transaction);
+    },
+  };
+}
+
+function tpayMoneyMoved(transaction: Record<string, unknown>): boolean {
+  const status = readStatus(transaction).trim().toLowerCase();
+  return status === "chargeback" || status === "refunded";
+}
+
+function tpayIdentityMatches(transaction: Record<string, unknown>, providerPaymentId: string): boolean {
+  const actual = readOptionalString(transaction, "transactionId") ?? readOptionalString(transaction, "id");
+  return actual === providerPaymentId;
+}
+
+function tpayConfiguredMoneyMatches(
+  transaction: Record<string, unknown>,
+  attempt: { amountMinor: number; currency: string },
+): boolean {
+  return readConfiguredAmountMinor(transaction) === attempt.amountMinor
+    && readCurrency(transaction)?.toUpperCase() === attempt.currency.toUpperCase();
+}
+
+const TPAY_PAYMENT_HOSTS = new Set(["secure.tpay.com", "secure.sandbox.tpay.com"]);
+
+function validatedTpayPaymentUrl(transaction: Record<string, unknown>): string | null {
+  const raw = transaction.transactionPaymentUrl;
+  if (typeof raw !== "string" || raw.length === 0) return null;
+  try {
+    const parsed = new URL(raw);
+    return parsed.protocol === "https:"
+      && parsed.port === ""
+      && parsed.username === ""
+      && parsed.password === ""
+      && TPAY_PAYMENT_HOSTS.has(parsed.hostname.toLowerCase())
+      ? parsed.toString()
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+export function normalizeTpayTransaction(
+  transaction: Record<string, unknown>,
+): ProviderReconciliationStatus {
+  const providerStatus = readStatus(transaction);
+  const statusFromField = normalizeTpayStatus(providerStatus);
+  // This rail leaves its status field non-terminal when the bank refuses, reporting
+  // the reason beside it in TWO carriers instead — per attempt, and in an errors
+  // array — so reading only the status field left a refused charge polling forever
+  // (what stranded a renewal on 2026-08-12). Attempts win when both carry a code:
+  // being the dated carrier, they are the only one that can say which is current.
+  const payments = record(transaction.payments);
+  const refusal = statusFromField !== "succeeded"
+    ? lastRefusal(payments.attempts, "paymentErrorCode") ?? lastRefusal(payments.errors, "errorCode")
+    : null;
+  const status = refusal ? "failed" as const : statusFromField;
+  return {
+    status,
+    providerStatus,
+    occurredAt: refusal?.occurredAt ?? readDate(transaction),
+    failureReason: refusal
+      ? `tpay_decline_${refusal.code}`
+      : status === "failed" ? `tpay_${providerStatus}` : null,
+    amountMinor: readAmountMinor(transaction),
+    currency: readCurrency(transaction),
+    rawPayload: sanitizedTpayTransaction(transaction, providerStatus, refusal),
+  };
+}
+
+interface AttemptRefusal {
+  code: string;
+  occurredAt: string | null;
+  reading: DeclineCodeReading;
+}
+
+/**
+ * The last row carrying a refusal code, dated and read. The scan is shared with
+ * the execution path, which needs the same "which code does this stand on"
+ * answer the instant the provider refuses; only the date and the reading are
+ * added. Undated rows yield no instant, so the caller uses the charge's own date.
+ */
+function lastRefusal(rows: unknown, codeKey: string): AttemptRefusal | null {
+  const refusal = lastRefusalRow(rows, codeKey);
+  if (!refusal) return null;
+  return {
+    code: refusal.code,
+    occurredAt: parseAttemptDate(refusal.row.date),
+    reading: declineCodeReading(refusal.code),
+  };
+}
+
+/**
+ * This rail labels no timestamp with a zone, on either carrier, and both are its
+ * own local wall clock. Reading them as UTC moved every instant this adapter
+ * produced one or two hours into the future: on 2026-08-15 a decline that landed
+ * 14:46Z was recorded as 16:46Z, later than the cron run that wrote it. The zone
+ * belongs to the rail, not to the merchant, so it is named here — beside the
+ * carriers it explains — and passed to the generic conversion.
+ */
+const REPORTING_TIME_ZONE = "Europe/Warsaw";
+
+/** Attempt timestamps arrive as `DD.MM.YYYY HH:mm`, which `Date.parse` misreads. */
+function parseAttemptDate(value: unknown): string | null {
+  if (typeof value !== "string") return null;
+  const match = /^(\d{2})\.(\d{2})\.(\d{4})[ T](\d{2}):(\d{2})/.exec(value.trim());
+  if (!match) return parseDate(value);
+  const [, day, month, year, hour, minute] = match;
+  return wallClockToUtc(`${year}-${month}-${day}T${hour}:${minute}:00`, REPORTING_TIME_ZONE);
+}
+
+function normalizeTpayStatus(status: string): ProviderReconciliationStatus["status"] {
+  const normalized = status.trim().toLowerCase();
+  if (["correct", "paid", "true", "success", "settled"].includes(normalized)) return "succeeded";
+  if ([
+    "failed",
+    "failure",
+    "error",
+    "false",
+    "declined",
+    "rejected",
+    "cancelled",
+    "canceled",
+    "expired",
+  ].includes(normalized)) {
+    return "failed";
+  }
+  if ([
+    "new",
+    "pending",
+    "created",
+    "processing",
+    "in_progress",
+    "authorized",
+    "requires_action",
+    "pending_confirmation",
+  ].includes(normalized)) {
+    return "pending";
+  }
+  return "unknown";
+}
+
+function readStatus(transaction: Record<string, unknown>): string {
+  for (const key of ["status", "tr_status", "transactionStatus", "state"]) {
+    const raw = transaction[key];
+    if (typeof raw === "string" && raw.trim()) return raw.trim();
+    if (typeof raw === "boolean") return raw ? "true" : "false";
+  }
+  return "unknown";
+}
+
+function readDate(transaction: Record<string, unknown>): string | null {
+  const nestedDate = record(transaction.date);
+  for (const key of ["realization", "creation"]) {
+    const parsed = parseDate(nestedDate[key]);
+    if (parsed) return parsed;
+  }
+  for (const key of ["date", "updatedAt", "updated_at", "createdAt", "created_at"]) {
+    const parsed = parseDate(transaction[key]);
+    if (parsed) return parsed;
+  }
+  return null;
+}
+
+/** The transaction carrier sends `YYYY-MM-DD HH:mm:ss` — zone-less, so read in the rail's zone. */
+function parseDate(value: unknown): string | null {
+  return parseInstant(value, REPORTING_TIME_ZONE);
+}
+
+function readAmountMinor(transaction: Record<string, unknown>): number | null {
+  return readAmountMinorFrom(
+    transaction,
+    ["amountMinor", "paidAmountMinor", "tr_amount_minor", "tr_paid_minor"],
+    ["paidAmount", "amount", "tr_paid", "tr_amount"],
+  );
+}
+
+function readConfiguredAmountMinor(transaction: Record<string, unknown>): number | null {
+  return readAmountMinorFrom(transaction, ["amountMinor", "tr_amount_minor"], ["amount", "tr_amount"]);
+}
+
+function readAmountMinorFrom(
+  transaction: Record<string, unknown>,
+  minorKeys: readonly string[],
+  majorKeys: readonly string[],
+): number | null {
+  for (const key of minorKeys) {
+    const raw = transaction[key];
+    if (typeof raw === "number" && Number.isFinite(raw)) return Math.round(raw);
+    if (typeof raw === "string" && /^\d+$/.test(raw.trim())) return Number(raw);
+  }
+  for (const key of majorKeys) {
+    const raw = transaction[key];
+    const value = typeof raw === "number" ? raw : typeof raw === "string" ? Number(raw.replace(",", ".")) : NaN;
+    if (Number.isFinite(value)) return Math.round(value * 100);
+  }
+  return null;
+}
+
+function readCurrency(transaction: Record<string, unknown>): string | null {
+  for (const key of ["currency", "tr_currency"]) {
+    const raw = transaction[key];
+    if (typeof raw === "string" && raw.trim().length === 3) return raw.trim().toUpperCase();
+  }
+  return null;
+}
+
+/**
+ * Classification goes through the shared `classifyDecline` seam, the same one
+ * the synchronous path and the card rail use, so there is exactly one place a
+ * refusal becomes a class. Only neutral evidence crosses: this provider's code
+ * vocabulary is translated here and travels no further. Since PR 2724 the class
+ * reaches the case and becomes the payer's cause sentence; it is no cadence input.
+ */
+
+function sanitizedTpayTransaction(
+  transaction: Record<string, unknown>,
+  providerStatus: string,
+  refusal: AttemptRefusal | null = null,
+): Record<string, unknown> {
+  return {
+    // Before this, the only record of why a charge failed was discarded on
+    // every poll.
+    ...(refusal ? refusalCapture(refusal, `tpay_decline_${refusal.code}`) : {}),
+    ...failureEvidencePayload(refusal || ["failed", "failure", "error", "false", "declined", "rejected"].includes(providerStatus.trim().toLowerCase()) ? tpayFailureEvidence({
+      source: "readback", providerPaymentId: readOptionalString(transaction, "transactionId"),
+      refusalVerified: true, flow: null,
+      observation: refusal ? { code: refusal.code, disposition: "present" } : attemptDeclineObservation(transaction), reading: refusal?.reading,
+    }) : null),
+    provider: "tpay",
+    transactionId: readOptionalString(transaction, "transactionId") ?? readOptionalString(transaction, "id"),
+    title: readOptionalString(transaction, "title") ?? readOptionalString(transaction, "tr_id"),
+    status: providerStatus,
+    requestIdPresent: Boolean(readOptionalString(transaction, "requestId")),
+    amountMinorPresent: readAmountMinor(transaction) !== null,
+    currency: readCurrency(transaction),
+  };
+}
+
+function readOptionalString(value: Record<string, unknown>, key: string): string | null {
+  const raw = value[key];
+  return typeof raw === "string" && raw.trim() ? raw.trim() : null;
+}
+
+function record(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : {};
+}