@openlup/platform 0.19.0 → 0.21.0

package/dist/payments/tpay/tpayPaymentExecutionAdapter.js

@@ -0,0 +1,249 @@
+import { failureEvidencePayload } from "./paymentFailureEvidence.js";
+import { tpayFailureEvidence } from "./tpayFailureEvidence.js";
+import { aliasValue, buildCreateTransactionInput, resolveRecurringModel, } from "./tpayCreateTransactionInput.js";
+import { declineCodeReading } from "./declineFailureHints.js";
+import { assertableHints, isMandateRefusal, mandateCapabilityReadable, readAttemptDeclineObservation, declineEvidenceSource, states, } from "./tpayDeclineEvidence.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";
+export function createTpayPaymentExecutionAdapter({ client, notificationUrl, successUrl, errorUrl, oneClickEnabled = false, aliasRegistrationOnCodeEnabled = false, modelOActivationEnabled = false, resolvePayer = defaultPayer, }) {
+    const validateInput = (input) => {
+        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) {
+            validateInput(input);
+        },
+        async execute(input) {
+            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, options) {
+    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) {
+    if (input.payer)
+        return input.payer;
+    if (!input.customerRef)
+        return null;
+    return { email: input.customerRef, name: "Customer" };
+}
+export class TpayExecutionInputError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "TpayExecutionInputError";
+    }
+}

package/dist/payments/tpay/tpayPaymentReconciliationProvider.d.ts

@@ -0,0 +1,5 @@
+import type { ProviderReconciliationStatus } from "./donorContracts.js";
+import type { PaymentProviderRecoveryProvider } from "./donorContracts.js";
+import type { TpayHttpClient } from "./tpayHttpClient.js";
+export declare function createTpayPaymentReconciliationProvider(client: Pick<TpayHttpClient, "getTransaction">): PaymentProviderRecoveryProvider;
+export declare function normalizeTpayTransaction(transaction: Record<string, unknown>): ProviderReconciliationStatus;

package/dist/payments/tpay/tpayPaymentReconciliationProvider.js

@@ -0,0 +1,244 @@
+import { refusalCapture, tpayFailureEvidence } from "./tpayFailureEvidence.js";
+import { failureEvidencePayload } from "./paymentFailureEvidence.js";
+import { parseInstant, wallClockToUtc } from "./wallClockTime.js";
+import { declineCodeReading } from "./declineFailureHints.js";
+import { attemptDeclineObservation, lastRefusalRow } from "./tpayDeclineEvidence.js";
+export function createTpayPaymentReconciliationProvider(client) {
+    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 = 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) {
+    const status = readStatus(transaction).trim().toLowerCase();
+    return status === "chargeback" || status === "refunded";
+}
+function tpayIdentityMatches(transaction, providerPaymentId) {
+    const actual = readOptionalString(transaction, "transactionId") ?? readOptionalString(transaction, "id");
+    return actual === providerPaymentId;
+}
+function tpayConfiguredMoneyMatches(transaction, attempt) {
+    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) {
+    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) {
+    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" : 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),
+    };
+}
+/**
+ * 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, codeKey) {
+    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) {
+    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) {
+    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) {
+    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) {
+    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) {
+    return parseInstant(value, REPORTING_TIME_ZONE);
+}
+function readAmountMinor(transaction) {
+    return readAmountMinorFrom(transaction, ["amountMinor", "paidAmountMinor", "tr_amount_minor", "tr_paid_minor"], ["paidAmount", "amount", "tr_paid", "tr_amount"]);
+}
+function readConfiguredAmountMinor(transaction) {
+    return readAmountMinorFrom(transaction, ["amountMinor", "tr_amount_minor"], ["amount", "tr_amount"]);
+}
+function readAmountMinorFrom(transaction, minorKeys, majorKeys) {
+    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) {
+    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, providerStatus, refusal = null) {
+    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, key) {
+    const raw = value[key];
+    return typeof raw === "string" && raw.trim() ? raw.trim() : null;
+}
+function record(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}

package/dist/payments/tpay/tpayTransactionPayload.d.ts

@@ -0,0 +1,120 @@
+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[];
+}
+/**
+ * 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 declare function buildTpayTransactionPayload(input: TpayTransactionCreateInput): Record<string, unknown>;