create-freeholder 0.0.0-bootstrap.0 → 0.2.0-beta.2

package/dist/template/src/adapters/payments/flutterwave.ts

@@ -0,0 +1,239 @@
+// Copyright (C) 2026 Tony Aly
+// SPDX-License-Identifier: Apache-2.0
+// Flutterwave Standard with verified settlement, refunds, and signed feedback.
+
+import { env } from "@/core/env";
+import { AdapterError } from "../types";
+import { decimalToMinor, minorToDecimal } from "./currency";
+import { object, paymentFetch, providerJson, text } from "./http";
+import {
+  bodyEventId,
+  deterministicProviderRef,
+  parseProviderJson,
+  providerIdentifier,
+  providerTime,
+  refuseOffSessionCharge,
+  refuseRecurringSchedule,
+  unsupportedSavedMethod,
+  verifyProviderHmac,
+} from "./provider-helpers";
+import type { PaymentAdapter, PaymentAdapterCapabilities } from "./types";
+
+const capabilities: PaymentAdapterCapabilities = {
+  refunds: true,
+  partialRefunds: true,
+  savedMethods: false,
+  subscriptions: false,
+  offSessionCharges: false,
+  disputes: false,
+  payouts: false,
+  inPerson: false,
+  strongCustomerAuthentication: true,
+};
+
+export interface FlutterwavePaymentOptions {
+  secretKey?: string;
+  webhookSecrets?: readonly string[];
+  apiBase?: string;
+  webhookUrl?: string;
+  fetch?: typeof fetch;
+}
+
+function flutterwaveData(payload: Record<string, unknown>): Record<string, unknown> {
+  const data = object(payload.data);
+  if (!data) throw new AdapterError("payments", "flutterwave", "provider_failure", "Flutterwave returned a malformed response.");
+  return data;
+}
+
+function majorAmount(value: unknown, currency: string | undefined): number | undefined {
+  if (!currency) return undefined;
+  const decimal = typeof value === "string" ? value : typeof value === "number" && Number.isFinite(value) ? String(value) : undefined;
+  return decimal ? decimalToMinor(decimal, currency) : undefined;
+}
+
+function metadata(value: unknown): { invoiceId?: string; contactId?: string } {
+  const record = object(value);
+  return {
+    invoiceId: text(record?.freeholder_invoice_id),
+    contactId: text(record?.freeholder_contact_id),
+  };
+}
+
+export function createFlutterwavePayments(options: FlutterwavePaymentOptions = {}): PaymentAdapter {
+  const current = env();
+  const secretKey = options.secretKey ?? current.FLUTTERWAVE_SECRET_KEY;
+  const webhookSecrets = options.webhookSecrets ?? [
+    current.FLUTTERWAVE_WEBHOOK_SECRET,
+    current.FLUTTERWAVE_WEBHOOK_SECRET_PREVIOUS,
+  ].filter((value): value is string => Boolean(value));
+  const apiBase = (options.apiBase ?? "https://api.flutterwave.com/v3").replace(/\/+$/, "");
+  const webhookUrl = options.webhookUrl ?? `${current.APP_URL.replace(/\/+$/, "")}/api/payments/webhooks/flutterwave`;
+  const fetcher = options.fetch ?? fetch;
+  const missing = [
+    !secretKey ? "FLUTTERWAVE_SECRET_KEY" : undefined,
+    webhookSecrets.length === 0 ? "FLUTTERWAVE_WEBHOOK_SECRET" : undefined,
+  ].filter(Boolean);
+
+  async function api(path: string, init: RequestInit): Promise<Record<string, unknown>> {
+    if (!secretKey) throw new AdapterError("payments", "flutterwave", "unavailable", "Flutterwave is not configured.");
+    const response = await paymentFetch(fetcher, `${apiBase}${path}`, {
+      ...init,
+      headers: { authorization: `Bearer ${secretKey}`, ...init.headers },
+    });
+    return providerJson("flutterwave", response);
+  }
+
+  async function verifiedTransaction(reference: string): Promise<Record<string, unknown>> {
+    return flutterwaveData(await api(`/transactions/verify_by_reference?tx_ref=${encodeURIComponent(reference)}`, { method: "GET" }));
+  }
+
+  function capture(data: Record<string, unknown>, fallback: string) {
+    const currency = text(data.currency)?.toUpperCase();
+    return {
+      providerRef: providerIdentifier(data.id) ?? fallback,
+      status: data.status === "successful" ? "succeeded" as const : data.status === "failed" ? "failed" as const : "pending" as const,
+      amountMinor: majorAmount(data.amount, currency),
+      currency,
+      occurredAt: providerTime("Flutterwave", data.created_at ?? data.createdAt),
+    };
+  }
+
+  return {
+    id: "flutterwave",
+    status: {
+      family: "payments",
+      id: "flutterwave",
+      available: missing.length === 0,
+      message: missing.length === 0
+        ? "Flutterwave Standard, API-verified settlement, refunds, and authenticated feedback are configured."
+        : `Flutterwave is missing ${missing.join(" and ")}.`,
+    },
+    capabilities: () => ({ ...capabilities }),
+    async supportedCurrencies() { return []; },
+    async supportedMethods(context) {
+      return [{
+        id: "flutterwave_checkout",
+        label: ["NG", "GH", "KE", "ZA", "UG", "TZ", "RW"].includes(context.country)
+          ? "Card, transfer, bank, or mobile money"
+          : "Flutterwave-supported checkout method",
+        kind: "other",
+        recurring: false,
+      }];
+    },
+    async createCheckout(invoice) {
+      const txRef = deterministicProviderRef("fh_", invoice.idempotencyKey, 64);
+      const data = flutterwaveData(await api("/payments", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          tx_ref: txRef,
+          amount: minorToDecimal(invoice.amountMinor, invoice.currency),
+          currency: invoice.currency,
+          redirect_url: invoice.successUrl,
+          customer: { email: invoice.customer.email, name: invoice.customer.name },
+          customizations: { title: invoice.description.slice(0, 100), description: invoice.description.slice(0, 255) },
+          meta: {
+            freeholder_invoice_id: invoice.invoiceId,
+            freeholder_contact_id: invoice.contactId,
+            cancel_url: invoice.cancelUrl,
+          },
+        }),
+      }));
+      const url = text(data.link);
+      if (!url) throw new AdapterError("payments", "flutterwave", "provider_failure", "Flutterwave did not return a checkout address.");
+      return { providerRef: txRef, url };
+    },
+    async captureCheckout(request) {
+      return capture(await verifiedTransaction(request.checkoutRef), request.checkoutRef);
+    },
+    async refund(request) {
+      const transactionId = request.providerRef;
+      if (!/^\d+$/.test(transactionId)) {
+        throw new AdapterError("payments", "flutterwave", "invalid_request", "Flutterwave refunds require a verified transaction identifier.");
+      }
+      const data = flutterwaveData(await api(`/transactions/${encodeURIComponent(transactionId)}/refund`, {
+        method: "POST",
+        headers: { "content-type": "application/json", "idempotency-key": request.idempotencyKey },
+        body: JSON.stringify({
+          amount: Number(minorToDecimal(request.amountMinor, request.currency)),
+          comments: request.reason?.slice(0, 255),
+          callbackurl: webhookUrl,
+        }),
+      }));
+      const providerRef = providerIdentifier(data.id) ?? text(data.flw_ref);
+      if (!providerRef) throw new AdapterError("payments", "flutterwave", "provider_failure", "Flutterwave did not return a refund reference.");
+      const status = text(data.status);
+      return {
+        providerRef,
+        // Plain `completed` means accepted and pending disbursement in the v3
+        // API. Only rail-specific completion or `succeeded` is final.
+        status: status === "succeeded" || status?.startsWith("completed-")
+          ? "succeeded"
+          : status === "failed"
+            ? "failed"
+            : "pending",
+      };
+    },
+    async revokeSavedMethod() { unsupportedSavedMethod("Flutterwave"); },
+    chargeSavedMethod: refuseOffSessionCharge("flutterwave"),
+    createRecurringSchedule: refuseRecurringSchedule("flutterwave"),
+    updateRecurringSchedule: refuseRecurringSchedule("flutterwave"),
+    cancelRecurringSchedule: refuseRecurringSchedule("flutterwave"),
+    async verifyWebhook(request) {
+      if (webhookSecrets.length === 0) throw new AdapterError("payments", "flutterwave", "unavailable", "Flutterwave webhook verification is not configured.");
+      verifyProviderHmac({
+        provider: "Flutterwave",
+        algorithm: "sha256",
+        secrets: webhookSecrets,
+        signed: request.body,
+        signature: request.headers["flutterwave-signature"],
+        encoding: "base64",
+      });
+      const payload = parseProviderJson("Flutterwave", request.body);
+      const type = text(payload.type) ?? text(payload.event);
+      const data = object(payload.data);
+      if (!type || !data) throw new AdapterError("payments", "flutterwave", "invalid_request", "Flutterwave sent a malformed event.");
+      const eventId = text(payload.id) ?? bodyEventId("flutterwave", request.body, type);
+
+      if (type === "charge.completed" || type === "charge.successful") {
+        const reference = text(data.tx_ref) ?? text(data.reference);
+        if (!reference) return [];
+        // Signature proves origin; the authenticated API re-fetch separately
+        // proves final status, amount, currency, and merchant reference.
+        const verified = await verifiedTransaction(reference);
+        const result = capture(verified, reference);
+        const common = {
+          id: eventId,
+          providerRef: result.providerRef,
+          checkoutRef: text(verified.tx_ref) ?? reference,
+          amountMinor: result.amountMinor,
+          currency: result.currency,
+          occurredAt: result.occurredAt,
+          ...metadata(verified.meta ?? data.meta),
+        };
+        if (result.status === "succeeded") return [{ ...common, kind: "payment_succeeded" }];
+        if (result.status === "failed") return [{ ...common, kind: "payment_failed" }];
+        return [{ ...common, kind: "payment_processing" }];
+      }
+
+      if (type.startsWith("refund.")) {
+        const providerRef = providerIdentifier(data.id) ?? text(data.refund_reference);
+        const paymentProviderRef = providerIdentifier(data.transaction_id ?? data.TransactionId ?? data.tx_id);
+        if (!providerRef || !paymentProviderRef) return [];
+        const currency = text(data.currency)?.toUpperCase();
+        const common = {
+          id: eventId,
+          providerRef,
+          paymentProviderRef,
+          amountMinor: majorAmount(data.amount_refunded ?? data.AmountRefunded ?? data.amount, currency),
+          currency,
+          occurredAt: providerTime("Flutterwave", data.updated_at ?? data.updatedAt ?? data.created_at ?? data.createdAt, request.receivedAt),
+        };
+        if (type === "refund.succeeded" || type === "refund.completed" || data.status === "succeeded" || text(data.status)?.startsWith("completed-")) return [{ ...common, kind: "refund_succeeded" }];
+        if (type === "refund.failed" || data.status === "failed") return [{ ...common, kind: "refund_failed" }];
+        return [{ ...common, kind: "refund_processing" }];
+      }
+      return [];
+    },
+  };
+}

package/dist/template/src/adapters/payments/http.ts

@@ -0,0 +1,82 @@
+// Copyright (C) 2026 Tony Aly
+// SPDX-License-Identifier: Apache-2.0
+// Bounded, credential-safe HTTP helpers shared by payment providers.
+
+import { AdapterError } from "../types";
+import { readBoundedBytes, RequestBodyError } from "@/core/http/body";
+
+const MAX_RESPONSE_BYTES = 1_048_576;
+
+export async function providerJson(
+  adapterId: string,
+  response: Response,
+): Promise<Record<string, unknown>> {
+  let body: string;
+  try {
+    body = new TextDecoder().decode(await readBoundedBytes(response, MAX_RESPONSE_BYTES));
+  } catch (error) {
+    if (error instanceof RequestBodyError) {
+      throw new AdapterError("payments", adapterId, "provider_failure", "The payment provider returned an oversized response.", true);
+    }
+    throw error;
+  }
+  let parsed: unknown;
+  try {
+    parsed = body ? JSON.parse(body) : {};
+  } catch {
+    throw new AdapterError("payments", adapterId, "provider_failure", "The payment provider returned an unreadable response.", response.status >= 500);
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new AdapterError("payments", adapterId, "provider_failure", "The payment provider returned an invalid response.", response.status >= 500);
+  }
+  if (!response.ok) {
+    const record = parsed as Record<string, unknown>;
+    const nested = record.error && typeof record.error === "object"
+      ? record.error as Record<string, unknown>
+      : undefined;
+    const candidate = nested?.code ?? nested?.type ?? record.name;
+    const code = (typeof candidate === "string" || typeof candidate === "number"
+      ? String(candidate)
+      : "provider_error").slice(0, 100);
+    const retryable = response.status === 429 || response.status >= 500;
+    throw new AdapterError(
+      "payments",
+      adapterId,
+      response.status === 401 || response.status === 403
+        ? "authentication"
+        : response.status === 429
+          ? "rate_limited"
+          : response.status >= 500
+            ? "provider_failure"
+            : "invalid_request",
+      `The payment provider refused the request (${code}).`,
+      retryable,
+    );
+  }
+  return parsed as Record<string, unknown>;
+}
+
+export function paymentFetch(fetcher: typeof fetch, input: string, init: RequestInit): Promise<Response> {
+  return fetcher(input, {
+    ...init,
+    redirect: init.redirect ?? "error",
+    signal: init.signal ?? AbortSignal.timeout(20_000),
+  }).catch((error: unknown) => {
+    if (error instanceof AdapterError) throw error;
+    throw new AdapterError("payments", "network", "provider_failure", "The payment provider could not be reached.", true);
+  });
+}
+
+export function object(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : undefined;
+}
+
+export function text(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+export function number(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isSafeInteger(value) ? value : undefined;
+}

package/dist/template/src/adapters/payments/index.ts

@@ -0,0 +1,42 @@
+// Copyright (C) 2026 Tony Aly
+// SPDX-License-Identifier: Apache-2.0
+
+import { AdapterRegistry } from "../registry";
+import config from "../../../freeholder.config";
+import { createManualPayments } from "./manual";
+import { createFlutterwavePayments } from "./flutterwave";
+import { createMolliePayments } from "./mollie";
+import { createNoPayments } from "./none";
+import { createPayPalPayments } from "./paypal";
+import { createPaystackPayments } from "./paystack";
+import { createRazorpayPayments } from "./razorpay";
+import { createSquarePayments } from "./square";
+import { createStripePayments } from "./stripe";
+import type { PaymentAdapter } from "./types";
+
+export * from "./types";
+export { createNoPayments } from "./none";
+export { createManualPayments } from "./manual";
+export { createFlutterwavePayments } from "./flutterwave";
+export { createMolliePayments } from "./mollie";
+export { createPayPalPayments } from "./paypal";
+export { createPaystackPayments } from "./paystack";
+export { createRazorpayPayments } from "./razorpay";
+export { createSquarePayments } from "./square";
+export { createStripePayments } from "./stripe";
+export * from "./providers";
+export const paymentAdapters = new AdapterRegistry<PaymentAdapter>("payments", [
+  createNoPayments(),
+  createManualPayments(),
+  createStripePayments(),
+  createPayPalPayments(),
+  createSquarePayments(),
+  createMolliePayments(),
+  createRazorpayPayments(),
+  createPaystackPayments(),
+  createFlutterwavePayments(),
+]);
+
+export function paymentAdapter(id: string = config.adapters.payments): PaymentAdapter {
+  return paymentAdapters.get(id);
+}

package/dist/template/src/adapters/payments/manual.ts

@@ -0,0 +1,59 @@
+// Copyright (C) 2026 Tony Aly
+// SPDX-License-Identifier: Apache-2.0
+// Owner-attested offline money. Settlement is recorded by the service layer.
+
+import { AdapterError } from "../types";
+import type { PaymentAdapter, PaymentAdapterCapabilities } from "./types";
+
+const capabilities: PaymentAdapterCapabilities = {
+  refunds: true,
+  partialRefunds: true,
+  savedMethods: false,
+  subscriptions: false,
+  offSessionCharges: false,
+  disputes: false,
+  payouts: false,
+  inPerson: true,
+  strongCustomerAuthentication: false,
+};
+
+const unsupported = () => Promise.reject(
+  new AdapterError(
+    "payments",
+    "manual",
+    "invalid_request",
+    "Offline payments are recorded by an authorized owner; they do not create a hosted checkout or webhook.",
+  ),
+);
+
+export function createManualPayments(): PaymentAdapter {
+  return {
+    id: "manual",
+    status: {
+      family: "payments",
+      id: "manual",
+      available: true,
+      message: "Cash, cheque, bank transfer, and externally processed payments can be recorded with owner evidence.",
+    },
+    capabilities: () => ({ ...capabilities }),
+    async supportedCurrencies() { return []; },
+    async supportedMethods() {
+      return [
+        { id: "cash", label: "Cash", kind: "cash" as const, recurring: false },
+        { id: "bank_transfer", label: "Bank transfer", kind: "bank_transfer" as const, recurring: false },
+        { id: "cheque", label: "Cheque", kind: "other" as const, recurring: false },
+        { id: "external_card", label: "Card processed elsewhere", kind: "card" as const, recurring: false },
+        { id: "other", label: "Other offline payment", kind: "other" as const, recurring: false },
+      ];
+    },
+    createCheckout: unsupported,
+    captureCheckout: unsupported,
+    refund: unsupported,
+    revokeSavedMethod: unsupported,
+    chargeSavedMethod: unsupported,
+    createRecurringSchedule: unsupported,
+    updateRecurringSchedule: unsupported,
+    cancelRecurringSchedule: unsupported,
+    verifyWebhook: unsupported,
+  };
+}

package/dist/template/src/adapters/payments/mollie.ts

@@ -0,0 +1,239 @@
+// Copyright (C) 2026 Tony Aly
+// SPDX-License-Identifier: Apache-2.0
+// Mollie hosted payments with API-authenticated classic webhook convergence.
+
+import { env } from "@/core/env";
+import { AdapterError } from "../types";
+import { decimalToMinor, minorToDecimal } from "./currency";
+import { object, paymentFetch, providerJson, text } from "./http";
+import {
+  parseProviderJson,
+  providerTime,
+  refuseOffSessionCharge,
+  refuseRecurringSchedule,
+  unsupportedSavedMethod,
+  verifyProviderHmac,
+} from "./provider-helpers";
+import type {
+  PaymentAdapter,
+  PaymentAdapterCapabilities,
+  PaymentMethodOffer,
+  PaymentProviderEvent,
+} from "./types";
+
+const capabilities: PaymentAdapterCapabilities = {
+  refunds: true,
+  partialRefunds: true,
+  savedMethods: false,
+  subscriptions: false,
+  offSessionCharges: false,
+  disputes: false,
+  payouts: false,
+  inPerson: false,
+  strongCustomerAuthentication: true,
+};
+
+export interface MolliePaymentOptions {
+  apiKey?: string;
+  webhookSecrets?: readonly string[];
+  apiBase?: string;
+  webhookUrl?: string;
+  fetch?: typeof fetch;
+}
+
+function amount(value: unknown): { amountMinor?: number; currency?: string } {
+  const money = object(value);
+  const currency = text(money?.currency)?.toUpperCase();
+  const decimal = text(money?.value);
+  return {
+    amountMinor: currency && decimal ? decimalToMinor(decimal, currency) : undefined,
+    currency,
+  };
+}
+
+function metadata(value: unknown): { invoiceId?: string; contactId?: string } {
+  let candidate = value;
+  if (typeof candidate === "string") {
+    try { candidate = JSON.parse(candidate); } catch { return {}; }
+  }
+  const record = object(candidate);
+  return {
+    invoiceId: text(record?.freeholder_invoice_id),
+    contactId: text(record?.freeholder_contact_id),
+  };
+}
+
+function eventTime(value: Record<string, unknown>): string {
+  return providerTime(
+    "Mollie",
+    value.paidAt ?? value.authorizedAt ?? value.failedAt ?? value.canceledAt
+      ?? value.expiredAt ?? value.updatedAt ?? value.createdAt,
+  );
+}
+
+function mollieEvents(payment: Record<string, unknown>): PaymentProviderEvent[] {
+  const providerRef = text(payment.id);
+  const status = text(payment.status);
+  if (!providerRef || !status) {
+    throw new AdapterError("payments", "mollie", "provider_failure", "Mollie returned a malformed payment during webhook verification.");
+  }
+  const occurredAt = eventTime(payment);
+  const common = {
+    id: `mollie:${providerRef}:payment:${status}:${occurredAt}`,
+    providerRef,
+    checkoutRef: providerRef,
+    ...amount(payment.amount),
+    occurredAt,
+    ...metadata(payment.metadata),
+  };
+  const events: PaymentProviderEvent[] = [];
+  if (status === "paid") events.push({ ...common, kind: "payment_succeeded" });
+  else if (status === "failed") events.push({ ...common, kind: "payment_failed" });
+  else if (status === "canceled" || status === "expired") events.push({ ...common, kind: "payment_cancelled" });
+  else if (status === "open" || status === "pending" || status === "authorized") events.push({ ...common, kind: "payment_processing" });
+
+  const embedded = object(payment._embedded);
+  const refunds = Array.isArray(embedded?.refunds) ? embedded.refunds.map(object).filter(Boolean) : [];
+  for (const refund of refunds) {
+    const refundRef = text(refund?.id);
+    const refundStatus = text(refund?.status);
+    if (!refundRef || !refundStatus) continue;
+    const refundAt = providerTime("Mollie", refund?.updatedAt ?? refund?.createdAt, occurredAt);
+    const refundCommon = {
+      id: `mollie:${refundRef}:refund:${refundStatus}:${refundAt}`,
+      providerRef: refundRef,
+      paymentProviderRef: providerRef,
+      ...amount(refund?.amount),
+      occurredAt: refundAt,
+    };
+    if (refundStatus === "refunded") events.push({ ...refundCommon, kind: "refund_succeeded" });
+    else if (refundStatus === "failed" || refundStatus === "canceled") events.push({ ...refundCommon, kind: "refund_failed" });
+    else events.push({ ...refundCommon, kind: "refund_processing" });
+  }
+  return events;
+}
+
+export function createMolliePayments(options: MolliePaymentOptions = {}): PaymentAdapter {
+  const current = env();
+  const apiKey = options.apiKey ?? current.MOLLIE_API_KEY;
+  const webhookSecrets = options.webhookSecrets ?? [
+    current.MOLLIE_WEBHOOK_SECRET,
+    current.MOLLIE_WEBHOOK_SECRET_PREVIOUS,
+  ].filter((value): value is string => Boolean(value));
+  const apiBase = (options.apiBase ?? "https://api.mollie.com").replace(/\/+$/, "");
+  const webhookUrl = options.webhookUrl ?? `${current.APP_URL.replace(/\/+$/, "")}/api/payments/webhooks/mollie`;
+  const fetcher = options.fetch ?? fetch;
+
+  async function api(path: string, init: RequestInit): Promise<Record<string, unknown>> {
+    if (!apiKey) throw new AdapterError("payments", "mollie", "unavailable", "Mollie is not configured.");
+    const response = await paymentFetch(fetcher, `${apiBase}${path}`, {
+      ...init,
+      headers: { authorization: `Bearer ${apiKey}`, ...init.headers },
+    });
+    return providerJson("mollie", response);
+  }
+
+  return {
+    id: "mollie",
+    status: {
+      family: "payments",
+      id: "mollie",
+      available: Boolean(apiKey),
+      message: apiKey
+        ? "Mollie checkout, refunds, and API-verified classic payment feedback are configured."
+        : "Mollie is missing MOLLIE_API_KEY.",
+    },
+    capabilities: () => ({ ...capabilities }),
+    async supportedCurrencies() { return []; },
+    async supportedMethods(context) {
+      const methods: PaymentMethodOffer[] = [{ id: "creditcard", label: "Card", kind: "card", recurring: false }];
+      if (context.currency === "EUR") {
+        methods.push({ id: "ideal", label: "iDEAL", kind: "bank_redirect", recurring: false });
+        methods.push({ id: "bancontact", label: "Bancontact", kind: "bank_redirect", recurring: false });
+      }
+      return methods;
+    },
+    async createCheckout(invoice) {
+      const value = await api("/v2/payments", {
+        method: "POST",
+        headers: { "content-type": "application/json", "idempotency-key": invoice.idempotencyKey },
+        body: JSON.stringify({
+          amount: { currency: invoice.currency, value: minorToDecimal(invoice.amountMinor, invoice.currency) },
+          description: invoice.description.slice(0, 255),
+          redirectUrl: invoice.successUrl,
+          cancelUrl: invoice.cancelUrl,
+          webhookUrl,
+          metadata: {
+            freeholder_invoice_id: invoice.invoiceId,
+            freeholder_contact_id: invoice.contactId,
+          },
+          ...(invoice.methodIds?.length === 1 ? { method: invoice.methodIds[0] } : {}),
+        }),
+      });
+      const providerRef = text(value.id);
+      const url = text(object(object(value._links)?.checkout)?.href);
+      if (!providerRef || !url) throw new AdapterError("payments", "mollie", "provider_failure", "Mollie did not return a checkout address.");
+      return { providerRef, url };
+    },
+    async captureCheckout(request) {
+      const payment = await api(`/v2/payments/${encodeURIComponent(request.checkoutRef)}`, { method: "GET" });
+      const status = text(payment.status);
+      return {
+        providerRef: text(payment.id) ?? request.checkoutRef,
+        status: status === "paid" ? "succeeded" : status === "failed" || status === "canceled" || status === "expired" ? "failed" : "pending",
+        ...amount(payment.amount),
+        occurredAt: eventTime(payment),
+      };
+    },
+    async refund(request) {
+      const value = await api(`/v2/payments/${encodeURIComponent(request.providerRef)}/refunds`, {
+        method: "POST",
+        headers: { "content-type": "application/json", "idempotency-key": request.idempotencyKey },
+        body: JSON.stringify({
+          amount: { currency: request.currency, value: minorToDecimal(request.amountMinor, request.currency) },
+          ...(request.reason ? { description: request.reason.slice(0, 255) } : {}),
+        }),
+      });
+      const providerRef = text(value.id);
+      if (!providerRef) throw new AdapterError("payments", "mollie", "provider_failure", "Mollie did not return a refund reference.");
+      return {
+        providerRef,
+        status: value.status === "refunded" ? "succeeded" : value.status === "failed" || value.status === "canceled" ? "failed" : "pending",
+      };
+    },
+    async revokeSavedMethod() { unsupportedSavedMethod("Mollie"); },
+    chargeSavedMethod: refuseOffSessionCharge("mollie"),
+    createRecurringSchedule: refuseRecurringSchedule("mollie"),
+    updateRecurringSchedule: refuseRecurringSchedule("mollie"),
+    cancelRecurringSchedule: refuseRecurringSchedule("mollie"),
+    async verifyWebhook(request) {
+      const signature = request.headers["x-mollie-signature"];
+      let paymentId: string | undefined;
+      if (signature) {
+        if (webhookSecrets.length === 0) throw new AdapterError("payments", "mollie", "unavailable", "Mollie next-generation webhook verification is not configured.");
+        verifyProviderHmac({
+          provider: "Mollie",
+          algorithm: "sha256",
+          secrets: webhookSecrets,
+          signed: request.body,
+          signature,
+          encoding: "hex",
+          prefix: "sha256=",
+        });
+        const payload = parseProviderJson("Mollie", request.body);
+        const entity = object(payload.entity) ?? object(payload.data);
+        paymentId = text(entity?.id) ?? text(payload.entityId) ?? text(payload.entity_id);
+        if (!paymentId && text(payload.resource) === "payment") paymentId = text(payload.id);
+      } else {
+        const form = new URLSearchParams(Buffer.from(request.body).toString("utf8"));
+        paymentId = form.get("id") ?? undefined;
+      }
+      if (!paymentId || paymentId.length > 64 || !/^tr_[A-Za-z0-9]+$/.test(paymentId)) {
+        throw new AdapterError("payments", "mollie", "invalid_request", "Mollie feedback did not identify a payment.");
+      }
+      // Classic callbacks deliberately carry no signature or status. Fetching
+      // with the private API credential is the authenticity check Mollie requires.
+      return mollieEvents(await api(`/v2/payments/${encodeURIComponent(paymentId)}?embed=refunds`, { method: "GET" }));
+    },
+  };
+}