@paytree/medusa-payment-paytree 0.1.0

package/dist/modules/paytree-payment/lib/methods.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PAYTREE_METHOD_DEFS = void 0;
+exports.resolveMethods = resolveMethods;
+exports.normalizeMethods = normalizeMethods;
+/**
+ * Canonical list of payment methods Paytree supports, with their default
+ * display labels. The admin can, per method:
+ *   - toggle whether it is offered at checkout (`enabled`)
+ *   - override the label shown to the customer (`label`)
+ *
+ * The set of methods is fixed by Paytree; only `enabled` and `label` are
+ * stored in the DB. Resolving merges the stored config over these defaults so
+ * that adding a method here automatically surfaces it in the admin UI.
+ */
+exports.PAYTREE_METHOD_DEFS = [
+    { method: "card", label: "Credit / debit card" },
+    { method: "paypal", label: "PayPal" },
+    { method: "klarna", label: "Klarna" },
+    { method: "ideal", label: "iDEAL" },
+    { method: "bancontact", label: "Bancontact" },
+    { method: "crypto", label: "Crypto" },
+    { method: "wire", label: "Bank transfer" },
+    { method: "trustly", label: "Trustly" },
+    { method: "kakaopay", label: "KakaoPay" },
+    { method: "p24", label: "Przelewy24" },
+    { method: "blik", label: "BLIK" },
+];
+const VALID_METHODS = new Set(exports.PAYTREE_METHOD_DEFS.map((m) => m.method));
+/**
+ * Merge stored per-method config over the canonical defaults. Unknown stored
+ * methods are ignored; missing ones fall back to disabled with the default
+ * label. `card` is enabled by default so a fresh install has one working
+ * method until the admin curates the list.
+ */
+function resolveMethods(stored) {
+    const byMethod = new Map((stored ?? [])
+        .filter((m) => m && VALID_METHODS.has(m.method))
+        .map((m) => [m.method, m]));
+    return exports.PAYTREE_METHOD_DEFS.map((def) => {
+        const s = byMethod.get(def.method);
+        const label = s?.label?.trim();
+        return {
+            method: def.method,
+            enabled: s ? Boolean(s.enabled) : def.method === "card",
+            label: label && label.length > 0 ? label : def.label,
+        };
+    });
+}
+/**
+ * Normalize an incoming admin payload into the minimal stored shape, dropping
+ * unknown methods and blank label overrides.
+ */
+function normalizeMethods(input) {
+    if (!Array.isArray(input)) {
+        return [];
+    }
+    return input
+        .filter((m) => m && VALID_METHODS.has(m.method))
+        .map((m) => {
+        const label = typeof m.label === "string" ? m.label.trim() : "";
+        return {
+            method: m.method,
+            enabled: Boolean(m.enabled),
+            ...(label ? { label } : {}),
+        };
+    });
+}

package/dist/modules/paytree-payment/lib/redact.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Redaction utilities.
+ *
+ * Request/response logging is opt-in via the admin toggles. When on, we log the
+ * full payload so it is actually useful for debugging — the only thing masked
+ * is the API key (and equivalent credentials), which lives in the Authorization
+ * header. Customer details and addresses are shown as-is.
+ */
+/**
+ * Deep-clone a value with credential fields masked. Safe to pass any JSON-ish
+ * object, including arrays and nested structures. Non-object values are
+ * returned as-is.
+ */
+export declare function redact(input: unknown): unknown;
+/** Mask the API key in the Authorization header for safe logging. */
+export declare function redactHeaders(headers: Record<string, string>): Record<string, string>;

package/dist/modules/paytree-payment/lib/redact.js

@@ -0,0 +1,60 @@
+"use strict";
+/**
+ * Redaction utilities.
+ *
+ * Request/response logging is opt-in via the admin toggles. When on, we log the
+ * full payload so it is actually useful for debugging — the only thing masked
+ * is the API key (and equivalent credentials), which lives in the Authorization
+ * header. Customer details and addresses are shown as-is.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.redact = redact;
+exports.redactHeaders = redactHeaders;
+const MASK = "[redacted]";
+/**
+ * Credential keys masked wherever they appear, at any depth. Deliberately
+ * limited to secrets — not PII — so logs stay debuggable. The API key normally
+ * only appears in the Authorization header (see redactHeaders).
+ */
+const FULLY_MASKED_KEYS = new Set([
+    "authorization",
+    "apikey",
+    "api_key",
+    "token",
+    "secret",
+    "password",
+]);
+/**
+ * Deep-clone a value with credential fields masked. Safe to pass any JSON-ish
+ * object, including arrays and nested structures. Non-object values are
+ * returned as-is.
+ */
+function redact(input) {
+    if (input === null || input === undefined) {
+        return input;
+    }
+    if (Array.isArray(input)) {
+        return input.map((item) => redact(item));
+    }
+    if (typeof input === "object") {
+        const out = {};
+        for (const [key, value] of Object.entries(input)) {
+            if (FULLY_MASKED_KEYS.has(key.toLowerCase())) {
+                out[key] = MASK;
+            }
+            else {
+                out[key] = redact(value);
+            }
+        }
+        return out;
+    }
+    return input;
+}
+/** Mask the API key in the Authorization header for safe logging. */
+function redactHeaders(headers) {
+    const out = {};
+    for (const [key, value] of Object.entries(headers)) {
+        out[key] = FULLY_MASKED_KEYS.has(key.toLowerCase()) ? MASK : value;
+    }
+    return out;
+}

package/dist/modules/paytree-payment/lib/settings-reader.d.ts

@@ -0,0 +1,24 @@
+import { PaytreeEffectiveSettings, PaytreeProviderOptions } from "./types";
+/**
+ * The payment provider runs inside the Payment module's isolated container, so
+ * it cannot resolve the `paytree` module's service to read settings. Medusa's
+ * module isolation only restricts service resolution, not physical database
+ * access, so we read the shared `paytree_setting` table directly through the
+ * Postgres connection that Medusa registers in the container.
+ *
+ * The `paytree` module owns the schema and migration for this table; here we
+ * only read from it, with a short TTL cache so we don't hit the DB on every
+ * provider call.
+ */
+export declare class SettingsReader {
+    private readonly container_;
+    private readonly options_;
+    private cache_;
+    constructor(container: any, options: PaytreeProviderOptions);
+    private fallback;
+    /** Resolve the knex connection from the container, tolerating the proxy quirk. */
+    private getConnection;
+    /** Force the next read to hit the database. */
+    invalidate(): void;
+    get(): Promise<PaytreeEffectiveSettings>;
+}

package/dist/modules/paytree-payment/lib/settings-reader.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SettingsReader = void 0;
+const utils_1 = require("@medusajs/framework/utils");
+const constants_1 = require("./constants");
+/**
+ * The payment provider runs inside the Payment module's isolated container, so
+ * it cannot resolve the `paytree` module's service to read settings. Medusa's
+ * module isolation only restricts service resolution, not physical database
+ * access, so we read the shared `paytree_setting` table directly through the
+ * Postgres connection that Medusa registers in the container.
+ *
+ * The `paytree` module owns the schema and migration for this table; here we
+ * only read from it, with a short TTL cache so we don't hit the DB on every
+ * provider call.
+ */
+class SettingsReader {
+    constructor(container, options) {
+        this.cache_ = null;
+        this.container_ = container;
+        this.options_ = options;
+    }
+    fallback() {
+        return {
+            baseUrl: this.options_.baseUrl || constants_1.DEFAULT_BASE_URL,
+            logRequest: false,
+            logResponse: false,
+        };
+    }
+    /** Resolve the knex connection from the container, tolerating the proxy quirk. */
+    getConnection() {
+        try {
+            return this.container_.resolve(utils_1.ContainerRegistrationKeys.PG_CONNECTION);
+        }
+        catch {
+            // The MedusaContainer proxy injected into providers can shadow `resolve`
+            // for some keys; fall back to direct property access.
+            return this.container_?.[utils_1.ContainerRegistrationKeys.PG_CONNECTION] ?? null;
+        }
+    }
+    /** Force the next read to hit the database. */
+    invalidate() {
+        this.cache_ = null;
+    }
+    async get() {
+        const now = Date.now();
+        if (this.cache_ && this.cache_.expiresAt > now) {
+            return this.cache_.value;
+        }
+        const knex = this.getConnection();
+        let value = this.fallback();
+        if (knex) {
+            try {
+                const row = await knex(constants_1.SETTINGS_TABLE)
+                    .where({ id: constants_1.SETTINGS_SINGLETON_ID })
+                    .first();
+                if (row) {
+                    value = {
+                        baseUrl: row.base_url || value.baseUrl,
+                        logRequest: Boolean(row.log_request),
+                        logResponse: Boolean(row.log_response),
+                    };
+                }
+            }
+            catch {
+                // Table may not exist yet (migrations not run) — use the fallback.
+                value = this.fallback();
+            }
+        }
+        this.cache_ = { value, expiresAt: now + constants_1.SETTINGS_CACHE_TTL_MS };
+        return value;
+    }
+}
+exports.SettingsReader = SettingsReader;

package/dist/modules/paytree-payment/lib/status-map.d.ts

@@ -0,0 +1,26 @@
+import { PaymentActions, PaymentSessionStatus } from "@medusajs/framework/utils";
+import { PaytreeStatusValue } from "./constants";
+/**
+ * Map a Paytree transaction status to a Medusa PaymentSessionStatus.
+ *
+ * Paytree auto-captures on the hosted page, so a `success` status means the
+ * funds are captured. When `autoCapture` is false (reserved for a future
+ * auth/capture flow), `success` is treated as `authorized` instead.
+ */
+export declare function toSessionStatus(status: PaytreeStatusValue, autoCapture?: boolean): PaymentSessionStatus;
+export type CallbackOutcome = {
+    kind: "action";
+    action: PaymentActions;
+} | {
+    kind: "refund";
+} | {
+    kind: "ignore";
+};
+/**
+ * Decide what the callback route should do for a given Paytree status.
+ *
+ * Medusa's webhook pipeline only acts on `authorized` and `captured` actions,
+ * so refunds cannot be expressed as a webhook action. They are routed to the
+ * refund workflow instead (kind: "refund").
+ */
+export declare function callbackOutcome(status: PaytreeStatusValue): CallbackOutcome;

package/dist/modules/paytree-payment/lib/status-map.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toSessionStatus = toSessionStatus;
+exports.callbackOutcome = callbackOutcome;
+const utils_1 = require("@medusajs/framework/utils");
+const constants_1 = require("./constants");
+/**
+ * Map a Paytree transaction status to a Medusa PaymentSessionStatus.
+ *
+ * Paytree auto-captures on the hosted page, so a `success` status means the
+ * funds are captured. When `autoCapture` is false (reserved for a future
+ * auth/capture flow), `success` is treated as `authorized` instead.
+ */
+function toSessionStatus(status, autoCapture = true) {
+    switch (status) {
+        case constants_1.PaytreeStatus.PENDING:
+        case constants_1.PaytreeStatus.PARTIAL:
+            return utils_1.PaymentSessionStatus.PENDING;
+        case constants_1.PaytreeStatus.AUTHORIZED:
+            return utils_1.PaymentSessionStatus.AUTHORIZED;
+        case constants_1.PaytreeStatus.SUCCESS:
+            return autoCapture
+                ? utils_1.PaymentSessionStatus.CAPTURED
+                : utils_1.PaymentSessionStatus.AUTHORIZED;
+        case constants_1.PaytreeStatus.FAILED:
+            return utils_1.PaymentSessionStatus.ERROR;
+        case constants_1.PaytreeStatus.CANCELED:
+        case constants_1.PaytreeStatus.EXPIRED:
+            return utils_1.PaymentSessionStatus.CANCELED;
+        // Refunds and disputes leave the session captured; refunds are tracked
+        // as separate refund records, disputes are handled out of band.
+        case constants_1.PaytreeStatus.REFUNDED:
+        case constants_1.PaytreeStatus.PARTIAL_REFUNDED:
+        case constants_1.PaytreeStatus.DISPUTED:
+        case constants_1.PaytreeStatus.DISPUTED_WON:
+        case constants_1.PaytreeStatus.DISPUTED_LOST:
+        case constants_1.PaytreeStatus.DISPUTED_CLOSE:
+            return utils_1.PaymentSessionStatus.CAPTURED;
+        default:
+            return utils_1.PaymentSessionStatus.PENDING;
+    }
+}
+/**
+ * Decide what the callback route should do for a given Paytree status.
+ *
+ * Medusa's webhook pipeline only acts on `authorized` and `captured` actions,
+ * so refunds cannot be expressed as a webhook action. They are routed to the
+ * refund workflow instead (kind: "refund").
+ */
+function callbackOutcome(status) {
+    switch (status) {
+        case constants_1.PaytreeStatus.SUCCESS:
+            return { kind: "action", action: utils_1.PaymentActions.SUCCESSFUL };
+        case constants_1.PaytreeStatus.AUTHORIZED:
+            return { kind: "action", action: utils_1.PaymentActions.AUTHORIZED };
+        case constants_1.PaytreeStatus.FAILED:
+        case constants_1.PaytreeStatus.EXPIRED:
+        case constants_1.PaytreeStatus.CANCELED:
+            return { kind: "action", action: utils_1.PaymentActions.FAILED };
+        case constants_1.PaytreeStatus.REFUNDED:
+        case constants_1.PaytreeStatus.PARTIAL_REFUNDED:
+            return { kind: "refund" };
+        default:
+            return { kind: "ignore" };
+    }
+}

package/dist/modules/paytree-payment/lib/types.d.ts

@@ -0,0 +1,144 @@
+import { PaytreeStatusValue } from "./constants";
+/**
+ * Options passed to the provider from medusa-config.ts.
+ * The API key is ALWAYS sourced from an environment variable and never
+ * stored in the database or shown in the admin UI.
+ */
+export interface PaytreeProviderOptions {
+    /** Paytree API key. Sent as `Authorization: Token <apiKey>`. From env. */
+    apiKey: string;
+    /**
+     * Public URL of this Medusa backend, used to build the notification URL
+     * Paytree calls back. e.g. https://api.mystore.com
+     */
+    backendUrl: string;
+    /**
+     * Fallback base URL if no settings row exists yet in the DB.
+     * The admin-editable value in the DB takes precedence at runtime.
+     */
+    baseUrl?: string;
+    /**
+     * Default payment method requested from Paytree when the storefront
+     * doesn't specify one. Defaults to "card".
+     */
+    defaultMethod?: PaytreeMethod;
+}
+/** Effective settings resolved at runtime (DB row, falling back to options). */
+export interface PaytreeEffectiveSettings {
+    baseUrl: string;
+    logRequest: boolean;
+    logResponse: boolean;
+}
+export type PaytreeMethod = "card" | "crypto" | "wire" | "paypal" | "klarna" | "ideal" | "bancontact" | "trustly" | "kakaopay" | "p24" | "blik";
+/** Data the storefront must supply when creating the payment session. */
+export interface PaytreeSessionData {
+    /** Stable correlation key. We default this to the Medusa payment session id. */
+    session_id?: string;
+    customer?: {
+        first_name?: string;
+        last_name?: string;
+        email?: string;
+        phone?: string;
+    };
+    address?: {
+        street?: string;
+        city?: string;
+        state?: string;
+        zip?: string;
+        /** ISO 3166-1 alpha-2 country code. Required by Paytree. */
+        country?: string;
+    };
+    /** End-customer IP and UA, required by Paytree for fraud screening. */
+    session?: {
+        ip_address?: string;
+        user_agent?: string;
+    };
+    return_url?: string;
+    cancel_url?: string;
+    method?: PaytreeMethod;
+    order_items?: PaytreeOrderItem[];
+    /** Set after we create the intent. */
+    paytree_id?: string;
+    payment_link?: string;
+    transaction_ref?: string;
+    status?: PaytreeStatusValue;
+}
+export interface PaytreeOrderItem {
+    name: string;
+    description?: string;
+    quantity: number;
+    unit_price: string;
+    sku: string;
+}
+/** Body sent to POST /v1/transaction/payment_intent/. */
+export interface PaytreeCreateIntentBody {
+    transaction_ref: string;
+    client_ref: string;
+    amount: string;
+    amount_currency: string;
+    method: PaytreeMethod;
+    customer: {
+        first_name: string;
+        last_name: string;
+        email: string;
+        phone?: string;
+    };
+    address: {
+        street?: string;
+        city?: string;
+        state?: string;
+        zip?: string;
+        country: string;
+    };
+    session: {
+        ip_address: string;
+        user_agent: string;
+    };
+    callback: {
+        notification_url: string;
+        return_url: string;
+        cancel_url?: string;
+    };
+    metadata?: Record<string, unknown>;
+    order_items?: PaytreeOrderItem[];
+}
+/** 201 response from creating a payment intent. */
+export interface PaytreeCreateIntentResponse {
+    id: number | string;
+    client_ref: string;
+    payment_link: string;
+}
+/** A nested payment object within a payment intent. */
+export interface PaytreePayment {
+    id: string;
+    amount: string;
+    currency: string;
+    base_amount?: string;
+    base_currency?: string;
+    fee?: string;
+    refunded?: string;
+    status: PaytreeStatusValue;
+    refund?: PaytreeRefund[];
+    created: string;
+}
+export interface PaytreeRefund {
+    id: string;
+    amount: string;
+    currency: string;
+    payment: string;
+    gateway_id: string;
+    created: string;
+}
+/** GET /v1/transaction/payment_intent/{id}/ response. */
+export interface PaytreePaymentIntent {
+    id: string;
+    transaction_ref: string;
+    client_ref: string;
+    amount: string;
+    currency: string;
+    method: PaytreeMethod;
+    payment_link: string;
+    payment: PaytreePayment[];
+    metadata?: Record<string, unknown>;
+    created: string;
+}

package/dist/modules/paytree-payment/lib/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/modules/paytree-payment/service.d.ts

@@ -0,0 +1,36 @@
+import { AbstractPaymentProvider } from "@medusajs/framework/utils";
+import type { AuthorizePaymentInput, AuthorizePaymentOutput, CancelPaymentInput, CancelPaymentOutput, CapturePaymentInput, CapturePaymentOutput, DeletePaymentInput, DeletePaymentOutput, GetPaymentStatusInput, GetPaymentStatusOutput, InitiatePaymentInput, InitiatePaymentOutput, ProviderWebhookPayload, RefundPaymentInput, RefundPaymentOutput, RetrievePaymentInput, RetrievePaymentOutput, UpdatePaymentInput, UpdatePaymentOutput, WebhookActionResult } from "@medusajs/framework/types";
+import { SettingsReader } from "./lib/settings-reader";
+import { AuditWriter } from "./lib/audit";
+import { PaytreeLogger } from "./lib/logger";
+import { PaytreeProviderOptions } from "./lib/types";
+type Injected = Record<string, unknown>;
+export declare class PaytreePaymentProviderService extends AbstractPaymentProvider<PaytreeProviderOptions> {
+    static identifier: string;
+    protected readonly options_: PaytreeProviderOptions;
+    protected readonly container_: any;
+    protected readonly logger_: PaytreeLogger;
+    protected readonly settings_: SettingsReader;
+    protected readonly audit_: AuditWriter;
+    static validateOptions(options: PaytreeProviderOptions): void;
+    constructor(container: Injected, options: PaytreeProviderOptions);
+    /** Build a client using the current effective settings (live base URL + toggles). */
+    private client;
+    /** Notification URL Paytree will call back, with its substitution tags. */
+    private notificationUrl;
+    initiatePayment(input: InitiatePaymentInput): Promise<InitiatePaymentOutput>;
+    /** Read the live intent from Paytree by transaction_ref. */
+    private readIntent;
+    /** Roll up the latest status across the intent's payment objects. */
+    private latestStatus;
+    getPaymentStatus(input: GetPaymentStatusInput): Promise<GetPaymentStatusOutput>;
+    retrievePayment(input: RetrievePaymentInput): Promise<RetrievePaymentOutput>;
+    authorizePayment(input: AuthorizePaymentInput): Promise<AuthorizePaymentOutput>;
+    capturePayment(input: CapturePaymentInput): Promise<CapturePaymentOutput>;
+    cancelPayment(input: CancelPaymentInput): Promise<CancelPaymentOutput>;
+    deletePayment(input: DeletePaymentInput): Promise<DeletePaymentOutput>;
+    updatePayment(input: UpdatePaymentInput): Promise<UpdatePaymentOutput>;
+    refundPayment(input: RefundPaymentInput): Promise<RefundPaymentOutput>;
+    getWebhookActionAndData(payload: ProviderWebhookPayload["payload"]): Promise<WebhookActionResult>;
+}
+export default PaytreePaymentProviderService;