@paytree/medusa-payment-paytree 0.1.0

package/dist/modules/paytree-payment/service.js

@@ -0,0 +1,369 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PaytreePaymentProviderService = void 0;
+const utils_1 = require("@medusajs/framework/utils");
+const client_1 = require("./lib/client");
+const settings_reader_1 = require("./lib/settings-reader");
+const audit_1 = require("./lib/audit");
+const logger_1 = require("./lib/logger");
+const amount_1 = require("./lib/amount");
+const status_map_1 = require("./lib/status-map");
+const constants_1 = require("./lib/constants");
+class PaytreePaymentProviderService extends utils_1.AbstractPaymentProvider {
+    static validateOptions(options) {
+        if (!options.apiKey) {
+            throw new utils_1.MedusaError(utils_1.MedusaError.Types.INVALID_DATA, "Paytree provider requires an `apiKey` (set PAYTREE_API_KEY).");
+        }
+        if (!options.backendUrl) {
+            throw new utils_1.MedusaError(utils_1.MedusaError.Types.INVALID_DATA, "Paytree provider requires a `backendUrl` to build the callback URL.");
+        }
+    }
+    constructor(container, options) {
+        super(container, options);
+        this.container_ = container;
+        this.options_ = options;
+        this.logger_ = new logger_1.PaytreeLogger(container);
+        this.settings_ = new settings_reader_1.SettingsReader(container, options);
+        this.audit_ = new audit_1.AuditWriter(container);
+    }
+    /** Build a client using the current effective settings (live base URL + toggles). */
+    async client() {
+        const settings = await this.settings_.get();
+        return new client_1.PaytreeClient({
+            apiKey: this.options_.apiKey,
+            baseUrl: settings.baseUrl,
+            logRequest: settings.logRequest,
+            logResponse: settings.logResponse,
+        }, this.logger_);
+    }
+    /** Notification URL Paytree will call back, with its substitution tags. */
+    notificationUrl() {
+        const base = this.options_.backendUrl.replace(/\/+$/, "");
+        return (`${base}/hooks/paytree` +
+            `?payment_intent_id={payment_intent_id}&transaction_id={transaction_id}`);
+    }
+    // ---------------------------------------------------------------------------
+    // initiate
+    // ---------------------------------------------------------------------------
+    async initiatePayment(input) {
+        const data = (input.data ?? {});
+        const context = input.context ?? {};
+        // Our stable correlation key = the Medusa payment session id when present.
+        const transactionRef = data.session_id ||
+            context.idempotency_key ||
+            `paytree_${Date.now()}`;
+        const c = { sessionId: transactionRef };
+        const customer = data.customer ?? {};
+        const email = customer.email || context?.customer?.email;
+        const firstName = customer.first_name || context?.customer?.first_name;
+        const lastName = customer.last_name || context?.customer?.last_name;
+        const country = data.address?.country;
+        const missing = [];
+        if (!email)
+            missing.push("customer.email");
+        if (!firstName)
+            missing.push("customer.first_name");
+        if (!lastName)
+            missing.push("customer.last_name");
+        if (!country)
+            missing.push("address.country");
+        if (!data.session?.ip_address)
+            missing.push("session.ip_address");
+        if (!data.session?.user_agent)
+            missing.push("session.user_agent");
+        if (missing.length) {
+            throw new utils_1.MedusaError(utils_1.MedusaError.Types.INVALID_DATA, `Paytree requires the storefront to pass these fields in the payment ` +
+                `session data: ${missing.join(", ")}. See the integration README.`);
+        }
+        const amount = (0, amount_1.toPaytreeAmount)(input.amount);
+        const currency = (input.currency_code || "").toUpperCase();
+        // Paytree rejects blank strings with a 400, so optional fields are only
+        // included when they actually have a value. Country is always required.
+        const clean = (v) => {
+            const s = typeof v === "string" ? v.trim() : "";
+            return s.length ? s : undefined;
+        };
+        const customerPayload = {
+            first_name: firstName,
+            last_name: lastName,
+            email: email,
+        };
+        const phone = clean(customer.phone);
+        if (phone) {
+            customerPayload.phone = phone;
+        }
+        const addressPayload = {
+            country: country,
+        };
+        for (const key of ["street", "city", "state", "zip"]) {
+            const value = clean(data.address?.[key]);
+            if (value) {
+                addressPayload[key] = value;
+            }
+        }
+        const body = {
+            transaction_ref: transactionRef,
+            client_ref: context?.customer?.id || email,
+            amount,
+            amount_currency: currency,
+            method: data.method || this.options_.defaultMethod || "card",
+            customer: customerPayload,
+            address: addressPayload,
+            session: {
+                ip_address: data.session.ip_address,
+                user_agent: data.session.user_agent,
+            },
+            callback: {
+                notification_url: this.notificationUrl(),
+                return_url: data.return_url || `${this.options_.backendUrl}`,
+                cancel_url: clean(data.cancel_url),
+            },
+            metadata: { medusa_session_id: transactionRef },
+            order_items: data.order_items,
+        };
+        this.logger_.info(`initiating payment for ${amount} ${currency}`, c);
+        try {
+            const cl = await this.client();
+            const res = await cl.createPaymentIntent(body, c);
+            const sessionData = {
+                ...data,
+                transaction_ref: transactionRef,
+                paytree_id: String(res.id),
+                payment_link: res.payment_link,
+                status: constants_1.PaytreeStatus.PENDING,
+            };
+            await this.audit_.write({
+                event: constants_1.AuditEvent.INITIATE,
+                session_id: transactionRef,
+                paytree_id: String(res.id),
+                status: constants_1.PaytreeStatus.PENDING,
+                amount,
+                currency,
+                detail: { payment_link: res.payment_link },
+            });
+            return {
+                id: transactionRef,
+                data: sessionData,
+                status: utils_1.PaymentSessionStatus.PENDING,
+            };
+        }
+        catch (e) {
+            this.logger_.error("initiatePayment failed", e, c);
+            await this.audit_.write({
+                event: constants_1.AuditEvent.ERROR,
+                session_id: transactionRef,
+                error: e instanceof Error ? e.message : String(e),
+                detail: {
+                    phase: constants_1.AuditEvent.INITIATE,
+                    http_status: e?.paytreeStatus ?? null,
+                    request: body,
+                    response: e?.paytreeResponse ?? null,
+                },
+            });
+            throw e;
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // status reads
+    // ---------------------------------------------------------------------------
+    /** Read the live intent from Paytree by transaction_ref. */
+    async readIntent(data, c) {
+        const ref = data.transaction_ref || data.session_id;
+        if (!ref) {
+            return null;
+        }
+        const cl = await this.client();
+        return cl.findByTransactionRef(ref, c);
+    }
+    /** Roll up the latest status across the intent's payment objects. */
+    latestStatus(intent) {
+        const payments = intent?.payment ?? [];
+        if (!payments.length) {
+            return constants_1.PaytreeStatus.PENDING;
+        }
+        // Prefer a terminal status if any payment reached it.
+        const statuses = payments.map((p) => p.status);
+        for (const s of [
+            constants_1.PaytreeStatus.REFUNDED,
+            constants_1.PaytreeStatus.PARTIAL_REFUNDED,
+            constants_1.PaytreeStatus.SUCCESS,
+            constants_1.PaytreeStatus.AUTHORIZED,
+            constants_1.PaytreeStatus.FAILED,
+            constants_1.PaytreeStatus.CANCELED,
+            constants_1.PaytreeStatus.EXPIRED,
+        ]) {
+            if (statuses.includes(s)) {
+                return s;
+            }
+        }
+        return statuses[0];
+    }
+    async getPaymentStatus(input) {
+        const data = (input.data ?? {});
+        const c = {
+            sessionId: data.transaction_ref,
+            paytreeId: data.paytree_id,
+        };
+        try {
+            const intent = await this.readIntent(data, c);
+            const status = this.latestStatus(intent);
+            await this.audit_.write({
+                event: constants_1.AuditEvent.STATUS_READ,
+                session_id: data.transaction_ref,
+                paytree_id: data.paytree_id,
+                status,
+            });
+            return {
+                status: (0, status_map_1.toSessionStatus)(status),
+                data: { ...data, status },
+            };
+        }
+        catch (e) {
+            this.logger_.error("getPaymentStatus failed", e, c);
+            // Surfacing PENDING keeps the session recoverable; the callback or a
+            // later read can resolve it.
+            return { status: utils_1.PaymentSessionStatus.PENDING, data: input.data };
+        }
+    }
+    async retrievePayment(input) {
+        const data = (input.data ?? {});
+        const c = {
+            sessionId: data.transaction_ref,
+            paytreeId: data.paytree_id,
+        };
+        const intent = await this.readIntent(data, c);
+        return {
+            data: {
+                ...data,
+                status: this.latestStatus(intent),
+                intent,
+            },
+        };
+    }
+    // ---------------------------------------------------------------------------
+    // authorize / capture (auto-capture model)
+    // ---------------------------------------------------------------------------
+    async authorizePayment(input) {
+        const data = (input.data ?? {});
+        const c = {
+            sessionId: data.transaction_ref,
+            paytreeId: data.paytree_id,
+        };
+        const intent = await this.readIntent(data, c);
+        const status = this.latestStatus(intent);
+        await this.audit_.write({
+            event: constants_1.AuditEvent.AUTHORIZE,
+            session_id: data.transaction_ref,
+            paytree_id: data.paytree_id,
+            status,
+        });
+        return {
+            status: (0, status_map_1.toSessionStatus)(status),
+            data: { ...data, status },
+        };
+    }
+    async capturePayment(input) {
+        // Paytree auto-captures on the hosted page, so there is no capture call to
+        // make. We read the live status and confirm it reached success.
+        const data = (input.data ?? {});
+        const c = {
+            sessionId: data.transaction_ref,
+            paytreeId: data.paytree_id,
+        };
+        const intent = await this.readIntent(data, c);
+        const status = this.latestStatus(intent);
+        await this.audit_.write({
+            event: constants_1.AuditEvent.CAPTURE,
+            session_id: data.transaction_ref,
+            paytree_id: data.paytree_id,
+            status,
+        });
+        return {
+            data: { ...data, status },
+        };
+    }
+    // ---------------------------------------------------------------------------
+    // cancel / delete / update
+    // ---------------------------------------------------------------------------
+    async cancelPayment(input) {
+        // Paytree has no server-side void; the hosted page's cancel_url handles a
+        // shopper abandoning, and an unpaid intent simply expires. Local state only.
+        const data = (input.data ?? {});
+        await this.audit_.write({
+            event: constants_1.AuditEvent.CANCEL,
+            session_id: data.transaction_ref,
+            paytree_id: data.paytree_id,
+        });
+        return { data: input.data };
+    }
+    async deletePayment(input) {
+        return { data: input.data };
+    }
+    async updatePayment(input) {
+        // A Paytree transaction_ref cannot be reused, so an amount change can't
+        // mutate an existing intent. Medusa creates a fresh session (and thus a
+        // fresh initiatePayment) for changes, so we just echo the data here.
+        return { data: input.data };
+    }
+    // ---------------------------------------------------------------------------
+    // refund (verify-then-record; refunds are initiated in the Paytree back office)
+    // ---------------------------------------------------------------------------
+    async refundPayment(input) {
+        const data = (input.data ?? {});
+        const c = {
+            sessionId: data.transaction_ref,
+            paytreeId: data.paytree_id,
+        };
+        // Paytree does not expose an API to CREATE a refund; refunds are performed
+        // in the Paytree back office and reflected to us via the callback. So this
+        // method verifies a matching refund actually exists in Paytree before
+        // letting Medusa record it. This both (a) lets the callback path record
+        // refunds and (b) prevents the admin "Refund" button from creating a
+        // phantom refund that never moved money.
+        const intent = await this.readIntent(data, c);
+        const payment = intent?.payment?.[0];
+        const refundedTotal = payment?.refunded ?? "0";
+        const requested = new utils_1.BigNumber(input.amount);
+        const refundedBN = (0, amount_1.fromPaytreeAmount)(refundedTotal);
+        const enough = refundedBN.numeric >= requested.numeric || refundedBN.numeric > 0;
+        if (!enough) {
+            await this.audit_.write({
+                event: constants_1.AuditEvent.ERROR,
+                session_id: data.transaction_ref,
+                paytree_id: data.paytree_id,
+                error: "refund not present in Paytree",
+                detail: { phase: constants_1.AuditEvent.REFUND, refundedTotal },
+            });
+            throw new utils_1.MedusaError(utils_1.MedusaError.Types.NOT_ALLOWED, "Refunds must be initiated in the Paytree back office. Once the " +
+                "refund is processed there, it is reflected here automatically.");
+        }
+        await this.audit_.write({
+            event: constants_1.AuditEvent.REFUND,
+            session_id: data.transaction_ref,
+            paytree_id: data.paytree_id,
+            status: constants_1.PaytreeStatus.REFUNDED,
+            amount: (0, amount_1.toPaytreeAmount)(input.amount),
+            detail: { refundedTotal },
+        });
+        return {
+            data: {
+                ...data,
+                refunded: refundedTotal,
+            },
+        };
+    }
+    // ---------------------------------------------------------------------------
+    // webhook (defensive only; the live path is the custom GET route)
+    // ---------------------------------------------------------------------------
+    async getWebhookActionAndData(payload) {
+        // Paytree sends a GET callback with no signed body, handled by the custom
+        // route at /hooks/paytree. The built-in POST webhook route is not used, so
+        // this returns NOT_SUPPORTED defensively if it is ever invoked.
+        this.logger_.warn("getWebhookActionAndData was called, but Paytree callbacks are handled " +
+            "by the custom /hooks/paytree route");
+        return { action: utils_1.PaymentActions.NOT_SUPPORTED };
+    }
+}
+exports.PaytreePaymentProviderService = PaytreePaymentProviderService;
+PaytreePaymentProviderService.identifier = constants_1.PAYTREE_PROVIDER_IDENTIFIER;
+exports.default = PaytreePaymentProviderService;

package/docs/api-reference.md

@@ -0,0 +1,121 @@
+# API reference
+
+Routes contributed by the plugin.
+
+## Store
+
+### `GET /store/paytree/methods`
+
+Public list of the Paytree methods the admin has enabled, with their (possibly
+overridden) display labels. Used by the storefront method picker. Never returns
+disabled methods or any secret/operational config.
+
+**Response**
+
+```json
+{
+  "methods": [
+    { "method": "card", "label": "Credit / debit card" },
+    { "method": "paypal", "label": "PayPal" }
+  ]
+}
+```
+
+## Callback
+
+### `GET /hooks/paytree`
+
+Called by Paytree when a payment status changes. The notification URL is built
+from `backendUrl` with substitution tags:
+
+```
+{BACKEND_URL}/hooks/paytree?payment_intent_id={payment_intent_id}&transaction_id={transaction_id}
+```
+
+**Query parameters**
+
+| Param               | Description |
+| ------------------- | ----------- |
+| `payment_intent_id` | Paytree intent id (tag substituted by Paytree). |
+| `transaction_id`    | Our `transaction_ref` = the Medusa payment session id. |
+
+The body is **not trusted**; the handler re-fetches the authoritative status
+from Paytree. Responses:
+
+- `200` — event handled (also returned when there is nothing to correlate, to
+  stop retries).
+- `500` — internal failure; signals Paytree to retry.
+
+## Admin
+
+All admin routes require an authenticated admin session.
+
+### `GET /admin/paytree/settings`
+
+```json
+{
+  "settings": {
+    "base_url": "https://api.paytree.tech",
+    "log_request": false,
+    "log_response": false,
+    "methods": [{ "method": "card", "enabled": true, "label": "Credit / debit card" }]
+  },
+  "api_key_configured": true
+}
+```
+
+The API key value is never returned — only whether it is configured.
+
+### `POST /admin/paytree/settings`
+
+**Body**
+
+```json
+{
+  "base_url": "https://api.paytree.tech",
+  "log_request": false,
+  "log_response": false,
+  "methods": [{ "method": "card", "enabled": true, "label": "Card" }]
+}
+```
+
+Validation: `base_url` must be a valid `https` URL. Unknown methods and blank
+label overrides are dropped. Returns the resolved settings.
+
+### `GET /admin/paytree/events`
+
+Audit-log query for the admin Payments page.
+
+**Query parameters**
+
+| Param         | Description |
+| ------------- | ----------- |
+| `session_id`  | Filter by Medusa payment session id. |
+| `paytree_id`  | Filter by Paytree intent id. |
+| `event`       | Filter by event type (e.g. `initiate_payment`). |
+| `limit`       | Page size (max 200, default 50). |
+| `offset`      | Pagination offset. |
+
+**Event types**: `initiate_payment`, `authorize_payment`, `capture_payment`,
+`refund_payment`, `cancel_payment`, `get_payment_status`, `webhook_received`,
+`webhook_processed`, `error`.
+
+## Payment session data (storefront → provider)
+
+`initiatePayment` requires these fields in the session `data` (assembled by the
+storefront). Missing required fields cause a clear `INVALID_DATA` error.
+
+| Field                 | Required | Notes |
+| --------------------- | -------- | ----- |
+| `customer.email`      | yes      | |
+| `customer.first_name` | yes      | |
+| `customer.last_name`  | yes      | |
+| `customer.phone`      | no       | Omitted if blank (Paytree rejects blanks). |
+| `address.country`     | yes      | ISO 3166-1 alpha-2. |
+| `address.street/city/state/zip` | no | Included only when non-empty. |
+| `session.ip_address`  | yes      | End-customer IP (fraud screening). |
+| `session.user_agent`  | yes      | End-customer UA. |
+| `method`              | no       | One of the supported methods; defaults to `defaultMethod`. |
+| `return_url`          | no       | Where Paytree redirects after payment. |
+| `cancel_url`          | no       | Where Paytree redirects on cancel. |
+| `order_items`         | no       | Line items forwarded to Paytree. |

package/docs/architecture.md

@@ -0,0 +1,97 @@
+# Architecture
+
+The package is modeled on `@medusajs/payment-stripe`: a plain TypeScript package
+compiled with `tsc` to `dist/` (CommonJS + `.d.ts`). It ships two Medusa modules
+compiled, plus copy-in API routes and admin extensions.
+
+```
+src/                              # COMPILED to dist/ (shipped on npm)
+├── index.ts                      #   default export = ModuleProvider(PAYMENT)
+└── modules/
+    ├── paytree/                  #   "data" module: settings + audit-log tables
+    │   ├── models/               #     paytree_setting, paytree_event_log
+    │   ├── migrations/           #     table creation + methods column
+    │   └── service.ts            #     getSettings / upsertSettings / log queries
+    └── paytree-payment/          #   payment PROVIDER (AbstractPaymentProvider)
+        ├── service.ts            #     initiate/authorize/capture/refund/status…
+        └── lib/                  #     client, amount, status-map, audit, logger…
+
+integration/                      # COPY-IN source (shipped, not compiled)
+├── api/
+│   ├── hooks/paytree/route.ts    #   GET callback from Paytree (the live path)
+│   ├── store/paytree/methods/    #   GET enabled methods for the storefront
+│   └── admin/paytree/            #   GET/POST settings, GET audit events
+└── admin/routes/paytree/         #   admin dashboard pages (Payments, Settings)
+
+storefront/                       # COPY-IN Next.js checkout components
+```
+
+The API routes and admin pages import shared helpers from the installed package
+(`@paytree/medusa-payment-paytree`) rather than relative paths, so they work
+unchanged once copied into your backend's `src/`.
+
+## Why two modules?
+
+Medusa runs payment providers inside the Payment module's **isolated
+container**, which means the provider cannot resolve another module's service.
+But the admin needs editable settings and an audit trail.
+
+- The **`paytree` data module** owns the schema (`paytree_setting`,
+  `paytree_event_log`) and is resolvable from app-level API routes, subscribers,
+  and the admin.
+- The **`paytree-payment` provider** cannot resolve that service, so it reads the
+  settings table and writes the audit table **directly** through the Postgres
+  connection registered in the container (`SettingsReader`, `AuditWriter`).
+  Module isolation restricts service resolution, not physical DB access.
+
+## Payment lifecycle mapping
+
+| Medusa call            | What the provider does |
+| ---------------------- | ---------------------- |
+| `initiatePayment`      | Validates required fields, creates a Paytree payment intent, stores `payment_link` + ids in session data. |
+| `getPaymentStatus`     | Looks up the intent by `transaction_ref`, rolls up the latest status, maps to a `PaymentSessionStatus`. |
+| `authorizePayment`     | Reads live status (auto-capture model). |
+| `capturePayment`       | No-op call to Paytree (captured on hosted page); confirms status. |
+| `refundPayment`        | Verifies a matching refund exists in Paytree, then records it. Never creates a refund. |
+| `cancelPayment`        | Local state only; unpaid intents expire on Paytree's side. |
+| `updatePayment`        | Echoes data — a `transaction_ref` can't be reused, so Medusa creates a fresh session for changes. |
+| `getWebhookActionAndData` | Returns `NOT_SUPPORTED`; the live path is the custom GET callback. |
+
+### Status mapping
+
+Paytree status → Medusa `PaymentSessionStatus` (`lib/status-map.ts`):
+
+- `pending`, `partial` → `PENDING`
+- `authorized` → `AUTHORIZED`
+- `success` → `CAPTURED` (auto-capture)
+- `failed` → `ERROR`
+- `canceled`, `expired` → `CANCELED`
+- `refunded`, `partial_refunded`, disputes → `CAPTURED` (tracked separately)
+
+## The callback (`/hooks/paytree`)
+
+Paytree sends a **GET** ping with `payment_intent_id` and `transaction_id` query
+tags — no signed body. The handler:
+
+1. Records a `webhook_received` audit event.
+2. Ignores the callback body entirely and re-fetches the **authoritative** status
+   from Paytree using the secret API key (this lookup is the trust mechanism).
+3. Routes the outcome:
+   - `success`/`authorized`/`failed` → `processPaymentWorkflow`.
+   - `refunded`/`partial_refunded` → `refundPaymentWorkflow` (Medusa has no
+     "refunded" webhook action).
+4. Returns `200` on success (idempotent; safe to retry) or `500` to trigger
+   Paytree's retry schedule on genuine internal failure.
+
+## Amounts
+
+Medusa v2 uses **major units** as `BigNumber`. Paytree accepts a 2-decimal
+string. `lib/amount.ts` converts between them; 3-decimal currencies are rounded
+to 2 places to match Paytree's API constraint.
+
+## Observability
+
+Every meaningful event is written to `paytree_event_log` via `AuditWriter`,
+always after redaction. The `PaytreeLogger` tags every line with the session and
+intent ids so a payment can be traced end-to-end by grepping one id. Request and
+response body logging is opt-in per the admin toggles and always redacted.

package/docs/configuration.md

@@ -0,0 +1,62 @@
+# Configuration
+
+## Environment variables
+
+| Variable           | Required | Purpose                                                                 |
+| ------------------ | -------- | ----------------------------------------------------------------------- |
+| `PAYTREE_API_KEY`  | yes      | Paytree API key. Sent as `Authorization: Token <key>`. Read from env only. |
+| `BACKEND_URL`      | yes      | Public URL of this backend; used to build the `/hooks/paytree` callback URL. |
+| `PAYTREE_BASE_URL` | no       | Paytree API origin. Defaults to `https://api.paytree.tech`; overridable in the admin. |
+
+## Provider options
+
+Passed under the payment provider entry in `medusa-config.js`:
+
+| Option          | Type     | Required | Default                  | Notes |
+| --------------- | -------- | -------- | ------------------------ | ----- |
+| `apiKey`        | string   | yes      | —                        | Validated at boot; throws if missing. |
+| `backendUrl`    | string   | yes      | —                        | Validated at boot; throws if missing. |
+| `baseUrl`       | string   | no       | `https://api.paytree.tech` | Only used as a fallback; the admin setting wins at runtime. |
+| `defaultMethod` | string   | no       | `card`                   | Requested when the storefront doesn't pass a `method`. |
+
+### Settings precedence for the base URL
+
+At runtime the effective base URL is resolved in this order:
+
+1. The `paytree_setting.base_url` row (editable in the admin UI).
+2. The `baseUrl` provider option.
+3. The built-in default `https://api.paytree.tech`.
+
+Settings are cached in the provider for a short TTL (15s) so admin changes take
+effect without a restart, without hitting the DB on every call.
+
+## Admin settings (`Paytree → Settings`)
+
+| Setting                | Stored in DB | Description |
+| ---------------------- | ------------ | ----------- |
+| Paytree API endpoint   | yes          | Must be a valid `https` URL. |
+| Payment methods        | yes          | Per-method `enabled` + optional `label`. Only enabled methods show at checkout. |
+| Log outgoing requests  | yes          | Logs request bodies (always redacted). |
+| Log responses          | yes          | Logs response bodies (always redacted). |
+
+The API key status ("configured" / "missing") is shown but the value is never
+returned or editable here — it lives only in `PAYTREE_API_KEY`.
+
+## Supported payment methods
+
+`card`, `paypal`, `klarna`, `ideal`, `bancontact`, `crypto`, `wire`
+(bank transfer), `trustly`, `kakaopay`, `p24` (Przelewy24), `blik`.
+
+The canonical list and default labels live in
+`src/modules/paytree-payment/lib/methods.ts`. Only `enabled` and `label` are
+persisted per method; adding a method to the canonical list automatically
+surfaces it in the admin UI.
+
+## Security notes
+
+- The API key is never persisted or logged; the `Authorization` header is masked
+  in all logs.
+- The admin base-URL update rejects non-`https` URLs so the key is never sent in
+  cleartext.
+- The audit log redacts credential-like fields (`token`, `secret`, `password`,
+  `api_key`, `authorization`) at any depth before writing.