@easypayment/medusa-payment-paypal 0.7.4

package/README.md

@@ -0,0 +1,172 @@
+# PayPal for Medusa
+
+**Accept PayPal and advanced credit card payments in your Medusa v2 store — built by an official PayPal Partner.**
+
+[![npm version](https://img.shields.io/npm/v/@easypayment/medusa-paypal?color=blue&label=npm)](https://www.npmjs.com/package/@easypayment/medusa-paypal)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![Medusa v2](https://img.shields.io/badge/Medusa-v2-9b59b6)](https://medusajs.com)
+[![PayPal PPCP](https://img.shields.io/badge/PayPal-PPCP-003087)](https://developer.paypal.com)
+
+---
+
+## 📋 Table of Contents
+
+- [📦 What's included](#-whats-included)
+- [✅ Requirements](#-requirements)
+- [🚀 Installation](#-installation)
+- [⚙️ Setup](#%EF%B8%8F-setup)
+  - [Step 1 — Configure medusa-config.ts](#step-1--configure-medusa-configts)
+  - [Step 2 — Run database migrations](#step-2--run-database-migrations)
+  - [Step 3 — Connect your PayPal account](#step-3--connect-your-paypal-account)
+  - [Step 4 — Enable providers in your region](#step-4--enable-providers-in-your-region)
+  - [Step 5 — Configure settings](#step-5--configure-settings-optional)
+  - [Step 6 — Add PayPal to your storefront](#step-6--add-paypal-to-your-storefront)
+- [📄 License](#-license)
+
+---
+
+## 📦 What's included
+
+| Feature | Details |
+|---|---|
+| 🔵 **PayPal Smart Buttons** | One-click wallet checkout via PayPal |
+| 💳 **Advanced Card Fields** | Hosted, PCI-compliant advanced credit card inputs |
+| 🛠 **Admin Dashboard** | Connect, configure, and switch environments from Medusa Admin |
+| 🌍 **Sandbox & Live** | Toggle between test and production without restarting |
+| ⚡ **Webhooks** | Automatically registered and verified with built-in retry support |
+| 🔐 **3D Secure** | Configurable SCA/3DS per transaction |
+
+---
+
+## ✅ Requirements
+
+- Medusa **v2**
+- Node.js **18+**
+- PostgreSQL
+
+---
+
+## 🚀 Installation
+
+**In your Medusa backend directory**, run:
+
+```bash
+npm install @easypayment/medusa-paypal
+```
+
+---
+
+## ⚙️ Setup
+
+### Step 1 — Configure `medusa-config.ts`
+
+Add the plugin and both payment providers to your existing `medusa-config.ts`:
+
+```ts
+import { loadEnv, defineConfig } from "@medusajs/framework/utils"
+
+loadEnv(process.env.NODE_ENV || "development", process.cwd())
+
+export default defineConfig({
+  projectConfig: {
+    databaseUrl: process.env.DATABASE_URL,
+    http: {
+      storeCors: process.env.STORE_CORS!,
+      adminCors: process.env.ADMIN_CORS!,
+      authCors: process.env.AUTH_CORS!,
+      jwtSecret: process.env.JWT_SECRET || "supersecret",
+      cookieSecret: process.env.COOKIE_SECRET || "supersecret",
+    },
+  },
+
+  plugins: [
+    {
+      resolve: "@easypayment/medusa-paypal",
+      options: {},
+    },
+  ],
+
+  modules: [
+    {
+      resolve: "@medusajs/medusa/payment",
+      options: {
+        providers: [
+          {
+            // PayPal Smart Buttons (wallet checkout)
+            resolve: "@easypayment/medusa-paypal/providers/paypal",
+            id: "paypal",
+            options: {},
+            dependencies: ["paypal_onboarding"],
+          },
+          {
+            // Advanced Card Fields (hosted card inputs)
+            resolve: "@easypayment/medusa-paypal/providers/paypal_card",
+            id: "paypal_card",
+            options: {},
+            dependencies: ["paypal_onboarding"],
+          },
+        ],
+      },
+    },
+  ],
+})
+```
+
+---
+
+### Step 2 — Run database migrations
+
+```bash
+npx medusa db:migrate
+```
+
+---
+
+### Step 3 — Connect your PayPal account
+
+1. Start your Medusa server
+2. Open **Medusa Admin → Settings → PayPal → PayPal Connection**
+3. Choose **Sandbox** (testing) or **Live** (production)
+4. Click **Connect to PayPal** and complete the onboarding flow
+
+Credentials are saved automatically. Prefer manual setup? Click **Insert credentials manually** and paste your Client ID and Secret from [developer.paypal.com](https://developer.paypal.com/dashboard/).
+
+---
+
+### Step 4 — Enable providers in your region
+
+1. Go to **Medusa Admin → Settings → Regions → [your region]**
+2. Under **Payment Providers**, enable:
+
+| Provider ID | Description |
+|---|---|
+| `pp_paypal_paypal` | PayPal Smart Buttons (wallet) |
+| `pp_paypal_card_paypal_card` | Advanced Card Fields (card) |
+
+---
+
+### Step 5 — Configure settings *(optional)*
+
+All settings live in **Medusa Admin → Settings → PayPal** and apply immediately — no server restart needed.
+
+| Tab | What you can configure |
+|---|---|
+| **PayPal Settings** | Enable/disable, button color, shape, label |
+| **Advanced Card Payments** | Enable/disable, 3D Secure mode |
+| **Additional Settings** | Payment action (capture / authorize), brand name, invoice prefix |
+
+---
+
+### Step 6 — Add PayPal to your storefront
+
+The checkout UI is shipped as a separate package — **install it inside your storefront project**, not in this backend.
+
+📦 **[@easypayment/medusa-paypal-ui](https://www.npmjs.com/package/@easypayment/medusa-paypal-ui)** — React components, hooks, and a drop-in payment step adapter for Next.js App Router storefronts.
+
+See the [storefront integration & testing guide →](https://www.npmjs.com/package/@easypayment/medusa-paypal-ui)
+
+---
+
+## 📄 License
+
+MIT © [Easy Payment](https://www.npmjs.com/package/@easypayment/medusa-paypal)

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "@easypayment/medusa-payment-paypal",
+  "version": "0.7.4",
+  "description": "PayPal integration for Medusa v2",
+  "author": "EasyPayment Plugins",
+  "license": "MIT",
+  "main": "./.medusa/server/src/index.js",
+  "types": "./.medusa/server/src/index.d.ts",
+  "files": [
+    ".medusa/server",
+    "src",
+    "scripts",
+    "package.json",
+    "README.md",
+    "LICENSE",
+    "tsconfig.json"
+  ],
+  "exports": {
+    "./package.json": "./package.json",
+    "./admin": "./.medusa/server/src/admin/index.mjs",
+    "./workflows": "./.medusa/server/src/workflows/index.js",
+    "./providers/paypal": "./.medusa/server/src/providers/paypal/index.js",
+    "./providers/paypal_card": "./.medusa/server/src/providers/paypal_card/index.js",
+    "./modules/paypal": "./.medusa/server/src/modules/paypal/index.js",
+    ".": "./.medusa/server/src/index.js",
+    "./.medusa/server/src/modules/*": "./.medusa/server/src/modules/*/index.js",
+    "./.medusa/server/src/modules/paypal": "./.medusa/server/src/modules/paypal/index.js",
+    "./.medusa/server/src/providers/*": "./.medusa/server/src/providers/*/index.js",
+    "./.medusa/server/src/providers/paypal": "./.medusa/server/src/providers/paypal/index.js",
+    "./.medusa/server/src/providers/paypal_card": "./.medusa/server/src/providers/paypal_card/index.js",
+    "./.medusa/server/src/admin": "./.medusa/server/src/admin/index.mjs",
+    "./.medusa/server/src/workflows": "./.medusa/server/src/workflows/index.js",
+    "./.medusa/server/src/*": "./.medusa/server/src/*.js",
+    "./.medusa/*": "./.medusa/*"
+  },
+  "scripts": {
+    "build": "medusa plugin:build",
+    "develop": "medusa plugin:develop",
+    "prepare": "npm run build"
+  },
+  "devDependencies": {
+    "@medusajs/admin-sdk": "2.12.5",
+    "@medusajs/cli": "2.12.5",
+    "@medusajs/framework": "2.12.5",
+    "@medusajs/medusa": "2.12.5",
+    "@medusajs/test-utils": "2.12.5",
+    "@medusajs/ui": "^4.0.0",
+    "@medusajs/icons": "2.12.5",
+    "@swc/core": "^1.5.7",
+    "typescript": "^5.6.2"
+  },
+  "peerDependencies": {
+    "@medusajs/admin-sdk": "^2.12.0",
+    "@medusajs/framework": "^2.12.0",
+    "@medusajs/medusa": "^2.12.0",
+    "@medusajs/ui": "^4.0.0",
+    "@medusajs/icons": "^2.12.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/easypayment/medusa-paypal.git"
+  },
+  "keywords": [
+    "medusa",
+    "medusa-v2",
+    "medusa-plugin",
+    "medusa-plugin-integration",
+    "medusa-plugin-payment",
+    "medusa-paypal-payment",
+    "medusa-paypal-plugin",
+    "medusa-paypal-integration",
+    "medusa-paypal"
+  ]
+}

package/src/admin/index.ts

@@ -0,0 +1,7 @@
+import { definePlugin } from "@medusajs/admin-sdk"
+import paypalRoute from "./routes/settings/paypal/page"
+
+export default definePlugin({
+  id: "paypal-backend",
+  routes: [paypalRoute],
+})

package/src/admin/routes/settings/paypal/_components/Tabs.tsx

@@ -0,0 +1,48 @@
+import React from "react"
+import { Link, useLocation } from "react-router-dom"
+
+type Tab = {
+  label: string
+  to: string
+}
+
+const BASE = "/settings/paypal"
+
+const TABS: Tab[] = [
+  { label: "PayPal Connection", to: `${BASE}/connection` },
+  { label: "PayPal Settings", to: `${BASE}/paypal-settings` },
+  { label: "Advanced Card Payments", to: `${BASE}/advanced-card-payments` },
+  { label: "Additional Settings", to: `${BASE}/additional-settings` },
+]
+
+function isActive(pathname: string, to: string) {
+  return pathname === to || pathname.startsWith(to + "/")
+}
+
+export default function PayPalTabs() {
+  const { pathname } = useLocation()
+
+  return (
+    <div className="border-b border-ui-border-base">
+      <div className="flex flex-wrap gap-6 text-sm">
+        {TABS.map((t) => {
+          const active = isActive(pathname, t.to)
+
+          return (
+            <Link
+              key={t.to}
+              to={t.to}
+              className={
+                active
+                  ? "border-b-2 border-ui-fg-base pb-2 font-medium text-ui-fg-base"
+                  : "pb-2 text-ui-fg-subtle hover:text-ui-fg-base"
+              }
+            >
+              {t.label}
+            </Link>
+          )
+        })}
+      </div>
+    </div>
+  )
+}

package/src/admin/routes/settings/paypal/_components/Toast.tsx

@@ -0,0 +1,51 @@
+import React, { useEffect } from "react"
+
+export type ToastKind = "success" | "error"
+
+export type ToastState = {
+  kind: ToastKind
+  message: string
+} | null
+
+type Props = {
+  toast: ToastState
+  onClose: () => void
+}
+
+export default function Toast({ toast, onClose }: Props) {
+  useEffect(() => {
+    if (!toast) return
+    const t = setTimeout(() => onClose(), 2500)
+    return () => clearTimeout(t)
+  }, [toast, onClose])
+
+  if (!toast) return null
+
+  const isSuccess = toast.kind === "success"
+
+  return (
+    <div className="fixed right-6 top-6 z-[9999]">
+      <div
+        className={[
+          "min-w-[280px] max-w-[420px] rounded-lg border px-4 py-3 shadow-md",
+          isSuccess ? "border-emerald-500/30 bg-emerald-500/10" : "border-rose-500/30 bg-rose-500/10",
+        ].join(" ")}
+        role="status"
+        aria-live="polite"
+      >
+        <div className="flex items-start gap-3">
+          <div className={["mt-0.5 h-2.5 w-2.5 rounded-full", isSuccess ? "bg-emerald-500" : "bg-rose-500"].join(" ")} />
+          <div className="flex-1 text-sm text-ui-fg-base">{toast.message}</div>
+          <button
+            type="button"
+            onClick={onClose}
+            className="text-ui-fg-subtle hover:text-ui-fg-base"
+            aria-label="Close"
+          >
+            ×
+          </button>
+        </div>
+      </div>
+    </div>
+  )
+}

package/src/admin/routes/settings/paypal/additional-settings/page.tsx

@@ -0,0 +1,199 @@
+import React, { useEffect, useRef, useState } from "react"
+import PayPalTabs from "../_components/Tabs"
+
+type AdminFetchOptions = {
+  method?: "GET" | "POST" | "PUT" | "DELETE" | "PATCH"
+  body?: Record<string, unknown>
+  query?: Record<string, string>
+}
+
+async function adminFetch<T = unknown>(path: string, opts: AdminFetchOptions = {}): Promise<T> {
+  const { method = "GET", body, query } = opts
+  let url = path
+  if (query && Object.keys(query).length > 0) {
+    const params = new URLSearchParams(query)
+    url = `${path}?${params.toString()}`
+  }
+  const headers: Record<string, string> = { Accept: "application/json" }
+  if (body !== undefined) headers["Content-Type"] = "application/json"
+  if (typeof window !== "undefined") {
+    const token = (window as any).__medusa__?.token
+    if (token) headers["Authorization"] = `Bearer ${token}`
+  }
+  const res = await fetch(url, {
+    method, headers, credentials: "include",
+    body: body !== undefined ? JSON.stringify(body) : undefined,
+  })
+  const text = await res.text().catch(() => "")
+  if (!res.ok) {
+    if (res.status === 401) throw new Error("Unauthorized (401) - session may have expired. Please reload and log in again.")
+    if (res.status === 403) throw new Error("Forbidden (403) - you do not have permission to perform this action.")
+    throw new Error(text || `Request failed with status ${res.status}`)
+  }
+  if (!text) return {} as T
+  try { return JSON.parse(text) as T } catch { return {} as T }
+}
+
+type PaymentAction = "capture" | "authorize"
+type LandingPage = "no_preference" | "login" | "billing"
+
+type AdditionalSettingsForm = {
+  paymentAction: PaymentAction
+  brandName: string
+  landingPage: LandingPage
+  requireInstantPayment: boolean
+  sendItemDetails: boolean
+  invoicePrefix: string
+  creditCardStatementName: string
+}
+
+const DEFAULT_FORM: AdditionalSettingsForm = {
+  paymentAction: "capture",
+  brandName: "PayPal",
+  landingPage: "no_preference",
+  requireInstantPayment: false,
+  sendItemDetails: true,
+  invoicePrefix: "WC-",
+  creditCardStatementName: "PayPal",
+}
+
+function mergeWithDefaults(saved?: Partial<AdditionalSettingsForm> | null) {
+  if (!saved) return { ...DEFAULT_FORM }
+  const entries = Object.entries(saved).filter(([, value]) => value !== undefined)
+  return { ...DEFAULT_FORM, ...(Object.fromEntries(entries) as Partial<AdditionalSettingsForm>) }
+}
+
+function SectionCard({ title, description, right, children }: { title: string; description?: React.ReactNode; right?: React.ReactNode; children: React.ReactNode }) {
+  return (
+    <div className="rounded-xl border border-ui-border-base bg-ui-bg-base shadow-sm">
+      <div className="flex items-start justify-between gap-4 border-b border-ui-border-base p-4">
+        <div>
+          <div className="text-base font-semibold text-ui-fg-base">{title}</div>
+          {description ? <div className="mt-1 text-sm text-ui-fg-subtle">{description}</div> : null}
+        </div>
+        {right}
+      </div>
+      <div className="p-4">{children}</div>
+    </div>
+  )
+}
+
+function FieldRow({ label, hint, children }: { label: string; hint?: React.ReactNode; children: React.ReactNode }) {
+  return (
+    <div className="grid grid-cols-12 items-start gap-4 py-3">
+      <div className="col-span-12 md:col-span-4">
+        <div className="text-sm font-medium text-ui-fg-base">{label}</div>
+        {hint ? <div className="mt-1 text-xs text-ui-fg-subtle">{hint}</div> : null}
+      </div>
+      <div className="col-span-12 md:col-span-8">{children}</div>
+    </div>
+  )
+}
+
+export default function AdditionalSettingsTab() {
+  const [form, setForm] = useState<AdditionalSettingsForm>(() => ({ ...DEFAULT_FORM }))
+  const [loading, setLoading] = useState(false)
+  const [saving, setSaving] = useState(false)
+  const [toast, setToast] = useState<{ type: "success" | "error"; message: string } | null>(null)
+  const didInit = useRef(false)
+
+  useEffect(() => {
+    if (didInit.current) return
+    didInit.current = true
+    ;(async () => {
+      try {
+        setLoading(true)
+        const json = await adminFetch<any>("/admin/paypal/settings")
+        const payload = json?.data ?? json
+        const saved = payload?.additional_settings
+        if (saved && typeof saved === "object") setForm(mergeWithDefaults(saved))
+      } catch {
+      } finally {
+        setLoading(false)
+      }
+    })()
+  }, [])
+
+  async function onSave() {
+    try {
+      setSaving(true)
+      setToast(null)
+      const json = await adminFetch<any>("/admin/paypal/settings", { method: "POST", body: { additional_settings: form as unknown as Record<string, unknown> } })
+      const payload = json?.data ?? json
+      const saved = payload?.additional_settings
+      if (saved && typeof saved === "object") setForm(mergeWithDefaults(saved))
+      setToast({ type: "success", message: "Settings saved" })
+      window.setTimeout(() => setToast(null), 2500)
+    } catch (e: unknown) {
+      setToast({ type: "error", message: e instanceof Error ? e.message : "Failed to save settings" })
+      window.setTimeout(() => setToast(null), 3500)
+    } finally {
+      setSaving(false)
+    }
+  }
+
+  return (
+    <div className="p-6">
+      <div className="flex flex-col gap-6">
+        <div className="flex items-start justify-between gap-4">
+          <div><h1 className="text-xl font-semibold text-ui-fg-base">PayPal Gateway By Easy Payment</h1></div>
+        </div>
+        <PayPalTabs />
+        {toast ? (
+          <div className="fixed right-6 top-6 z-50 rounded-md border border-ui-border-base bg-ui-bg-base px-4 py-3 text-sm shadow-lg" role="status" aria-live="polite">
+            <span className={toast.type === "success" ? "text-ui-fg-base" : "text-ui-fg-error"}>{toast.message}</span>
+          </div>
+        ) : null}
+        <SectionCard
+          title="Additional Settings"
+          description="These settings control checkout behavior and PayPal experience."
+          right={(
+            <div className="flex items-center gap-3">
+              <button type="button" onClick={onSave} disabled={saving || loading} className="transition-fg relative inline-flex w-fit items-center justify-center overflow-hidden rounded-md outline-none shadow-buttons-neutral text-ui-fg-base bg-ui-button-neutral after:transition-fg after:absolute after:inset-0 after:content-[''] after:button-neutral-gradient hover:bg-ui-button-neutral-hover hover:after:button-neutral-hover-gradient active:bg-ui-button-neutral-pressed active:after:button-neutral-pressed-gradient focus-visible:shadow-buttons-neutral-focus disabled:bg-ui-bg-disabled disabled:border-ui-border-base disabled:text-ui-fg-disabled disabled:shadow-buttons-neutral disabled:after:hidden txt-compact-small-plus px-3 py-1.5">
+                {saving ? "Saving..." : "Save settings"}
+              </button>
+              {loading ? <span className="text-sm text-ui-fg-subtle">Loading...</span> : null}
+            </div>
+          )}
+        >
+          <div className="divide-y divide-ui-border-base">
+            <FieldRow label="Payment action">
+              <select value={form.paymentAction} onChange={(e) => setForm((p) => ({ ...p, paymentAction: e.target.value as PaymentAction }))} className="w-full rounded-md border border-ui-border-base bg-ui-bg-base px-3 py-2 text-sm text-ui-fg-base outline-none focus:ring-2 focus:ring-ui-border-interactive">
+                <option value="capture">Capture</option>
+                <option value="authorize">Authorize</option>
+              </select>
+            </FieldRow>
+            <FieldRow label="Brand Name">
+              <input value={form.brandName} onChange={(e) => setForm((p) => ({ ...p, brandName: e.target.value }))} className="w-full rounded-md border border-ui-border-base bg-ui-bg-base px-3 py-2 text-sm text-ui-fg-base outline-none focus:ring-2 focus:ring-ui-border-interactive" placeholder="PayPal" />
+            </FieldRow>
+            <FieldRow label="Landing Page">
+              <select value={form.landingPage} onChange={(e) => setForm((p) => ({ ...p, landingPage: e.target.value as LandingPage }))} className="w-full rounded-md border border-ui-border-base bg-ui-bg-base px-3 py-2 text-sm text-ui-fg-base outline-none focus:ring-2 focus:ring-ui-border-interactive">
+                <option value="no_preference">No Preference</option>
+                <option value="login">Login</option>
+                <option value="billing">Billing</option>
+              </select>
+            </FieldRow>
+            <FieldRow label="Instant Payments">
+              <label className="inline-flex items-center gap-2">
+                <input type="checkbox" checked={form.requireInstantPayment} onChange={(e) => setForm((p) => ({ ...p, requireInstantPayment: e.target.checked }))} className="h-4 w-4 rounded border-ui-border-base" />
+                <span className="text-sm text-ui-fg-base">Require Instant Payment</span>
+              </label>
+            </FieldRow>
+            <FieldRow label="Send Item Details" hint="Include all line item details in the payment request to PayPal so that they can be seen from the PayPal transaction details page.">
+              <label className="inline-flex items-center gap-2">
+                <input type="checkbox" checked={form.sendItemDetails} onChange={(e) => setForm((p) => ({ ...p, sendItemDetails: e.target.checked }))} className="h-4 w-4 rounded border-ui-border-base" />
+                <span className="text-sm text-ui-fg-base">Send line item details to PayPal</span>
+              </label>
+            </FieldRow>
+            <FieldRow label="Invoice prefix">
+              <input value={form.invoicePrefix} onChange={(e) => setForm((p) => ({ ...p, invoicePrefix: e.target.value }))} className="w-full rounded-md border border-ui-border-base bg-ui-bg-base px-3 py-2 text-sm text-ui-fg-base outline-none focus:ring-2 focus:ring-ui-border-interactive" placeholder="WC-" />
+            </FieldRow>
+            <FieldRow label="Credit Card Statement Name">
+              <input value={form.creditCardStatementName} onChange={(e) => setForm((p) => ({ ...p, creditCardStatementName: e.target.value }))} className="w-full rounded-md border border-ui-border-base bg-ui-bg-base px-3 py-2 text-sm text-ui-fg-base outline-none focus:ring-2 focus:ring-ui-border-interactive" placeholder="PayPal" />
+            </FieldRow>
+          </div>
+        </SectionCard>
+      </div>
+    </div>
+  )
+}