@paytree/medusa-payment-paytree 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Paytree
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,195 @@
+<h1 align="center">@paytree/medusa-payment-paytree</h1>
+
+<p align="center">
+  Paytree hosted-payment provider for <a href="https://medusajs.com">Medusa 2.0</a>.
+</p>
+
+Adds Paytree as a payment provider in your Medusa store. Customers are handed off
+to a Paytree hosted payment page, pay with the method they chose (card, PayPal,
+Klarna, iDEAL, crypto, bank transfer, and more), and are redirected back to your
+storefront. Status changes are reconciled server-side via a signed-by-lookup
+callback, and every event is written to an auditable log.
+
+Like `@medusajs/payment-stripe`, this is an installable package that does most
+of the work; you register it and wire up a few Medusa-side pieces.
+
+**Shipped compiled (installed from npm):**
+
+- **Payment provider** (`paytree`) — the package's default export, registered
+  under Medusa's Payment module.
+- **Data module** (`paytree`) — owns the settings + audit-log tables and their
+  migrations.
+
+**Shipped as copy-in source (the "some work you still do"):**
+
+- **API routes** under [`integration/api`](./integration/api) — the Paytree
+  callback (`/hooks/paytree`), the store methods endpoint
+  (`/store/paytree/methods`), and the admin settings/events APIs.
+- **Admin UI** under [`integration/admin`](./integration/admin) — a "Paytree"
+  sidebar group (Payments log + Settings).
+- **Storefront components** (Next.js) under [`storefront/`](./storefront).
+
+These live outside the compiled module because Medusa discovers API routes and
+admin extensions from *your app's* `src/` (and bundles admin with Vite), so they
+are copied in rather than imported. See
+[`integration/README.md`](./integration/README.md).
+
+---
+
+## Requirements
+
+- Medusa `>= 2.13`
+- Node `>= 20`
+- A Paytree account and API key
+
+## Installation
+
+```bash
+npm install @paytree/medusa-payment-paytree
+# or
+pnpm add @paytree/medusa-payment-paytree
+# or
+yarn add @paytree/medusa-payment-paytree
+```
+
+## Configuration
+
+Add your credentials to the backend `.env`:
+
+```bash
+PAYTREE_API_KEY=your_paytree_api_key
+# Optional — defaults to https://api.paytree.tech, also editable in the admin UI
+PAYTREE_BASE_URL=https://api.paytree.tech
+# Public URL of THIS backend, used to build the callback URL Paytree calls back
+BACKEND_URL=https://api.mystore.com
+```
+
+Register the payment **provider** (the package's default export) inside the
+Payment module's `providers` array, and register the **data module** so the
+settings/audit tables and their migrations are picked up:
+
+```js
+const { PAYTREE_API_KEY, PAYTREE_BASE_URL, BACKEND_URL } = process.env
+
+module.exports = defineConfig({
+  // ...
+  modules: [
+    // Data module: settings + audit-log tables (owns the migrations).
+    {
+      resolve: "@paytree/medusa-payment-paytree/dist/modules/paytree",
+    },
+    // Payment module with the Paytree provider.
+    {
+      key: Modules.PAYMENT,
+      resolve: "@medusajs/payment",
+      options: {
+        providers: [
+          {
+            resolve: "@paytree/medusa-payment-paytree",
+            id: "paytree",
+            options: {
+              apiKey: PAYTREE_API_KEY,
+              backendUrl: BACKEND_URL,
+              baseUrl: PAYTREE_BASE_URL,
+              // defaultMethod: "card",
+            },
+          },
+        ],
+      },
+    },
+  ],
+})
+```
+
+Then copy the API routes and admin UI from
+[`integration/`](./integration) into your backend's `src/` (see
+[`integration/README.md`](./integration/README.md)), and run migrations.
+
+> The API key is **only** ever read from the provider options (i.e. the
+> `PAYTREE_API_KEY` env var). It is never written to the database and never
+> returned by any API or shown in the admin UI.
+
+Run migrations to create the `paytree_setting` and `paytree_event_log` tables:
+
+```bash
+npx medusa db:migrate
+```
+
+Finally, enable Paytree for the relevant regions in the Medusa admin
+(**Settings → Regions → Payment providers**), the same as any other provider.
+
+## Provider options
+
+| Option          | Required | Description                                                                 |
+| --------------- | -------- | --------------------------------------------------------------------------- |
+| `apiKey`        | yes      | Paytree API key. Sent as `Authorization: Token <apiKey>`. Source from env.  |
+| `backendUrl`    | yes      | Public URL of this Medusa backend; used to build the callback URL.          |
+| `baseUrl`       | no       | Paytree API origin. Falls back to the admin setting, then the default.      |
+| `defaultMethod` | no       | Method requested when the storefront doesn't specify one. Defaults `card`.  |
+
+## How it works
+
+```mermaid
+sequenceDiagram
+    participant S as Storefront
+    participant M as Medusa (provider)
+    participant P as Paytree API
+    participant C as Customer
+
+    S->>M: initiatePaymentSession (customer, address, session, method)
+    M->>P: POST /v1/transaction/payment_intent/
+    P-->>M: { id, payment_link }
+    M-->>S: session.data.payment_link
+    S->>C: redirect to hosted payment page
+    C->>P: pays
+    P->>M: GET /hooks/paytree?payment_intent_id=..&transaction_id=..
+    M->>P: authoritative status lookup (by transaction_ref)
+    M->>M: processPaymentWorkflow / refundPaymentWorkflow
+    C->>S: redirected to return_url → order confirmed
+```
+
+Key design points:
+
+- **Auto-capture model.** Paytree captures on the hosted page, so a `success`
+  status maps to Medusa `CAPTURED`. There is no separate capture call.
+- **Callback is trusted by lookup, not signature.** The `/hooks/paytree` GET
+  callback carries only ids; the handler re-fetches the authoritative status
+  from Paytree using the secret API key. It is idempotent and safe to retry.
+- **Refunds are reflected, not initiated.** Refunds are performed in the Paytree
+  back office; the callback drives Medusa's refund workflow, and the provider
+  verifies the refund exists in Paytree before recording it.
+- **Correlation.** The Medusa payment session id is used as Paytree's
+  `transaction_ref`, so a payment can be traced end-to-end by that single id.
+
+See [`docs/architecture.md`](./docs/architecture.md) for the full breakdown.
+
+## Admin UI
+
+Once installed, a **Paytree** group appears in the admin sidebar:
+
+- **Payments** — the audit log of every event (initiate, capture, callback,
+  refund, errors), filterable by session/intent id and event type.
+- **Settings** — the API endpoint, per-method enable/label overrides shown at
+  checkout, and opt-in request/response logging (always redacted).
+
+## Storefront
+
+The backend exposes `GET /store/paytree/methods` returning the admin-enabled
+methods. The [`storefront/`](./storefront) folder contains reference Next.js
+components (method picker, hosted-page redirect button, data loader) you can drop
+into a Medusa Next.js starter. See
+[`docs/storefront-integration.md`](./docs/storefront-integration.md).
+
+## Documentation
+
+| Doc | What's in it |
+| --- | --- |
+| [Getting started](./docs/getting-started.md) | Install, configure, first payment |
+| [Configuration](./docs/configuration.md) | Env vars, options, admin settings |
+| [Storefront integration](./docs/storefront-integration.md) | Wiring the checkout UI |
+| [Architecture](./docs/architecture.md) | Modules, data flow, design decisions |
+| [API reference](./docs/api-reference.md) | Store, admin, and callback routes |
+
+## License
+
+[MIT](./LICENSE)

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Public entry point for the Paytree Medusa payment package.
+ *
+ * The compiled package ships two backend modules — the payment PROVIDER and a
+ * small DATA module that owns the settings + audit-log tables — plus the shared
+ * helpers used by the copy-in API routes and admin pages (see `integration/`).
+ */
+/**
+ * Default export: registers the Paytree payment provider with the Payment
+ * module. Reference this from `medusa-config` under the payment module's
+ * `providers` array (see the README).
+ */
+declare const _default: import("@medusajs/types").ModuleProviderExports;
+export default _default;
+export { default as PaytreePaymentProviderService, PaytreePaymentProviderService as PaytreeProvider, } from "./modules/paytree-payment/service";
+export { default as PaytreeModule, PAYTREE_MODULE, PaytreeService, } from "./modules/paytree";
+export { PAYTREE_PROVIDER_IDENTIFIER, PaytreeStatus, AuditEvent, DEFAULT_BASE_URL, } from "./modules/paytree-payment/lib/constants";
+export type { PaytreeStatusValue, AuditEventType, } from "./modules/paytree-payment/lib/constants";
+export { PAYTREE_METHOD_DEFS, resolveMethods, normalizeMethods, } from "./modules/paytree-payment/lib/methods";
+export type { StoredMethodConfig, ResolvedMethodConfig, PaytreeMethodId, } from "./modules/paytree-payment/lib/methods";
+export { PaytreeClient } from "./modules/paytree-payment/lib/client";
+export type { PaytreeClientConfig } from "./modules/paytree-payment/lib/client";
+export { PaytreeLogger } from "./modules/paytree-payment/lib/logger";
+export type { Correlation } from "./modules/paytree-payment/lib/logger";
+export { toSessionStatus, callbackOutcome, } from "./modules/paytree-payment/lib/status-map";
+export type { CallbackOutcome } from "./modules/paytree-payment/lib/status-map";
+export { toPaytreeAmount, fromPaytreeAmount, newlyRefundedAmount, } from "./modules/paytree-payment/lib/amount";
+export type { PaytreeProviderOptions, PaytreeMethod, PaytreeSessionData, PaytreeOrderItem, PaytreePaymentIntent, } from "./modules/paytree-payment/lib/types";

package/dist/index.js

@@ -0,0 +1,55 @@
+"use strict";
+/**
+ * Public entry point for the Paytree Medusa payment package.
+ *
+ * The compiled package ships two backend modules — the payment PROVIDER and a
+ * small DATA module that owns the settings + audit-log tables — plus the shared
+ * helpers used by the copy-in API routes and admin pages (see `integration/`).
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.newlyRefundedAmount = exports.fromPaytreeAmount = exports.toPaytreeAmount = exports.callbackOutcome = exports.toSessionStatus = exports.PaytreeLogger = exports.PaytreeClient = exports.normalizeMethods = exports.resolveMethods = exports.PAYTREE_METHOD_DEFS = exports.DEFAULT_BASE_URL = exports.AuditEvent = exports.PaytreeStatus = exports.PAYTREE_PROVIDER_IDENTIFIER = exports.PaytreeService = exports.PAYTREE_MODULE = exports.PaytreeModule = exports.PaytreeProvider = exports.PaytreePaymentProviderService = void 0;
+const utils_1 = require("@medusajs/framework/utils");
+const service_1 = __importDefault(require("./modules/paytree-payment/service"));
+/**
+ * Default export: registers the Paytree payment provider with the Payment
+ * module. Reference this from `medusa-config` under the payment module's
+ * `providers` array (see the README).
+ */
+exports.default = (0, utils_1.ModuleProvider)(utils_1.Modules.PAYMENT, {
+    services: [service_1.default],
+});
+// Payment provider service.
+var service_2 = require("./modules/paytree-payment/service");
+Object.defineProperty(exports, "PaytreePaymentProviderService", { enumerable: true, get: function () { return __importDefault(service_2).default; } });
+Object.defineProperty(exports, "PaytreeProvider", { enumerable: true, get: function () { return service_2.PaytreePaymentProviderService; } });
+// Data module (settings + audit-log tables; resolvable from routes/subscribers).
+var paytree_1 = require("./modules/paytree");
+Object.defineProperty(exports, "PaytreeModule", { enumerable: true, get: function () { return __importDefault(paytree_1).default; } });
+Object.defineProperty(exports, "PAYTREE_MODULE", { enumerable: true, get: function () { return paytree_1.PAYTREE_MODULE; } });
+Object.defineProperty(exports, "PaytreeService", { enumerable: true, get: function () { return paytree_1.PaytreeService; } });
+// Constants.
+var constants_1 = require("./modules/paytree-payment/lib/constants");
+Object.defineProperty(exports, "PAYTREE_PROVIDER_IDENTIFIER", { enumerable: true, get: function () { return constants_1.PAYTREE_PROVIDER_IDENTIFIER; } });
+Object.defineProperty(exports, "PaytreeStatus", { enumerable: true, get: function () { return constants_1.PaytreeStatus; } });
+Object.defineProperty(exports, "AuditEvent", { enumerable: true, get: function () { return constants_1.AuditEvent; } });
+Object.defineProperty(exports, "DEFAULT_BASE_URL", { enumerable: true, get: function () { return constants_1.DEFAULT_BASE_URL; } });
+// Method catalog + resolution helpers (used by the admin + store routes).
+var methods_1 = require("./modules/paytree-payment/lib/methods");
+Object.defineProperty(exports, "PAYTREE_METHOD_DEFS", { enumerable: true, get: function () { return methods_1.PAYTREE_METHOD_DEFS; } });
+Object.defineProperty(exports, "resolveMethods", { enumerable: true, get: function () { return methods_1.resolveMethods; } });
+Object.defineProperty(exports, "normalizeMethods", { enumerable: true, get: function () { return methods_1.normalizeMethods; } });
+// REST client, logging, amount + status helpers (used by the callback route).
+var client_1 = require("./modules/paytree-payment/lib/client");
+Object.defineProperty(exports, "PaytreeClient", { enumerable: true, get: function () { return client_1.PaytreeClient; } });
+var logger_1 = require("./modules/paytree-payment/lib/logger");
+Object.defineProperty(exports, "PaytreeLogger", { enumerable: true, get: function () { return logger_1.PaytreeLogger; } });
+var status_map_1 = require("./modules/paytree-payment/lib/status-map");
+Object.defineProperty(exports, "toSessionStatus", { enumerable: true, get: function () { return status_map_1.toSessionStatus; } });
+Object.defineProperty(exports, "callbackOutcome", { enumerable: true, get: function () { return status_map_1.callbackOutcome; } });
+var amount_1 = require("./modules/paytree-payment/lib/amount");
+Object.defineProperty(exports, "toPaytreeAmount", { enumerable: true, get: function () { return amount_1.toPaytreeAmount; } });
+Object.defineProperty(exports, "fromPaytreeAmount", { enumerable: true, get: function () { return amount_1.fromPaytreeAmount; } });
+Object.defineProperty(exports, "newlyRefundedAmount", { enumerable: true, get: function () { return amount_1.newlyRefundedAmount; } });

package/dist/modules/paytree/index.d.ts

@@ -0,0 +1,36 @@
+import PaytreeService from "./service";
+export declare const PAYTREE_MODULE = "paytree";
+declare const _default: import("@medusajs/types").ModuleExports<typeof PaytreeService> & {
+    linkable: {
+        readonly paytreeSetting: {
+            id: {
+                serviceName: "paytree";
+                field: "paytreeSetting";
+                linkable: "paytree_setting_id";
+                primaryKey: "id";
+            };
+            toJSON: () => {
+                serviceName: "paytree";
+                field: "paytreeSetting";
+                linkable: "paytree_setting_id";
+                primaryKey: "id";
+            };
+        };
+        readonly paytreeEventLog: {
+            id: {
+                serviceName: "paytree";
+                field: "paytreeEventLog";
+                linkable: "paytree_event_log_id";
+                primaryKey: "id";
+            };
+            toJSON: () => {
+                serviceName: "paytree";
+                field: "paytreeEventLog";
+                linkable: "paytree_event_log_id";
+                primaryKey: "id";
+            };
+        };
+    };
+};
+export default _default;
+export { PaytreeService };

package/dist/modules/paytree/index.js

@@ -0,0 +1,13 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PaytreeService = exports.PAYTREE_MODULE = void 0;
+const utils_1 = require("@medusajs/framework/utils");
+const service_1 = __importDefault(require("./service"));
+exports.PaytreeService = service_1.default;
+exports.PAYTREE_MODULE = "paytree";
+exports.default = (0, utils_1.Module)(exports.PAYTREE_MODULE, {
+    service: service_1.default,
+});

package/dist/modules/paytree/migrations/Migration20260617000000.d.ts

@@ -0,0 +1,5 @@
+import { Migration } from "@mikro-orm/migrations";
+export declare class Migration20260617000000 extends Migration {
+    up(): Promise<void>;
+    down(): Promise<void>;
+}

package/dist/modules/paytree/migrations/Migration20260617000000.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Migration20260617000000 = void 0;
+const migrations_1 = require("@mikro-orm/migrations");
+class Migration20260617000000 extends migrations_1.Migration {
+    async up() {
+        this.addSql(`
+      CREATE TABLE IF NOT EXISTS "paytree_setting" (
+        "id" TEXT NOT NULL,
+        "base_url" TEXT NOT NULL,
+        "log_request" BOOLEAN NOT NULL DEFAULT FALSE,
+        "log_response" BOOLEAN NOT NULL DEFAULT FALSE,
+        "created_at" TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+        "updated_at" TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+        "deleted_at" TIMESTAMPTZ NULL,
+        CONSTRAINT "paytree_setting_pkey" PRIMARY KEY ("id")
+      );
+    `);
+        this.addSql(`
+      CREATE TABLE IF NOT EXISTS "paytree_event_log" (
+        "id" TEXT NOT NULL,
+        "event" TEXT NOT NULL,
+        "session_id" TEXT NULL,
+        "paytree_id" TEXT NULL,
+        "status" TEXT NULL,
+        "amount" TEXT NULL,
+        "currency" TEXT NULL,
+        "detail" JSONB NULL,
+        "error" TEXT NULL,
+        "created_at" TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+        "updated_at" TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+        "deleted_at" TIMESTAMPTZ NULL,
+        CONSTRAINT "paytree_event_log_pkey" PRIMARY KEY ("id")
+      );
+    `);
+        this.addSql(`
+      CREATE INDEX IF NOT EXISTS "IDX_paytree_event_log_session_id"
+        ON "paytree_event_log" ("session_id");
+    `);
+        this.addSql(`
+      CREATE INDEX IF NOT EXISTS "IDX_paytree_event_log_paytree_id"
+        ON "paytree_event_log" ("paytree_id");
+    `);
+        this.addSql(`
+      CREATE INDEX IF NOT EXISTS "IDX_paytree_event_log_created_at"
+        ON "paytree_event_log" ("created_at");
+    `);
+    }
+    async down() {
+        this.addSql(`DROP TABLE IF EXISTS "paytree_event_log" CASCADE;`);
+        this.addSql(`DROP TABLE IF EXISTS "paytree_setting" CASCADE;`);
+    }
+}
+exports.Migration20260617000000 = Migration20260617000000;

package/dist/modules/paytree/migrations/Migration20260618000000.d.ts

@@ -0,0 +1,5 @@
+import { Migration } from "@mikro-orm/migrations";
+export declare class Migration20260618000000 extends Migration {
+    up(): Promise<void>;
+    down(): Promise<void>;
+}

package/dist/modules/paytree/migrations/Migration20260618000000.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Migration20260618000000 = void 0;
+const migrations_1 = require("@mikro-orm/migrations");
+class Migration20260618000000 extends migrations_1.Migration {
+    async up() {
+        this.addSql(`
+      ALTER TABLE "paytree_setting"
+      ADD COLUMN IF NOT EXISTS "methods" JSONB NULL;
+    `);
+    }
+    async down() {
+        this.addSql(`
+      ALTER TABLE "paytree_setting"
+      DROP COLUMN IF EXISTS "methods";
+    `);
+    }
+}
+exports.Migration20260618000000 = Migration20260618000000;

package/dist/modules/paytree/models/paytree-event-log.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Append-only audit trail of payment events, for traceability. Written by the
+ * provider, the callback route, and the subscriber; read by the admin UI.
+ *
+ * Every payload stored in `detail` is redacted before write, so this table
+ * never holds secrets or raw PII.
+ */
+export declare const PaytreeEventLog: import("@medusajs/framework/utils").DmlEntity<import("@medusajs/framework/utils").DMLEntitySchemaBuilder<{
+    id: import("@medusajs/framework/utils").PrimaryKeyModifier<string, import("@medusajs/framework/utils").IdProperty>;
+    /** One of the AuditEvent values (initiate_payment, capture_payment, ...). */
+    event: import("@medusajs/framework/utils").TextProperty;
+    /** Medusa payment session id (our transaction_ref). */
+    session_id: import("@medusajs/framework/utils").NullableModifier<string, import("@medusajs/framework/utils").TextProperty>;
+    /** Paytree payment intent id. */
+    paytree_id: import("@medusajs/framework/utils").NullableModifier<string, import("@medusajs/framework/utils").TextProperty>;
+    /** Paytree status at the time of the event. */
+    status: import("@medusajs/framework/utils").NullableModifier<string, import("@medusajs/framework/utils").TextProperty>;
+    amount: import("@medusajs/framework/utils").NullableModifier<string, import("@medusajs/framework/utils").TextProperty>;
+    currency: import("@medusajs/framework/utils").NullableModifier<string, import("@medusajs/framework/utils").TextProperty>;
+    /** Redacted JSON blob with event-specific detail. */
+    detail: import("@medusajs/framework/utils").NullableModifier<Record<string, unknown>, import("@medusajs/framework/utils").JSONProperty>;
+    /** Error message, when the event records a failure. */
+    error: import("@medusajs/framework/utils").NullableModifier<string, import("@medusajs/framework/utils").TextProperty>;
+}>, "paytree_event_log">;
+export default PaytreeEventLog;

package/dist/modules/paytree/models/paytree-event-log.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PaytreeEventLog = void 0;
+const utils_1 = require("@medusajs/framework/utils");
+/**
+ * Append-only audit trail of payment events, for traceability. Written by the
+ * provider, the callback route, and the subscriber; read by the admin UI.
+ *
+ * Every payload stored in `detail` is redacted before write, so this table
+ * never holds secrets or raw PII.
+ */
+exports.PaytreeEventLog = utils_1.model.define("paytree_event_log", {
+    id: utils_1.model.id().primaryKey(),
+    /** One of the AuditEvent values (initiate_payment, capture_payment, ...). */
+    event: utils_1.model.text(),
+    /** Medusa payment session id (our transaction_ref). */
+    session_id: utils_1.model.text().nullable(),
+    /** Paytree payment intent id. */
+    paytree_id: utils_1.model.text().nullable(),
+    /** Paytree status at the time of the event. */
+    status: utils_1.model.text().nullable(),
+    amount: utils_1.model.text().nullable(),
+    currency: utils_1.model.text().nullable(),
+    /** Redacted JSON blob with event-specific detail. */
+    detail: utils_1.model.json().nullable(),
+    /** Error message, when the event records a failure. */
+    error: utils_1.model.text().nullable(),
+});
+exports.default = exports.PaytreeEventLog;

package/dist/modules/paytree/models/paytree-setting.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Global settings for the Paytree integration, editable from the admin UI.
+ * Only NON-secret operational config lives here. The API key is never stored
+ * in the database — it comes from the PAYTREE_API_KEY environment variable.
+ *
+ * We keep a single row (id = "paytree_settings").
+ */
+export declare const PaytreeSetting: import("@medusajs/framework/utils").DmlEntity<import("@medusajs/framework/utils").DMLEntitySchemaBuilder<{
+    id: import("@medusajs/framework/utils").PrimaryKeyModifier<string, import("@medusajs/framework/utils").IdProperty>;
+    /** Paytree API origin requests are sent to. */
+    base_url: import("@medusajs/framework/utils").TextProperty;
+    /** When true, outbound request bodies are logged (always redacted). */
+    log_request: import("@medusajs/framework/utils").BooleanProperty;
+    /** When true, Paytree response bodies are logged (always redacted). */
+    log_response: import("@medusajs/framework/utils").BooleanProperty;
+    /**
+     * Per-method config the admin curates: which Paytree methods are offered at
+     * checkout and an optional label override. Shape: Array<{ method, enabled,
+     * label? }>. Null until the admin saves; resolved against canonical defaults.
+     */
+    methods: import("@medusajs/framework/utils").NullableModifier<Record<string, unknown>, import("@medusajs/framework/utils").JSONProperty>;
+}>, "paytree_setting">;
+export default PaytreeSetting;

package/dist/modules/paytree/models/paytree-setting.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PaytreeSetting = void 0;
+const utils_1 = require("@medusajs/framework/utils");
+/**
+ * Global settings for the Paytree integration, editable from the admin UI.
+ * Only NON-secret operational config lives here. The API key is never stored
+ * in the database — it comes from the PAYTREE_API_KEY environment variable.
+ *
+ * We keep a single row (id = "paytree_settings").
+ */
+exports.PaytreeSetting = utils_1.model.define("paytree_setting", {
+    id: utils_1.model.id().primaryKey(),
+    /** Paytree API origin requests are sent to. */
+    base_url: utils_1.model.text(),
+    /** When true, outbound request bodies are logged (always redacted). */
+    log_request: utils_1.model.boolean().default(false),
+    /** When true, Paytree response bodies are logged (always redacted). */
+    log_response: utils_1.model.boolean().default(false),
+    /**
+     * Per-method config the admin curates: which Paytree methods are offered at
+     * checkout and an optional label override. Shape: Array<{ method, enabled,
+     * label? }>. Null until the admin saves; resolved against canonical defaults.
+     */
+    methods: utils_1.model.json().nullable(),
+});
+exports.default = exports.PaytreeSetting;

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

@@ -0,0 +1,60 @@
+declare const PaytreeService_base: import("@medusajs/framework/utils").MedusaServiceReturnType<import("@medusajs/framework/utils").ModelConfigurationsToConfigTemplate<{
+    readonly PaytreeSetting: import("@medusajs/framework/utils").DmlEntity<import("@medusajs/framework/utils").DMLEntitySchemaBuilder<{
+        id: import("@medusajs/framework/utils").PrimaryKeyModifier<string, import("@medusajs/framework/utils").IdProperty>;
+        base_url: import("@medusajs/framework/utils").TextProperty;
+        log_request: import("@medusajs/framework/utils").BooleanProperty;
+        log_response: import("@medusajs/framework/utils").BooleanProperty;
+        methods: import("@medusajs/framework/utils").NullableModifier<Record<string, unknown>, import("@medusajs/framework/utils").JSONProperty>;
+    }>, "paytree_setting">;
+    readonly PaytreeEventLog: import("@medusajs/framework/utils").DmlEntity<import("@medusajs/framework/utils").DMLEntitySchemaBuilder<{
+        id: import("@medusajs/framework/utils").PrimaryKeyModifier<string, import("@medusajs/framework/utils").IdProperty>;
+        event: import("@medusajs/framework/utils").TextProperty;
+        session_id: import("@medusajs/framework/utils").NullableModifier<string, import("@medusajs/framework/utils").TextProperty>;
+        paytree_id: import("@medusajs/framework/utils").NullableModifier<string, import("@medusajs/framework/utils").TextProperty>;
+        status: import("@medusajs/framework/utils").NullableModifier<string, import("@medusajs/framework/utils").TextProperty>;
+        amount: import("@medusajs/framework/utils").NullableModifier<string, import("@medusajs/framework/utils").TextProperty>;
+        currency: import("@medusajs/framework/utils").NullableModifier<string, import("@medusajs/framework/utils").TextProperty>;
+        detail: import("@medusajs/framework/utils").NullableModifier<Record<string, unknown>, import("@medusajs/framework/utils").JSONProperty>;
+        error: import("@medusajs/framework/utils").NullableModifier<string, import("@medusajs/framework/utils").TextProperty>;
+    }>, "paytree_event_log">;
+}>>;
+/**
+ * Service for the `paytree` module. Resolvable from app-level API routes and
+ * subscribers (not from the isolated payment provider — that path reads the
+ * table directly). Exposes settings get/upsert and audit-log queries used by
+ * the admin UI.
+ */
+declare class PaytreeService extends PaytreeService_base {
+    /** Return the single settings row, creating defaults if absent. */
+    getSettings(defaults: {
+        base_url: string;
+        log_request?: boolean;
+        log_response?: boolean;
+    }): Promise<{
+        id: string;
+        base_url: string;
+        log_request: boolean;
+        log_response: boolean;
+        methods: Record<string, unknown> | null;
+        created_at: Date;
+        updated_at: Date;
+        deleted_at: Date | null;
+    }>;
+    /** Upsert the single settings row. */
+    upsertSettings(values: {
+        base_url: string;
+        log_request: boolean;
+        log_response: boolean;
+        methods?: unknown;
+    }): Promise<{
+        id: string;
+        base_url: string;
+        log_request: boolean;
+        log_response: boolean;
+        methods: Record<string, unknown> | null;
+        created_at: Date;
+        updated_at: Date;
+        deleted_at: Date | null;
+    }>;
+}
+export default PaytreeService;