@paytree/medusa-payment-paytree 0.1.0

package/integration/admin/routes/paytree/settings/page.tsx

@@ -0,0 +1,214 @@
+import { defineRouteConfig } from "@medusajs/admin-sdk"
+import { CogSixTooth } from "@medusajs/icons"
+import {
+  Badge,
+  Button,
+  Container,
+  Heading,
+  Input,
+  Label,
+  Switch,
+  Text,
+  toast,
+} from "@medusajs/ui"
+import { useEffect, useState } from "react"
+import { MethodIcon } from "../method-icons"
+import { api } from "../api"
+
+type MethodConfig = {
+  method: string
+  enabled: boolean
+  label: string
+}
+
+type Settings = {
+  base_url: string
+  log_request: boolean
+  log_response: boolean
+  methods: MethodConfig[]
+}
+
+const SettingsPage = () => {
+  const [settings, setSettings] = useState<Settings>({
+    base_url: "",
+    log_request: false,
+    log_response: false,
+    methods: [],
+  })
+  const [keyConfigured, setKeyConfigured] = useState(false)
+  const [loading, setLoading] = useState(true)
+  const [saving, setSaving] = useState(false)
+
+  const updateMethod = (method: string, patch: Partial<MethodConfig>) =>
+    setSettings((s) => ({
+      ...s,
+      methods: s.methods.map((m) =>
+        m.method === method ? { ...m, ...patch } : m
+      ),
+    }))
+
+  const enabledCount = settings.methods.filter((m) => m.enabled).length
+
+  useEffect(() => {
+    api("settings")
+      .then((d) => {
+        setSettings(d.settings)
+        setKeyConfigured(d.api_key_configured)
+      })
+      .catch((e) => toast.error(e.message))
+      .finally(() => setLoading(false))
+  }, [])
+
+  const save = async () => {
+    setSaving(true)
+    try {
+      const d = await api("settings", {
+        method: "POST",
+        body: JSON.stringify(settings),
+      })
+      setSettings(d.settings)
+      toast.success("Settings saved")
+    } catch (e: any) {
+      toast.error(e.message)
+    } finally {
+      setSaving(false)
+    }
+  }
+
+  return (
+    <div className="flex flex-col gap-y-3">
+    <Container className="divide-y p-0">
+      <div className="flex items-center justify-between px-6 py-4">
+        <Heading level="h2">Paytree settings</Heading>
+        <Badge color={keyConfigured ? "green" : "red"} size="2xsmall">
+          {keyConfigured ? "API key configured" : "API key missing"}
+        </Badge>
+      </div>
+
+      <div className="flex flex-col gap-6 px-6 py-6">
+        <div className="flex flex-col gap-2">
+          <Label htmlFor="base_url">Paytree API endpoint</Label>
+          <Input
+            id="base_url"
+            placeholder="https://api.paytree.tech"
+            value={settings.base_url}
+            disabled={loading}
+            onChange={(e) =>
+              setSettings({ ...settings, base_url: e.target.value })
+            }
+          />
+          <Text size="small" className="text-ui-fg-subtle">
+            Requests are sent here with your API key. Any https endpoint is
+            accepted. The API key itself is set with the PAYTREE_API_KEY
+            environment variable, not here.
+          </Text>
+        </div>
+
+        <div className="flex flex-col gap-3">
+          <div className="flex items-center justify-between">
+            <div className="flex flex-col">
+              <Label>Payment methods</Label>
+              <Text size="small" className="text-ui-fg-subtle">
+                Choose which methods customers can select at checkout, and
+                rename any of them. Disabled methods are never shown.
+              </Text>
+            </div>
+            <Badge size="2xsmall" color={enabledCount > 0 ? "green" : "orange"}>
+              {enabledCount} enabled
+            </Badge>
+          </div>
+
+          <div className="flex flex-col divide-y rounded-lg border border-ui-border-base">
+            {settings.methods.map((m) => (
+              <div
+                key={m.method}
+                className="flex items-center gap-3 px-3 py-2.5"
+              >
+                <div className="flex h-8 w-8 shrink-0 items-center justify-center text-ui-fg-subtle">
+                  <MethodIcon method={m.method} />
+                </div>
+                <Input
+                  aria-label={`${m.method} label`}
+                  className="flex-1"
+                  value={m.label}
+                  disabled={loading || !m.enabled}
+                  onChange={(e) =>
+                    updateMethod(m.method, { label: e.target.value })
+                  }
+                />
+                <Switch
+                  checked={m.enabled}
+                  disabled={loading}
+                  onCheckedChange={(v) => updateMethod(m.method, { enabled: v })}
+                />
+              </div>
+            ))}
+          </div>
+        </div>
+      </div>
+    </Container>
+
+    <Container className="divide-y p-0">
+      <div className="px-6 py-4">
+        <Heading level="h2">Logging</Heading>
+      </div>
+
+      <div className="flex flex-col gap-3 px-6 py-6">
+        <Text size="small" className="text-ui-fg-subtle">
+          Diagnostic logging for Paytree traffic. Sensitive data is always
+          masked.
+        </Text>
+
+        <div className="flex flex-col divide-y rounded-lg border border-ui-border-base">
+          <div className="flex items-center justify-between gap-4 px-4 py-3">
+            <div className="flex flex-col">
+              <Label htmlFor="log_request">Log outgoing requests</Label>
+              <Text size="small" className="text-ui-fg-subtle">
+                Records request bodies sent to Paytree. Card data, the API key,
+                and personal details are always masked.
+              </Text>
+            </div>
+            <Switch
+              id="log_request"
+              checked={settings.log_request}
+              onCheckedChange={(v) =>
+                setSettings({ ...settings, log_request: v })
+              }
+            />
+          </div>
+
+          <div className="flex items-center justify-between gap-4 px-4 py-3">
+            <div className="flex flex-col">
+              <Label htmlFor="log_response">Log responses</Label>
+              <Text size="small" className="text-ui-fg-subtle">
+                Records responses received from Paytree, with sensitive fields
+                masked.
+              </Text>
+            </div>
+            <Switch
+              id="log_response"
+              checked={settings.log_response}
+              onCheckedChange={(v) =>
+                setSettings({ ...settings, log_response: v })
+              }
+            />
+          </div>
+        </div>
+      </div>
+    </Container>
+
+    <div className="flex justify-end">
+      <Button onClick={save} isLoading={saving} disabled={loading}>
+        Save changes
+      </Button>
+    </div>
+    </div>
+  )
+}
+
+export const config = defineRouteConfig({
+  label: "Settings",
+  icon: CogSixTooth,
+})
+
+export default SettingsPage

package/integration/api/admin/paytree/events/route.ts

@@ -0,0 +1,35 @@
+import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http";
+import { PAYTREE_MODULE } from "@paytree/medusa-payment-paytree";
+
+/**
+ * GET audit-log events for the admin UI. Supports filtering by session id,
+ * Paytree intent id, and event type, plus simple pagination.
+ */
+export async function GET(
+  req: MedusaRequest,
+  res: MedusaResponse,
+): Promise<void> {
+  const paytree: any = req.scope.resolve(PAYTREE_MODULE);
+
+  const limit = Math.min(Number(req.query.limit ?? 50), 200);
+  const offset = Number(req.query.offset ?? 0);
+
+  const filters: Record<string, unknown> = {};
+  if (req.query.session_id) {
+    filters.session_id = String(req.query.session_id);
+  }
+  if (req.query.paytree_id) {
+    filters.paytree_id = String(req.query.paytree_id);
+  }
+  if (req.query.event) {
+    filters.event = String(req.query.event);
+  }
+
+  const [events, count] = await paytree.listAndCountPaytreeEventLogs(filters, {
+    take: limit,
+    skip: offset,
+    order: { created_at: "DESC" },
+  });
+
+  res.json({ events, count, limit, offset });
+}

package/integration/api/admin/paytree/settings/route.ts

@@ -0,0 +1,86 @@
+import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http";
+import { MedusaError } from "@medusajs/framework/utils";
+import {
+  PAYTREE_MODULE,
+  DEFAULT_BASE_URL,
+  normalizeMethods,
+  resolveMethods,
+  type StoredMethodConfig,
+} from "@paytree/medusa-payment-paytree";
+
+/**
+ * GET current settings. The API key is never returned — it lives only in the
+ * PAYTREE_API_KEY environment variable. We return whether it is configured so
+ * the UI can show a status, without exposing the value.
+ */
+export async function GET(
+  req: MedusaRequest,
+  res: MedusaResponse,
+): Promise<void> {
+  const paytree: any = req.scope.resolve(PAYTREE_MODULE);
+  const settings = await paytree.getSettings({ base_url: DEFAULT_BASE_URL });
+  res.json({
+    settings: {
+      base_url: settings.base_url,
+      log_request: settings.log_request,
+      log_response: settings.log_response,
+      methods: resolveMethods(settings.methods as StoredMethodConfig[] | null),
+    },
+    api_key_configured: Boolean(process.env.PAYTREE_API_KEY),
+  });
+}
+
+interface UpdateBody {
+  base_url?: string;
+  log_request?: boolean;
+  log_response?: boolean;
+  methods?: StoredMethodConfig[];
+}
+
+/**
+ * Update settings. The base URL accepts any endpoint (no host restriction);
+ * we only require a well-formed https URL so the API key is never sent over
+ * cleartext http.
+ */
+export async function POST(
+  req: MedusaRequest,
+  res: MedusaResponse,
+): Promise<void> {
+  const body = (req.body ?? {}) as UpdateBody;
+
+  const baseUrl = (body.base_url ?? "").trim();
+  let parsed: URL;
+  try {
+    parsed = new URL(baseUrl);
+  } catch {
+    throw new MedusaError(
+      MedusaError.Types.INVALID_DATA,
+      "Enter a valid URL, e.g. https://api.paytree.tech",
+    );
+  }
+  if (parsed.protocol !== "https:") {
+    throw new MedusaError(
+      MedusaError.Types.INVALID_DATA,
+      "The base URL must use https so the API key is never sent in cleartext.",
+    );
+  }
+
+  const methods = normalizeMethods(body.methods);
+
+  const paytree: any = req.scope.resolve(PAYTREE_MODULE);
+  const saved = await paytree.upsertSettings({
+    base_url: baseUrl.replace(/\/+$/, ""),
+    log_request: Boolean(body.log_request),
+    log_response: Boolean(body.log_response),
+    methods,
+  });
+
+  res.json({
+    settings: {
+      base_url: saved.base_url,
+      log_request: saved.log_request,
+      log_response: saved.log_response,
+      methods: resolveMethods(saved.methods as StoredMethodConfig[] | null),
+    },
+  });
+}

package/integration/api/hooks/paytree/route.ts

@@ -0,0 +1,195 @@
+import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http";
+import { ContainerRegistrationKeys, Modules } from "@medusajs/framework/utils";
+import {
+  processPaymentWorkflow,
+  refundPaymentWorkflow,
+} from "@medusajs/medusa/core-flows";
+
+import {
+  PAYTREE_MODULE,
+  PaytreeClient,
+  PaytreeLogger,
+  callbackOutcome,
+  toSessionStatus,
+  newlyRefundedAmount,
+  fromPaytreeAmount,
+  AuditEvent,
+  DEFAULT_BASE_URL,
+} from "@paytree/medusa-payment-paytree";
+
+/**
+ * Paytree calls this GET endpoint when a payment status changes, substituting
+ * the {payment_intent_id} and {transaction_id} tags in the notification URL.
+ *
+ * The callback body is NOT trusted. We take only the ids and fetch the
+ * authoritative status from Paytree using our secret API key — that lookup is
+ * the trust mechanism (no signature is involved). The handler is idempotent,
+ * so repeated or spoofed pings cause at most a harmless re-read.
+ *
+ * Always returns 200 on a handled event. A non-200 triggers Paytree's retry
+ * schedule, which we reserve for genuine internal failures.
+ */
+export async function GET(
+  req: MedusaRequest,
+  res: MedusaResponse,
+): Promise<void> {
+  const logger = new PaytreeLogger(req.scope);
+  const transactionId = String(req.query.transaction_id ?? "");
+  const paytreeId = String(req.query.payment_intent_id ?? "");
+  const c = { sessionId: transactionId, paytreeId };
+
+  const paytree: any = req.scope.resolve(PAYTREE_MODULE);
+  const query = req.scope.resolve(ContainerRegistrationKeys.QUERY);
+
+  logger.info("callback received", c);
+  await safeAudit(paytree, {
+    event: AuditEvent.WEBHOOK_RECEIVED,
+    session_id: transactionId,
+    paytree_id: paytreeId,
+  });
+
+  if (!transactionId && !paytreeId) {
+    // Nothing to correlate; acknowledge so Paytree doesn't retry forever.
+    res.sendStatus(200);
+    return;
+  }
+
+  try {
+    const settings = await paytree.getSettings({ base_url: DEFAULT_BASE_URL });
+    const apiKey = process.env.PAYTREE_API_KEY || "";
+    const client = new PaytreeClient(
+      {
+        apiKey,
+        baseUrl: settings.base_url || DEFAULT_BASE_URL,
+        logRequest: Boolean(settings.log_request),
+        logResponse: Boolean(settings.log_response),
+      },
+      logger,
+    );
+
+    // Authoritative lookup by our own ref (avoids the create-id vs UUID issue).
+    const intent = transactionId
+      ? await client.findByTransactionRef(transactionId, c)
+      : await client.getPaymentIntent(paytreeId, c);
+
+    if (!intent) {
+      logger.warn("callback intent not found in Paytree", c);
+      res.sendStatus(200);
+      return;
+    }
+
+    const payment = intent.payment?.[0];
+    const status = payment?.status ?? "pending";
+    const sessionId = intent.transaction_ref || transactionId;
+    const outcome = callbackOutcome(status);
+
+    if (outcome.kind === "action") {
+      await processPaymentWorkflow(req.scope).run({
+        input: {
+          action: outcome.action,
+          data: {
+            session_id: sessionId,
+            amount: fromPaytreeAmount(payment?.amount ?? intent.amount),
+          },
+        },
+      });
+    } else if (outcome.kind === "refund") {
+      await reflectRefund(
+        req.scope,
+        query,
+        sessionId,
+        payment?.refunded ?? "0",
+        c,
+        logger,
+      );
+    }
+
+    await safeAudit(paytree, {
+      event: AuditEvent.WEBHOOK_PROCESSED,
+      session_id: sessionId,
+      paytree_id: paytreeId,
+      status,
+      detail: { medusa_status: toSessionStatus(status), outcome: outcome.kind },
+    });
+
+    res.sendStatus(200);
+  } catch (e) {
+    logger.error("callback processing failed", e, c);
+    await safeAudit(paytree, {
+      event: AuditEvent.ERROR,
+      session_id: transactionId,
+      paytree_id: paytreeId,
+      error: e instanceof Error ? e.message : String(e),
+      detail: { phase: AuditEvent.WEBHOOK_PROCESSED },
+    });
+    // Signal failure so Paytree retries the callback.
+    res.sendStatus(500);
+  }
+}
+
+/**
+ * Record an externally-initiated Paytree refund in Medusa. Medusa has no
+ * "refunded" webhook action, so we drive the refund workflow directly. The
+ * workflow calls the provider's refundPayment, which verifies the refund
+ * against Paytree before recording — so this is safe to call idempotently.
+ */
+async function reflectRefund(
+  scope: any,
+  query: any,
+  sessionId: string,
+  paytreeRefundedTotal: string,
+  c: { sessionId?: string; paytreeId?: string },
+  logger: PaytreeLogger,
+): Promise<void> {
+  // Find the Medusa payment + how much is already refunded there.
+  const { data: sessions } = await query.graph({
+    entity: "payment_session",
+    fields: [
+      "id",
+      "payment_collection.payments.id",
+      "payment_collection.payments.amount",
+      "payment_collection.payments.refunds.amount",
+    ],
+    filters: { id: sessionId },
+  });
+
+  const payment = sessions?.[0]?.payment_collection?.payments?.[0];
+  if (!payment) {
+    logger.warn("refund callback: no Medusa payment found for session", c);
+    return;
+  }
+
+  const alreadyRefunded = (payment.refunds ?? []).reduce(
+    (sum: number, r: any) => sum + Number(r.amount ?? 0),
+    0,
+  );
+
+  const delta = newlyRefundedAmount(paytreeRefundedTotal, alreadyRefunded);
+  if (!delta) {
+    logger.info("refund callback: nothing new to record", c);
+    return;
+  }
+
+  await refundPaymentWorkflow(scope).run({
+    input: {
+      payment_id: payment.id,
+      amount: fromPaytreeAmount(delta),
+      note: "Reflected from Paytree back-office refund",
+    },
+  });
+  logger.info(`recorded refund of ${delta}`, c);
+}
+
+async function safeAudit(paytree: any, record: any): Promise<void> {
+  try {
+    await paytree.createPaytreeEventLogs([
+      {
+        id: `ptlog_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
+        ...record,
+        detail: record.detail ?? null,
+      },
+    ]);
+  } catch {
+    // Audit write must never break the callback.
+  }
+}

package/integration/api/store/paytree/methods/route.ts

@@ -0,0 +1,28 @@
+import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http";
+import {
+  PAYTREE_MODULE,
+  DEFAULT_BASE_URL,
+  resolveMethods,
+  type StoredMethodConfig,
+} from "@paytree/medusa-payment-paytree";
+
+/**
+ * Public list of the Paytree payment methods the admin has enabled, with their
+ * (possibly overridden) display labels. The storefront renders this as the
+ * method picker shown after Paytree is selected at checkout. Only enabled
+ * methods are returned, and never any secret/operational config.
+ */
+export async function GET(
+  req: MedusaRequest,
+  res: MedusaResponse,
+): Promise<void> {
+  const paytree: any = req.scope.resolve(PAYTREE_MODULE);
+  const settings = await paytree.getSettings({ base_url: DEFAULT_BASE_URL });
+  const methods = resolveMethods(
+    settings.methods as StoredMethodConfig[] | null,
+  )
+    .filter((m) => m.enabled)
+    .map((m) => ({ method: m.method, label: m.label }));
+
+  res.json({ methods });
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@paytree/medusa-payment-paytree",
+  "version": "0.1.0",
+  "description": "Paytree hosted-payment provider for Medusa 2.0.",
+  "author": "Paytree",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "!dist/**/__tests__",
+    "integration",
+    "storefront",
+    "docs",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "medusa",
+    "medusa-plugin",
+    "medusa-plugin-payment",
+    "payment",
+    "payment-provider",
+    "paytree",
+    "ecommerce"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/paytree/medusa-payment-paytree"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "rimraf dist && tsc --build tsconfig.json",
+    "watch": "tsc --watch",
+    "test": "jest --passWithNoTests src",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "@medusajs/framework": "2.13.6"
+  },
+  "devDependencies": {
+    "@medusajs/framework": "2.13.6",
+    "@mikro-orm/migrations": "6.6.12",
+    "@swc/core": "1.5.7",
+    "@swc/jest": "^0.2.39",
+    "@types/jest": "^29.5.14",
+    "@types/node": "^20.19.25",
+    "jest": "^29.7.0",
+    "rimraf": "^5.0.10",
+    "typescript": "^5.9.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/storefront/README.md

@@ -0,0 +1,25 @@
+# Paytree storefront reference components
+
+Reference Next.js components for the Paytree checkout experience, targeting the
+[Medusa Next.js starter](https://github.com/medusajs/nextjs-starter-medusa)
+layout. These are **copy-paste sources**, not a compiled/importable module — the
+storefront owns its own build, styling, and import aliases.
+
+## Contents
+
+| File | Purpose | Copy to |
+| ---- | ------- | ------- |
+| `lib/paytree.ts` | `listPaytreeMethods()` server action (`GET /store/paytree/methods`). | `src/lib/data/paytree.ts` |
+| `components/paytree-method-icon.tsx` | SVG icons for each method in the picker. | `src/modules/checkout/components/paytree-method-icon/index.tsx` |
+| `components/payment.tsx` | Payment step with the Paytree method picker. | `src/modules/checkout/components/payment/index.tsx` |
+| `components/payment-button.tsx` | Place-order button that redirects to the hosted page. | `src/modules/checkout/components/payment-button/index.tsx` |
+
+## Peer requirements
+
+These components assume the starter's dependencies are present:
+`@medusajs/ui`, `@medusajs/icons`, `@medusajs/types`, `@headlessui/react`,
+`next`, `react`, and the starter's `@lib`/`@modules` path aliases.
+
+See [`../docs/storefront-integration.md`](../docs/storefront-integration.md) for
+the full wiring guide, including the shared-file edits to `constants.tsx` and
+`cart.ts`.