@paytree/medusa-payment-paytree 0.1.0

package/docs/getting-started.md

@@ -0,0 +1,111 @@
+# Getting started
+
+This guide takes you from install to a first successful Paytree payment.
+
+## 1. Prerequisites
+
+- A running Medusa `>= 2.13` backend (and, for the full flow, a Next.js storefront).
+- A Paytree account with an API key.
+- The public URL of your backend (for local dev, a tunnel such as ngrok/cloudflared
+  so Paytree can reach `/hooks/paytree`).
+
+## 2. Install
+
+```bash
+npm install @paytree/medusa-payment-paytree
+```
+
+## 3. Environment
+
+In `backend/.env`:
+
+```bash
+PAYTREE_API_KEY=sk_live_or_test_key
+PAYTREE_BASE_URL=https://api.paytree.tech
+BACKEND_URL=https://<your-public-backend-url>
+```
+
+## 4. Register in `medusa-config.js`
+
+```js
+modules: [
+  // Data module: settings + audit-log tables (owns the migrations).
+  { resolve: "@paytree/medusa-payment-paytree/dist/modules/paytree" },
+  // Payment module with the Paytree provider (the package's default export).
+  {
+    key: Modules.PAYMENT,
+    resolve: "@medusajs/payment",
+    options: {
+      providers: [
+        {
+          resolve: "@paytree/medusa-payment-paytree",
+          id: "paytree",
+          options: {
+            apiKey: process.env.PAYTREE_API_KEY,
+            backendUrl: process.env.BACKEND_URL,
+            baseUrl: process.env.PAYTREE_BASE_URL,
+          },
+        },
+      ],
+    },
+  },
+],
+```
+
+## 5. Copy in the API routes and admin UI
+
+Medusa loads API routes and admin extensions from *your app's* `src/`, so copy
+them from the package's `integration/` folder into your backend:
+
+```bash
+cp -R node_modules/@paytree/medusa-payment-paytree/integration/api/* backend/src/api/
+cp -R node_modules/@paytree/medusa-payment-paytree/integration/admin/* backend/src/admin/
+```
+
+See [`../integration/README.md`](../integration/README.md) for the file map.
+
+## 6. Migrate the database
+
+The data module owns two tables (`paytree_setting`, `paytree_event_log`):
+
+```bash
+npx medusa db:migrate
+```
+
+## 7. Enable Paytree for a region
+
+In the admin: **Settings → Regions → (a region) → Payment providers**, enable
+**Paytree**. This is what makes it appear as an option at checkout.
+
+## 8. Curate methods (optional)
+
+Open the admin **Paytree → Settings** page. `card` is enabled by default. Toggle
+the methods you want to offer and optionally override their labels. Only enabled
+methods are returned by `GET /store/paytree/methods` and shown at checkout.
+
+## 9. Storefront
+
+Wire up the checkout UI using the reference components in
+[`../storefront`](../storefront) — see
+[storefront-integration.md](./storefront-integration.md).
+
+## 10. Make a test payment
+
+1. Add a product to the cart and reach the payment step.
+2. Select **Paytree**, pick a method, and continue.
+3. Click **Pay with Paytree** — you're redirected to the hosted page.
+4. Complete payment; you're redirected back to the return URL and the order is
+   placed.
+5. Check **Paytree → Payments** in the admin: you should see `initiate_payment`,
+   `webhook_received`, and `webhook_processed` events for the session.
+
+## Troubleshooting
+
+- **"Paytree requires the storefront to pass these fields…"** — the payment
+  session data is missing `customer`, `address.country`, or `session`
+  (IP/user-agent). Make sure your storefront assembles these server-side (the
+  reference `initiatePaymentSession` does this).
+- **Callback never arrives** — `BACKEND_URL` must be publicly reachable by
+  Paytree; for local dev use a tunnel and set `BACKEND_URL` to the tunnel URL.
+- **401/403 from Paytree** — check `PAYTREE_API_KEY`. The base URL must be
+  `https` (enforced) so the key is never sent in cleartext.

package/docs/storefront-integration.md

@@ -0,0 +1,85 @@
+# Storefront integration
+
+Paytree is a **hosted-redirect** provider: the storefront collects the method
+choice, the backend creates a payment intent and returns a `payment_link`, and
+the customer is sent to Paytree's hosted page. These reference components target
+the official [Medusa Next.js starter](https://github.com/medusajs/nextjs-starter-medusa)
+layout.
+
+The files live under [`../storefront`](../storefront). Copy each to the matching
+path in your storefront and apply the shared-file edits below.
+
+## Files to add
+
+| Reference file | Destination in the Next.js starter |
+| -------------- | ---------------------------------- |
+| `storefront/lib/paytree.ts` | `src/lib/data/paytree.ts` |
+| `storefront/components/paytree-method-icon.tsx` | `src/modules/checkout/components/paytree-method-icon/index.tsx` |
+| `storefront/components/payment.tsx` | `src/modules/checkout/components/payment/index.tsx` (replaces the starter's) |
+| `storefront/components/payment-button.tsx` | `src/modules/checkout/components/payment-button/index.tsx` (replaces the starter's) |
+
+## Shared files to edit
+
+### 1. `src/lib/constants.tsx`
+
+Register the provider so the picker shows a title/icon and helpers can detect it:
+
+```tsx
+export const paymentInfoMap = {
+  // ...existing entries
+  pp_paytree_paytree: { title: "Paytree", icon: <CreditCard /> },
+}
+
+export const isPaytree = (providerId?: string) =>
+  providerId?.startsWith("pp_paytree")
+```
+
+### 2. `src/lib/data/cart.ts`
+
+Paytree needs the customer, address, and request session (IP + user-agent) in
+the payment session `data`. Assemble it **server-side** in
+`initiatePaymentSession` before calling the SDK:
+
+```ts
+export async function initiatePaymentSession(cart, data) {
+  let payload = data
+  if (data.provider_id.includes("paytree")) {
+    payload = { ...data, data: await buildPaytreeSessionData(cart, data.data) }
+  }
+  return sdk.store.payment.initiatePaymentSession(
+    cart, payload, {}, await getAuthHeaders()
+  ).then((resp) => { revalidateTag("cart"); return resp })
+}
+```
+
+`buildPaytreeSessionData` reads `next/headers` for `x-forwarded-for` /
+`user-agent`, pulls the address/email from the cart, and sets `return_url` /
+`cancel_url`. See the full implementation in the reference `payment.tsx` notes
+and `storefront/lib/paytree.ts`, or copy from the demo's `cart.ts`.
+
+## How the checkout flows
+
+1. **Method step** (`payment.tsx`) — when Paytree is selected it calls
+   `listPaytreeMethods()` (`GET /store/paytree/methods`) and renders a radio list
+   using `PaytreeMethodIcon`. Paytree re-initiates the session on every submit so
+   the freshest method choice produces a fresh `payment_link`.
+2. **Review / place order** (`payment-button.tsx`) — `PaytreePaymentButton` reads
+   `session.data.payment_link` and redirects the browser to it.
+3. **Return** — Paytree redirects to your `return_url`. You need a return page at
+   the path you configured (the reference `buildPaytreeSessionData` uses
+   `/{countryCode}/checkout/paytree-return`). That page should finalize the cart
+   (`placeOrder()`) and show confirmation. Meanwhile the backend `/hooks/paytree`
+   callback reconciles the authoritative status independently, so the order is
+   captured even if the shopper closes the tab before the redirect completes.
+
+## Data loader
+
+`storefront/lib/paytree.ts` exports `listPaytreeMethods()`, a server action that
+fetches enabled methods and returns `[]` on failure so checkout degrades
+gracefully if Paytree isn't configured.
+
+## Notes
+
+- The reference components keep the starter's import aliases (`@lib/...`,
+  `@modules/...`). If your storefront uses different aliases, adjust the imports.
+- The method picker only lists methods enabled in **Paytree → Settings**.

package/integration/README.md

@@ -0,0 +1,46 @@
+# Copy-in integration files
+
+Medusa discovers **API routes** and **admin extensions** from your own app's
+`src/` directory (and bundles the admin with Vite), so these can't be loaded
+from an installed module the way the payment provider and data module are.
+Copy them into your backend once, then they behave like first-party code.
+
+They import the shared helpers (`PAYTREE_MODULE`, `PaytreeClient`,
+`resolveMethods`, etc.) from the installed package
+`@paytree/medusa-payment-paytree`, so no relative paths need fixing.
+
+## File map
+
+| From (this package) | To (your backend) |
+| ------------------- | ----------------- |
+| `integration/api/hooks/paytree/route.ts` | `src/api/hooks/paytree/route.ts` |
+| `integration/api/store/paytree/methods/route.ts` | `src/api/store/paytree/methods/route.ts` |
+| `integration/api/admin/paytree/settings/route.ts` | `src/api/admin/paytree/settings/route.ts` |
+| `integration/api/admin/paytree/events/route.ts` | `src/api/admin/paytree/events/route.ts` |
+| `integration/admin/routes/paytree/**` | `src/admin/routes/paytree/**` |
+
+## Quick copy
+
+```bash
+cp -R node_modules/@paytree/medusa-payment-paytree/integration/api/*   backend/src/api/
+cp -R node_modules/@paytree/medusa-payment-paytree/integration/admin/* backend/src/admin/
+```
+
+## What each piece does
+
+- **`api/hooks/paytree`** — the GET callback Paytree calls when a payment status
+  changes. It re-fetches the authoritative status and drives the payment/refund
+  workflows. This is the live reconciliation path; without it, payments won't
+  finalize server-side.
+- **`api/store/paytree/methods`** — public list of admin-enabled methods for the
+  storefront picker.
+- **`api/admin/paytree/settings` + `events`** — admin settings read/write and the
+  audit-log query.
+- **`admin/routes/paytree`** — the "Paytree" admin dashboard pages.
+
+## Requirements
+
+The admin pages use `@medusajs/ui`, `@medusajs/icons`, and `react-router-dom`,
+which a standard Medusa backend already provides. The routes require the data
+module to be registered (see the main README) so `req.scope.resolve("paytree")`
+works.

package/integration/admin/routes/paytree/api.ts

@@ -0,0 +1,16 @@
+/**
+ * Small fetch helper shared by the Paytree admin pages. Calls the admin API
+ * under /admin/paytree and surfaces a useful error message on failure.
+ */
+export async function api(path: string, init?: RequestInit) {
+  const res = await fetch(`/admin/paytree/${path}`, {
+    credentials: "include",
+    headers: { "Content-Type": "application/json" },
+    ...init,
+  })
+  if (!res.ok) {
+    const detail = await res.json().catch(() => ({}))
+    throw new Error(detail?.message || `Request failed (${res.status})`)
+  }
+  return res.json()
+}

package/integration/admin/routes/paytree/method-icons.tsx

@@ -0,0 +1,106 @@
+import React from "react"
+
+/**
+ * Compact SVG icons for each Paytree method, shown in the admin methods list
+ * and intended to mirror what the storefront renders. Generic rails (card,
+ * bank transfer, crypto) use line glyphs; brand methods use a colored badge
+ * with a short brand mark so the set stays consistent and recognizable.
+ */
+
+type Badge = { bg: string; fg: string; text: string; size?: number }
+
+const BADGES: Record<string, Badge> = {
+  paypal: { bg: "#003087", fg: "#ffffff", text: "PP" },
+  klarna: { bg: "#FFB3C7", fg: "#0A0A0A", text: "K." },
+  ideal: { bg: "#CD0067", fg: "#ffffff", text: "iD" },
+  bancontact: { bg: "#005498", fg: "#FFD800", text: "BC" },
+  trustly: { bg: "#0EE06E", fg: "#0A0A0A", text: "T" },
+  kakaopay: { bg: "#FFCD00", fg: "#3C1E1E", text: "pay", size: 7 },
+  p24: { bg: "#D3132B", fg: "#ffffff", text: "P24", size: 7 },
+  blik: { bg: "#000000", fg: "#E61E2A", text: "blik", size: 6 },
+}
+
+const BadgeIcon = ({ bg, fg, text, size = 9 }: Badge) => (
+  <svg width="24" height="24" viewBox="0 0 24 24" aria-hidden="true">
+    <rect x="1" y="4" width="22" height="16" rx="3" fill={bg} />
+    <text
+      x="12"
+      y="12.5"
+      fill={fg}
+      fontSize={size}
+      fontWeight="700"
+      fontFamily="Inter, system-ui, sans-serif"
+      textAnchor="middle"
+      dominantBaseline="central"
+    >
+      {text}
+    </text>
+  </svg>
+)
+
+const CardIcon = () => (
+  <svg width="24" height="24" viewBox="0 0 24 24" fill="none" aria-hidden="true">
+    <rect
+      x="2"
+      y="5"
+      width="20"
+      height="14"
+      rx="2.5"
+      stroke="currentColor"
+      strokeWidth="1.6"
+    />
+    <path d="M2 9.5h20" stroke="currentColor" strokeWidth="1.6" />
+    <path
+      d="M5.5 15.5h4"
+      stroke="currentColor"
+      strokeWidth="1.6"
+      strokeLinecap="round"
+    />
+  </svg>
+)
+
+const BankIcon = () => (
+  <svg width="24" height="24" viewBox="0 0 24 24" fill="none" aria-hidden="true">
+    <path
+      d="M12 3 3 7.5h18L12 3Z"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinejoin="round"
+    />
+    <path
+      d="M5 10v6M9.3 10v6M14.7 10v6M19 10v6M3 19.5h18"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+    />
+  </svg>
+)
+
+const CryptoIcon = () => (
+  <svg width="24" height="24" viewBox="0 0 24 24" aria-hidden="true">
+    <circle cx="12" cy="12" r="9.2" fill="#F7931A" />
+    <text
+      x="12"
+      y="12.5"
+      fill="#ffffff"
+      fontSize="11"
+      fontWeight="700"
+      fontFamily="Inter, system-ui, sans-serif"
+      textAnchor="middle"
+      dominantBaseline="central"
+    >
+      ₿
+    </text>
+  </svg>
+)
+
+export const MethodIcon = ({ method }: { method: string }) => {
+  if (method === "card") return <CardIcon />
+  if (method === "wire") return <BankIcon />
+  if (method === "crypto") return <CryptoIcon />
+  const badge = BADGES[method]
+  if (badge) return <BadgeIcon {...badge} />
+  return <CardIcon />
+}
+
+export default MethodIcon

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

@@ -0,0 +1,18 @@
+import { defineRouteConfig } from "@medusajs/admin-sdk"
+import { CreditCard } from "@medusajs/icons"
+import { Navigate } from "react-router-dom"
+
+/**
+ * The "Paytree" sidebar group. Its children — Payments and Settings — are the
+ * real pages; landing on the group itself sends you to Payments.
+ */
+const PaytreePage = () => {
+  return <Navigate to="/paytree/payments" replace />
+}
+
+export const config = defineRouteConfig({
+  label: "Paytree",
+  icon: CreditCard,
+})
+
+export default PaytreePage

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

@@ -0,0 +1,240 @@
+import { defineRouteConfig } from "@medusajs/admin-sdk"
+import { CurrencyDollar, TriangleRightMini, TriangleDownMini } from "@medusajs/icons"
+import { Badge, Button, Container, Heading, Input, Table, Text, toast } from "@medusajs/ui"
+import { Fragment, useEffect, useState } from "react"
+import { api } from "../api"
+
+type EventRow = {
+  id: string
+  event: string
+  session_id: string | null
+  paytree_id: string | null
+  status: string | null
+  amount: string | null
+  currency: string | null
+  error: string | null
+  detail: Record<string, unknown> | null
+  created_at: string
+}
+
+/** Pretty-print a JSON-ish value; detail may arrive as an object or a string. */
+function formatDetail(value: unknown): string {
+  if (value == null) {
+    return ""
+  }
+  if (typeof value === "string") {
+    try {
+      return JSON.stringify(JSON.parse(value), null, 2)
+    } catch {
+      return value
+    }
+  }
+  return JSON.stringify(value, null, 2)
+}
+
+const STATUS_COLOR: Record<string, "green" | "red" | "orange" | "grey"> = {
+  success: "green",
+  authorized: "green",
+  captured: "green",
+  refunded: "orange",
+  partial_refunded: "orange",
+  failed: "red",
+  canceled: "red",
+  expired: "red",
+  pending: "grey",
+}
+
+const PaymentsPage = () => {
+  const [events, setEvents] = useState<EventRow[]>([])
+  const [count, setCount] = useState(0)
+  const [offset, setOffset] = useState(0)
+  const [sessionFilter, setSessionFilter] = useState("")
+  const [loading, setLoading] = useState(true)
+  const [expandedId, setExpandedId] = useState<string | null>(null)
+  const limit = 20
+
+  const toggleExpanded = (id: string) =>
+    setExpandedId((current) => (current === id ? null : id))
+
+  const load = (nextOffset = 0, session = sessionFilter) => {
+    setLoading(true)
+    const params = new URLSearchParams({
+      limit: String(limit),
+      offset: String(nextOffset),
+    })
+    if (session) {
+      params.set("session_id", session)
+    }
+    api(`events?${params.toString()}`)
+      .then((d) => {
+        setEvents(d.events)
+        setCount(d.count)
+        setOffset(nextOffset)
+      })
+      .catch((e) => toast.error(e.message))
+      .finally(() => setLoading(false))
+  }
+
+  useEffect(() => {
+    load(0)
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [])
+
+  return (
+    <Container className="divide-y p-0">
+      <div className="flex items-center justify-between px-6 py-4">
+        <Heading level="h2">Payment activity</Heading>
+        <div className="flex gap-2">
+          <Input
+            placeholder="Filter by session id"
+            value={sessionFilter}
+            onChange={(e) => setSessionFilter(e.target.value)}
+          />
+          <Button variant="secondary" onClick={() => load(0)}>
+            Search
+          </Button>
+        </div>
+      </div>
+
+      <div className="px-6 py-2">
+        <Table>
+          <Table.Header>
+            <Table.Row>
+              <Table.HeaderCell className="w-8" />
+              <Table.HeaderCell>When</Table.HeaderCell>
+              <Table.HeaderCell>Event</Table.HeaderCell>
+              <Table.HeaderCell>Status</Table.HeaderCell>
+              <Table.HeaderCell>Amount</Table.HeaderCell>
+              <Table.HeaderCell>Session</Table.HeaderCell>
+            </Table.Row>
+          </Table.Header>
+          <Table.Body>
+            {events.map((row) => {
+              const hasDetails = Boolean(
+                row.error ||
+                  (row.detail && Object.keys(row.detail).length > 0)
+              )
+              const expanded = expandedId === row.id
+
+              return (
+                <Fragment key={row.id}>
+                  <Table.Row
+                    className={hasDetails ? "cursor-pointer" : undefined}
+                    onClick={
+                      hasDetails ? () => toggleExpanded(row.id) : undefined
+                    }
+                  >
+                    <Table.Cell className="w-8 text-ui-fg-muted">
+                      {hasDetails ? (
+                        expanded ? (
+                          <TriangleDownMini />
+                        ) : (
+                          <TriangleRightMini />
+                        )
+                      ) : null}
+                    </Table.Cell>
+                    <Table.Cell>
+                      {new Date(row.created_at).toLocaleString()}
+                    </Table.Cell>
+                    <Table.Cell>{row.event}</Table.Cell>
+                    <Table.Cell>
+                      {row.status ? (
+                        <Badge
+                          size="2xsmall"
+                          color={STATUS_COLOR[row.status] ?? "grey"}
+                        >
+                          {row.status}
+                        </Badge>
+                      ) : row.error ? (
+                        <Badge size="2xsmall" color="red">
+                          error
+                        </Badge>
+                      ) : (
+                        "—"
+                      )}
+                    </Table.Cell>
+                    <Table.Cell>
+                      {row.amount
+                        ? `${row.amount} ${row.currency ?? ""}`.trim()
+                        : "—"}
+                    </Table.Cell>
+                    <Table.Cell className="font-mono text-xs">
+                      {row.session_id ?? "—"}
+                    </Table.Cell>
+                  </Table.Row>
+
+                  {expanded && (
+                    <Table.Row className="bg-ui-bg-subtle hover:bg-ui-bg-subtle">
+                      <Table.Cell colSpan={6}>
+                        <div className="flex flex-col gap-3 py-2">
+                          {row.error && (
+                            <div className="flex flex-col gap-1">
+                              <Text
+                                size="small"
+                                weight="plus"
+                                className="text-ui-fg-error"
+                              >
+                                Error
+                              </Text>
+                              <pre className="whitespace-pre-wrap break-all rounded-md border border-ui-border-base bg-ui-bg-base p-3 text-xs">
+                                {row.error}
+                              </pre>
+                            </div>
+                          )}
+                          {row.detail &&
+                            Object.keys(row.detail).length > 0 && (
+                              <div className="flex flex-col gap-1">
+                                <Text
+                                  size="small"
+                                  weight="plus"
+                                  className="text-ui-fg-subtle"
+                                >
+                                  Request &amp; response
+                                </Text>
+                                <pre className="max-h-96 overflow-auto whitespace-pre-wrap break-all rounded-md border border-ui-border-base bg-ui-bg-base p-3 text-xs">
+                                  {formatDetail(row.detail)}
+                                </pre>
+                              </div>
+                            )}
+                        </div>
+                      </Table.Cell>
+                    </Table.Row>
+                  )}
+                </Fragment>
+              )
+            })}
+          </Table.Body>
+        </Table>
+      </div>
+
+      <div className="flex items-center justify-between px-6 py-4">
+        <Text size="small" className="text-ui-fg-subtle">
+          {count} event{count === 1 ? "" : "s"}
+        </Text>
+        <div className="flex gap-2">
+          <Button
+            variant="secondary"
+            disabled={offset === 0 || loading}
+            onClick={() => load(Math.max(0, offset - limit))}
+          >
+            Previous
+          </Button>
+          <Button
+            variant="secondary"
+            disabled={offset + limit >= count || loading}
+            onClick={() => load(offset + limit)}
+          >
+            Next
+          </Button>
+        </div>
+      </div>
+    </Container>
+  )
+}
+
+export const config = defineRouteConfig({
+  label: "Payments",
+  icon: CurrencyDollar,
+})
+
+export default PaymentsPage