@openlup/platform 0.19.0 → 0.21.0

package/src/payments/tpay/tpayTransactionPayload.ts

@@ -0,0 +1,207 @@
+export interface TpayPayerInput {
+  email: string;
+  name: string;
+  ip?: string | null;
+  userAgent?: string | null;
+}
+
+/**
+ * BLIK alias sent on transaction create.
+ *
+ * `UID` is merchant-scoped one-click; `PAYID` is the recurring mandate.
+ * `recommendedAuthLevel` is a SIBLING of `autopayment`, not a field inside it
+ * (Tpay SDK `Model/Objects/Transactions/Alias.php`), and Tpay documents it as
+ * available and required only for autopayment model `O`, where it omits the
+ * per-charge authorization screen.
+ */
+export interface TpayAliasInput {
+  value: string;
+  type: "UID" | "PAYID";
+  label?: string;
+  recommendedAuthLevel?: "NOCONFREQ";
+  /**
+   * Collect immediately instead of giving the payer 72 hours to approve. Required
+   * on every model `O` charge; available for models `A` and `O` only.
+   */
+  noDelay?: boolean;
+  /**
+   * `frequency` is deliberately absent: Tpay requires it for model `A`, treats it
+   * as optional for `M`, and does not accept it for `O`. We only ever register
+   * variable-amount mandates, so no caller needs it.
+   */
+  autopayment?: { model: "A" | "M" | "O" };
+}
+
+export interface TpayTransactionCreateInput {
+  amount: number;
+  currency: "PLN";
+  description: string;
+  hiddenDescription: string;
+  payer: TpayPayerInput;
+  notificationUrl: string;
+  successUrl: string;
+  errorUrl: string;
+  groupId?: number;
+  channelId?: string;
+  blikPaymentType?: 2;
+  blikToken?: string;
+  /**
+   * Ask BLIK to reject the transaction outright when the payer's bank does not
+   * support recurring payments, instead of taking the money and silently never
+   * showing the mandate invitation. Only meaningful when registering a `PAYID`
+   * alias; never set it for a plain one-off BLIK payment.
+   */
+  refuseNoPayId?: boolean;
+  alias?: TpayAliasInput | null;
+  simulatorContext?: {
+    orderId?: string;
+    paymentIntentId: string;
+    clientId?: string;
+    /** Stable per provider attempt; simulator-only and never sent to Tpay. */
+    providerAttemptKey?: string;
+    /**
+     * In-account terminal path the simulator panel returns to after the buyer
+     * settles (account `returnContext` only). Absent for the public flow, which
+     * keeps the simulator page's own `/checkout/payment` return so the
+     * public path stays byte-identical (and client-side localized).
+     */
+    returnPath?: string;
+  };
+}
+
+/** One entry of Tpay's `payments.errors[]`. `errorCode` is low-cardinality. */
+export interface TpayPaymentError {
+  errorCode: string;
+  errorMessage: string;
+  fieldName: string | null;
+}
+
+/**
+ * Create-transaction result.
+ *
+ * ⚠️ Tpay signals a synchronous BLIK rejection ONLY through `payments.errors[]`
+ * and the absence of `payments.payIdEligible`. Verified against production
+ * 2026-07-20: a rejected recurring BLIK still returns HTTP 200 with
+ * `result: "success"`, top-level `status: "pending"` AND `payments.status:
+ * "pending"`. Those three fields therefore prove nothing — never branch on them
+ * to decide success. `payments.method` is equally useless: it reads
+ * `"pay_by_link"` even for a settled BLIK PayID charge.
+ *
+ * This matters because Tpay has no async channel for failures — the transaction
+ * webhook's `tr_status` only ever carries `true` or `chargeback`, so a decline
+ * that is not read out of this response is never reported at all.
+ */
+export interface TpayTransactionCreated {
+  transactionId: string;
+  title: string;
+  status: string;
+  transactionPaymentUrl: string | null;
+  requestId: string | null;
+  /**
+   * Whether BLIK considers the payer's bank capable of registering a PayID
+   * mandate. Present and `true` when eligible; absent entirely when Tpay
+   * rejected the transaction.
+   *
+   * ⚠️ UNDOCUMENTED — observed empirically, absent from Tpay's OpenAPI spec and
+   * from their official SDK. Treat as a hint that may vanish without notice and
+   * always keep `errors` as the fallback signal.
+   */
+  payIdEligible: boolean | null;
+  /** Synchronous provider errors. Empty when the request was accepted. */
+  errors: TpayPaymentError[];
+}
+
+/**
+ * Per-field maxima Tpay enforces on `payer.*`, read from the provider's own SDK
+ * rather than inferred. In `tpay-com/tpay-openapi-php`,
+ * `src/Model/Objects/Transactions/Payer.php` binds every accepted wire key to a
+ * field model, and each model declares the `$maxLength` the API applies:
+ *
+ *   email      `src/Model/Fields/Person/Email.php`      255
+ *   name       `src/Model/Fields/Payer/Name.php`        255
+ *   ip         `src/Model/Fields/Payer/IP.php`          255
+ *   userAgent  `src/Model/Fields/Payer/UserAgent.php`   255
+ *
+ * ⚠️ The unit is BYTES, not characters: `src/Model/Fields/FieldValidator.php`
+ * measures with PHP `strlen()`, which counts bytes. A 255-CHARACTER name in an
+ * accented or non-Latin script can be far more than 255 bytes in UTF-8 and would
+ * still be refused, so the clamp below counts bytes.
+ *
+ * An over-long field is refused synchronously with HTTP 400 `not_valid`. On BLIK
+ * the code then never reaches the bank and the buyer sees no prompt at all: the
+ * Facebook iOS in-app WebView user agent is 271 characters, which cost four
+ * orders and two cancelled subscriptions from 2026-08-28.
+ */
+const TPAY_PAYER_MAX_BYTES = {
+  email: 255,
+  name: 255,
+  ip: 255,
+  userAgent: 255,
+} as const;
+
+/**
+ * Fits one payer field inside the provider's documented maximum.
+ *
+ * ⛔ Truncate, never omit, and for every one of the four keys. `Field.php` runs
+ * a `pattern` check only for models that declare one and none of these four
+ * does, so a truncated value stays structurally valid; `getRequiredFields()`
+ * makes `email` and `name` mandatory, so dropping either only buys a different
+ * 400; and `ts:request:no_ip` is a real provider error, so dropping `ip` trades
+ * one refusal for another. Truncation also keeps the prefix that a fraud review
+ * or a support ticket can still read.
+ *
+ * Lives here, in the single function that serialises the wire body, so no payer
+ * producer can bypass it.
+ */
+function payerFieldWithinLimit(key: keyof typeof TPAY_PAYER_MAX_BYTES, value: string): string {
+  const maxBytes = TPAY_PAYER_MAX_BYTES[key];
+  const bytes = new TextEncoder().encode(value);
+  if (bytes.length <= maxBytes) return value;
+  let end = maxBytes;
+  // Never cut inside a code point: UTF-8 continuation bytes are 0b10xxxxxx, so
+  // walk back off them rather than emitting a replacement character.
+  while (end > 0 && (bytes[end] & 0xc0) === 0x80) end -= 1;
+  return new TextDecoder().decode(bytes.subarray(0, end));
+}
+
+/**
+ * Builds the `POST /transactions` wire payload.
+ *
+ * Every BLIK-specific field lives under `pay.blikPaymentData`; `aliases` carries
+ * the mandate. `refuseNoPayId` sits beside `aliases` (not inside it), while
+ * `recommendedAuthLevel` and `noDelay` sit inside the alias object as siblings of
+ * `autopayment` — matching Tpay's SDK object model and verified against
+ * production on 2026-07-20.
+ */
+export function buildTpayTransactionPayload(input: TpayTransactionCreateInput): Record<string, unknown> {
+  const pay: Record<string, unknown> = {};
+  if (input.groupId) pay.groupId = input.groupId;
+  if (input.channelId) pay.channelId = input.channelId;
+  if (input.blikToken || input.alias) {
+    pay.blikPaymentData = {
+      ...(input.blikPaymentType ? { type: input.blikPaymentType } : {}),
+      ...(input.blikToken ? { blikToken: input.blikToken } : {}),
+      ...(input.refuseNoPayId ? { refuseNoPayId: true } : {}),
+      ...(input.alias ? { aliases: input.alias } : {}),
+    };
+  }
+  return {
+    amount: input.amount,
+    currency: input.currency,
+    description: input.description,
+    hiddenDescription: input.hiddenDescription,
+    payer: {
+      email: payerFieldWithinLimit("email", input.payer.email),
+      name: payerFieldWithinLimit("name", input.payer.name),
+      ...(input.payer.ip ? { ip: payerFieldWithinLimit("ip", input.payer.ip) } : {}),
+      ...(input.payer.userAgent
+        ? { userAgent: payerFieldWithinLimit("userAgent", input.payer.userAgent) }
+        : {}),
+    },
+    ...(Object.keys(pay).length > 0 ? { pay } : {}),
+    callbacks: {
+      notification: { url: input.notificationUrl },
+      payerUrls: { success: input.successUrl, error: input.errorUrl },
+    },
+  };
+}

package/src/payments/tpay/wallClockTime.ts

@@ -0,0 +1,57 @@
+/**
+ * Reading a timestamp from a rail that does not say what clock it is on.
+ *
+ * A value carrying `Z` or `±HH:mm` is already an instant and is honoured as
+ * written. A value without one is a WALL CLOCK — a label on someone's local
+ * time — and turning it into an instant needs the zone that clock runs on.
+ * `Date.parse` resolves such a value against the HOST zone, which is a silent
+ * trap: it reads correct on a laptop set to the rail's own zone and skews by
+ * the offset on the UTC runtime that serves production. Callers therefore pass
+ * the zone explicitly; there is no default, because a wrong default is exactly
+ * the bug this module exists to remove.
+ */
+
+/** A date-time with no `Z` and no `±HH:mm`, i.e. a bare wall-clock label. */
+const ZONELESS_DATE_TIME = /^(\d{4}-\d{2}-\d{2})[ T](\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?)$/;
+
+/** Milliseconds `timeZone` is ahead of UTC at `at` (negative when west of it). */
+function zoneOffsetMs(at: Date, timeZone: string): number {
+  const zone = new Intl.DateTimeFormat("en", { timeZone, timeZoneName: "longOffset" })
+    .formatToParts(at).find((part) => part.type === "timeZoneName")?.value;
+  const match = /^GMT([+-])(\d{1,2}):(\d{2})$/.exec(zone ?? "");
+  if (!match) return 0;
+  const [, sign, hours, minutes] = match;
+  return (sign === "-" ? -1 : 1) * (Number(hours) * 60 + Number(minutes)) * 60_000;
+}
+
+/**
+ * The UTC instant of a zone-less `YYYY-MM-DDTHH:mm[:ss]` read in `timeZone`.
+ *
+ * Two passes, because the offset is a function of the answer being computed:
+ * the first prices the naive reading, the second re-prices it at the instant
+ * that produced. That is what makes the conversion hold on both sides of a DST
+ * transition rather than only in the half-year it was written in — a single
+ * pass reads the hour after a spring-forward an hour early. A local time the
+ * transition skips or repeats resolves through the offset in force at the first
+ * pass; no wall clock can separate those two readings.
+ */
+export function wallClockToUtc(wallClock: string, timeZone: string): string | null {
+  const asIfUtc = Date.parse(`${wallClock}Z`);
+  if (!Number.isFinite(asIfUtc)) return null;
+  const firstPass = asIfUtc - zoneOffsetMs(new Date(asIfUtc), timeZone);
+  return new Date(asIfUtc - zoneOffsetMs(new Date(firstPass), timeZone)).toISOString();
+}
+
+/**
+ * An ISO UTC instant for `value`, or `null` when it does not carry one. A
+ * zone-less value is read as a wall clock in `timeZone`; a value stating its
+ * own offset keeps it. Never invents an instant — the absence of a readable
+ * timestamp must stay distinguishable from a timestamp.
+ */
+export function parseInstant(value: unknown, timeZone: string): string | null {
+  if (typeof value !== "string" || !value.trim()) return null;
+  const trimmed = value.trim();
+  const zoneless = ZONELESS_DATE_TIME.exec(trimmed);
+  if (zoneless) return wallClockToUtc(`${zoneless[1]}T${zoneless[2]}`, timeZone);
+  return Number.isFinite(Date.parse(trimmed)) ? new Date(trimmed).toISOString() : null;
+}

package/src/payments/tpay/webhookJwsVerifier.ts

@@ -0,0 +1,82 @@
+import { verify as verifySignature, X509Certificate } from "node:crypto";
+
+export interface TpayJwsCertificateResolver {
+  (url: string): Promise<string>;
+}
+
+export interface TpayJwsVerificationInput {
+  rawBody: string;
+  signatureHeader: string | undefined;
+  resolveCertificate: TpayJwsCertificateResolver;
+  rootCertificatePem: string;
+  allowedX5uPrefix?: string;
+  verifyCertificateChain?: (signingCertificatePem: string, rootCertificatePem: string) => boolean;
+  verifyDetachedSignature?: (input: {
+    signingInput: string;
+    signature: Buffer;
+    signingCertificatePem: string;
+  }) => boolean;
+}
+
+export async function verifyTpayJwsSignature({
+  rawBody,
+  signatureHeader,
+  resolveCertificate,
+  rootCertificatePem,
+  allowedX5uPrefix = "https://secure.sandbox.tpay.com/",
+  verifyCertificateChain: verifyChain = verifyCertificateChain,
+  verifyDetachedSignature: verifyDetached = defaultVerifyDetachedSignature,
+}: TpayJwsVerificationInput): Promise<boolean> {
+  if (!signatureHeader || !rootCertificatePem) return false;
+  const parts = signatureHeader.split(".");
+  if (parts.length < 3 || !parts[0] || !parts[2]) return false;
+  const header = parseJwsHeader(parts[0]);
+  if (!header?.x5u || !header.x5u.startsWith(allowedX5uPrefix)) return false;
+
+  const signingCertificatePem = await resolveCertificate(header.x5u);
+  if (!verifyChain(signingCertificatePem, rootCertificatePem)) return false;
+
+  const signedPayload = `${parts[0]}.${base64Url(Buffer.from(rawBody, "utf8"))}`;
+  const signature = base64UrlDecode(parts[2]);
+  return verifyDetached({ signingInput: signedPayload, signature, signingCertificatePem });
+}
+
+function parseJwsHeader(encoded: string): { x5u?: string } | null {
+  try {
+    const parsed = JSON.parse(base64UrlDecode(encoded).toString("utf8")) as unknown;
+    if (!parsed || typeof parsed !== "object") return null;
+    const x5u = (parsed as Record<string, unknown>).x5u;
+    return typeof x5u === "string" ? { x5u } : null;
+  } catch {
+    return null;
+  }
+}
+
+function verifyCertificateChain(signingCertificatePem: string, rootCertificatePem: string): boolean {
+  try {
+    const signing = new X509Certificate(signingCertificatePem);
+    const root = new X509Certificate(rootCertificatePem);
+    return signing.verify(root.publicKey);
+  } catch {
+    return false;
+  }
+}
+
+function defaultVerifyDetachedSignature(input: {
+  signingInput: string;
+  signature: Buffer;
+  signingCertificatePem: string;
+}): boolean {
+  const publicKey = new X509Certificate(input.signingCertificatePem).publicKey;
+  return verifySignature("RSA-SHA256", Buffer.from(input.signingInput), publicKey, input.signature);
+}
+
+function base64Url(value: Buffer): string {
+  return value.toString("base64").replace(/=/g, "").replace(/\+/g, "-").replace(/\//g, "_");
+}
+
+function base64UrlDecode(value: string): Buffer {
+  const normalized = value.replace(/-/g, "+").replace(/_/g, "/");
+  const padded = normalized.padEnd(normalized.length + ((4 - normalized.length % 4) % 4), "=");
+  return Buffer.from(padded, "base64");
+}

package/src/payments/tpay/webhookNormalizer.ts

@@ -0,0 +1,279 @@
+import type {
+  PaymentMethodLifecycleEvent,
+  PaymentMethodLifecycleEventKind,
+} from "@openlup/core/payment";
+
+const PROVIDER_KIND = "tpay";
+
+/**
+ * Alias-rail event names, mapped to the neutral lifecycle vocabulary.
+ *
+ * ⛔ `ALIAS_UPDATE` is a ROTATION, not a death: the payer's standing consent is
+ * unchanged and only the alias behind it moves. Classifying it with the two
+ * terminal names would strip a healthy subscription of the mandate it renews
+ * on. That is why the `active` flag below already treats register and update
+ * alike, and why this table must keep them apart from unregister and expiry.
+ */
+const ALIAS_LIFECYCLE_KINDS: Record<string, PaymentMethodLifecycleEventKind> = {
+  ALIAS_REGISTER: "method_registered",
+  ALIAS_UPDATE: "method_updated",
+  ALIAS_UNREGISTER: "method_revoked",
+  ALIAS_EXPIRED: "method_expired",
+};
+
+type TpayCanonicalPaymentEvent = {
+  provider_event_id: string;
+  event_type:
+    | "payment.succeeded"
+    | "payment.failed"
+    | "payment.refunded"
+    | "payment.requires_action"
+    | "payment.disputed"
+    | "setup.succeeded"
+    | "setup.failed"
+    | "setup.requires_action";
+  payment_provider_id: string;
+  payment_intent_id?: string | null;
+  amount_minor?: number;
+  raw_payload: Record<string, unknown>;
+};
+
+export interface NormalizedTpayMethodRef {
+  clientId: string | null;
+  subscriptionId?: string | null;
+  providerMethodRef: string;
+  methodKind: "blik_payid";
+  status: "active" | "inactive";
+  consentSnapshot: Record<string, unknown>;
+}
+
+export interface NormalizedTpayWebhook {
+  event: TpayCanonicalPaymentEvent;
+  methodRef: NormalizedTpayMethodRef | null;
+  /**
+   * The neutral transition this delivery reports about the stored mandate. The
+   * instant it happened is not known at this layer, so the full neutral event
+   * is assembled by the provider-webhook mapper below.
+   */
+  methodLifecycleKind: PaymentMethodLifecycleEventKind | null;
+  responseBody: "TRUE";
+}
+
+type NormalizedTpayProviderWebhook = {
+  provider: typeof PROVIDER_KIND;
+  providerEventId: string;
+  eventType: TpayCanonicalPaymentEvent["event_type"];
+  providerPaymentId: string;
+  paymentIntentId?: string | null;
+  amountMinor: number | null;
+  currency: string | null;
+  occurredAt: string;
+  rawPayload: Record<string, unknown>;
+  reusableMethod: {
+    clientId: string;
+    subscriptionId: string | null;
+    providerCustomerRef: null;
+    providerMethodRef: string;
+    providerMandateRef: null;
+    methodKind: "blik_payid";
+    status: "active" | "inactive";
+    consentSnapshot: Record<string, unknown>;
+  } | null;
+  methodLifecycle: PaymentMethodLifecycleEvent | null;
+};
+
+export function normalizeTpayWebhook(rawBody: string): NormalizedTpayWebhook {
+  const payload = parsePayload(rawBody);
+  const aliasEvent = payload.event;
+  if (aliasEvent) {
+    return normalizeAliasWebhook(payload);
+  }
+  return normalizeTransactionWebhook(payload);
+}
+
+export function toNormalizedProviderTpayWebhook(
+  webhook: NormalizedTpayWebhook,
+  occurredAt: string,
+): NormalizedTpayProviderWebhook {
+  return {
+    provider: PROVIDER_KIND,
+    providerEventId: webhook.event.provider_event_id,
+    eventType: webhook.event.event_type,
+    providerPaymentId: webhook.event.payment_provider_id,
+    paymentIntentId: webhook.event.payment_intent_id ?? null,
+    amountMinor: webhook.event.amount_minor ?? null,
+    currency: readCurrency(webhook.event.raw_payload),
+    occurredAt,
+    rawPayload: webhook.event.raw_payload,
+    reusableMethod: toReusableMethod(webhook.methodRef),
+    // The alias value IS the stored method reference on this rail. The rail
+    // publishes no scheme label or digits with an alias transition, and its
+    // expiry field is deliberately not read here (see the wave plan): a
+    // transition on this rail is a state change, not a facts refresh.
+    methodLifecycle: webhook.methodLifecycleKind
+      ? {
+        kind: webhook.methodLifecycleKind,
+        providerKind: PROVIDER_KIND,
+        providerMethodRef: webhook.event.payment_provider_id,
+        providerEventId: webhook.event.provider_event_id,
+        occurredAt,
+        replacement: null,
+      }
+      : null,
+  };
+}
+
+function normalizeTransactionWebhook(payload: Record<string, string>): NormalizedTpayWebhook {
+  const transactionTitle = required(payload, "tr_id");
+  const rawStatus = required(payload, "tr_status");
+  // Tpay production sends `tr_status` UPPERCASE ("TRUE"/"CHARGEBACK"); a
+  // case-sensitive compare mislabels every real success as payment.failed
+  // (caught live 2026-07-13 via a production payment-link). Classify
+  // case-insensitively; keep the raw value in raw_payload for observability.
+  const status = rawStatus.toLowerCase();
+  const amountMinor = amountToMinor(payload.tr_paid || payload.tr_amount);
+  const paymentIntentId = parseUuid(payload.tr_crc);
+  return {
+    event: {
+      // Only chargebacks split identity; every other status keeps its legacy keys.
+      provider_event_id: status === "chargeback" ? `${transactionTitle}:chargeback` : transactionTitle,
+      event_type: status === "chargeback" ? "payment.refunded" : status === "true" ? "payment.succeeded" : "payment.failed",
+      payment_provider_id: transactionTitle,
+      payment_intent_id: paymentIntentId,
+      amount_minor: amountMinor,
+      raw_payload: {
+        provider: PROVIDER_KIND,
+        eventKind: "transaction",
+        transactionTitle,
+        hiddenDescription: payload.tr_crc ?? null,
+        transactionAmount: payload.tr_amount ?? null,
+        paidAmount: payload.tr_paid ?? null,
+        // Null, not the settlement default: this records what the provider SAID,
+        // and a currency it did not send is unknown. The whole path was already
+        // built for that - `NormalizedTpayProviderWebhook.currency` is typed
+        // `string | null` and `readCurrency` below returns null for an absent or
+        // blank field - so the old `?? "PLN"` was manufacturing an operand rather
+        // than filling a gap.
+        //
+        // It does not weaken the SQL cross-check either. `commerce_payment_control_
+        // apply_result` guards `v_event.currency IS NOT NULL AND v_event.currency <>
+        // v_intent.currency`; a fabricated code cannot detect a real mismatch, it can
+        // only compare equal by luck in a PLN deployment or raise a *false*
+        // `payment_control_result_currency_mismatch` in one that settles elsewhere and
+        // refuse a legitimate payment. Skipping a comparison nobody can make beats
+        // making one against an invented value.
+        currency: payload.tr_currency ?? null,
+        status: rawStatus,
+        testMode: payload.test_mode ?? null,
+      },
+    },
+    methodRef: null,
+    methodLifecycleKind: null,
+    responseBody: "TRUE",
+  };
+}
+
+function normalizeAliasWebhook(payload: Record<string, string>): NormalizedTpayWebhook {
+  const aliasValue = required(payload, "msg_value[value]");
+  // Tpay sends alias event names UPPERCASE; normalize defensively so the
+  // classification can never be defeated by casing (see tr_status above).
+  const event = required(payload, "event").toUpperCase();
+  const active = event === "ALIAS_REGISTER" || event === "ALIAS_UPDATE";
+  const paymentIntentId = paymentIntentIdFromAlias(aliasValue);
+  return {
+    event: {
+      provider_event_id: `${event}:${aliasValue}`,
+      event_type: active ? "setup.succeeded" : "setup.failed",
+      payment_provider_id: aliasValue,
+      payment_intent_id: paymentIntentId,
+      raw_payload: {
+        provider: PROVIDER_KIND,
+        eventKind: "blik_alias",
+        event,
+        paymentIntentId,
+        aliasValuePresent: true,
+        aliasType: payload["msg_value[type]"] ?? null,
+        aliasExpirationDatePresent: Boolean(payload["msg_value[expirationDate]"]),
+      },
+    },
+    methodRef: {
+      clientId: payload.client_id ?? null,
+      subscriptionId: payload.subscription_id ?? null,
+      providerMethodRef: aliasValue,
+      methodKind: "blik_payid",
+      status: active ? "active" : "inactive",
+      consentSnapshot: { source: "tpay.alias.webhook", event },
+    },
+    methodLifecycleKind: ALIAS_LIFECYCLE_KINDS[event] ?? null,
+    responseBody: "TRUE",
+  };
+}
+
+function toReusableMethod(
+  methodRef: NormalizedTpayMethodRef | null,
+): NormalizedTpayProviderWebhook["reusableMethod"] {
+  if (!methodRef?.clientId) return null;
+  return {
+    clientId: methodRef.clientId,
+    subscriptionId: methodRef.subscriptionId ?? null,
+    providerCustomerRef: null,
+    providerMethodRef: methodRef.providerMethodRef,
+    providerMandateRef: null,
+    methodKind: methodRef.methodKind,
+    status: methodRef.status,
+    consentSnapshot: methodRef.consentSnapshot,
+  };
+}
+
+function readCurrency(payload: Record<string, unknown>): string | null {
+  const currency = payload.currency;
+  return typeof currency === "string" && currency.trim() ? currency : null;
+}
+
+function parsePayload(rawBody: string): Record<string, string> {
+  const trimmed = rawBody.trim();
+  if (trimmed.startsWith("{")) {
+    const parsed = JSON.parse(trimmed) as Record<string, unknown>;
+    return flattenJson(parsed);
+  }
+  const params = new URLSearchParams(rawBody);
+  return Object.fromEntries(Array.from(params.entries()));
+}
+
+function flattenJson(value: Record<string, unknown>, prefix = ""): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [key, raw] of Object.entries(value)) {
+    const name = prefix ? `${prefix}[${key}]` : key;
+    if (raw && typeof raw === "object" && !Array.isArray(raw)) {
+      Object.assign(out, flattenJson(raw as Record<string, unknown>, name));
+    } else if (raw !== undefined && raw !== null) {
+      out[name] = String(raw);
+    }
+  }
+  return out;
+}
+
+function required(payload: Record<string, string>, key: string): string {
+  const value = payload[key];
+  if (!value) throw new Error(`tpay_webhook_missing_${key}`);
+  return value;
+}
+
+function amountToMinor(value: string | undefined): number | undefined {
+  if (!value) return undefined;
+  const numeric = Number(value.replace(",", "."));
+  return Number.isFinite(numeric) ? Math.round(numeric * 100) : undefined;
+}
+
+function paymentIntentIdFromAlias(value: string): string | null {
+  const match = /^openlup_([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12})$/i.exec(value);
+  return match ? match[1].toLowerCase() : null;
+}
+
+function parseUuid(value: string | undefined): string | null {
+  if (!value) return null;
+  const trimmed = value.trim();
+  return /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(trimmed)
+    ? trimmed.toLowerCase()
+    : null;
+}