@easypayment/medusa-paypal 0.1.0

package/src/api/store/paypal/disputes/route.ts

@@ -0,0 +1,67 @@
+import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+import type PayPalModuleService from "../../../../modules/paypal/service"
+
+type DisputeRecord = {
+  id: string
+  dispute_id: string
+  status?: string | null
+  reason?: string | null
+  stage?: string | null
+  amount?: string | null
+  currency_code?: string | null
+  transaction_id?: string | null
+  seller_transaction_id?: string | null
+  order_id?: string | null
+  cart_id?: string | null
+  created_at?: string
+  updated_at?: string
+}
+
+function toPublicDispute(dispute: any): DisputeRecord {
+  return {
+    id: dispute.id,
+    dispute_id: dispute.dispute_id,
+    status: dispute.status ?? null,
+    reason: dispute.reason ?? null,
+    stage: dispute.stage ?? null,
+    amount: dispute.amount ?? null,
+    currency_code: dispute.currency_code ?? null,
+    transaction_id: dispute.transaction_id ?? null,
+    seller_transaction_id: dispute.seller_transaction_id ?? null,
+    order_id: dispute.order_id ?? null,
+    cart_id: dispute.cart_id ?? null,
+    created_at: dispute.created_at ?? null,
+    updated_at: dispute.updated_at ?? null,
+  }
+}
+
+export async function GET(req: MedusaRequest, res: MedusaResponse) {
+  const paypal = req.scope.resolve<PayPalModuleService>("paypal_onboarding")
+
+  const query = (req.query || {}) as Record<string, string | string[] | undefined>
+  const filters: Record<string, string> = {}
+
+  const addFilter = (key: string) => {
+    const value = query[key]
+    if (Array.isArray(value)) {
+      if (value[0]) {
+        filters[key] = value[0]
+      }
+      return
+    }
+    if (typeof value === "string" && value.trim()) {
+      filters[key] = value.trim()
+    }
+  }
+
+  addFilter("order_id")
+  addFilter("cart_id")
+  addFilter("dispute_id")
+
+  if (Object.keys(filters).length === 0) {
+    return res.status(400).json({ message: "order_id, cart_id, or dispute_id is required" })
+  }
+
+  const disputes = await paypal.listPayPalDisputes(filters)
+  return res.json({ disputes: (disputes || []).map(toPublicDispute) })
+}

package/src/api/store/paypal/settings/route.ts

@@ -0,0 +1,12 @@
+import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+import type PayPalModuleService from "../../../../modules/paypal/service"
+
+export async function GET(req: MedusaRequest, res: MedusaResponse) {
+  const paypal = req.scope.resolve<PayPalModuleService>("paypal_onboarding")
+  try {
+    const settings = await paypal.getSettings()
+    return res.json(settings)
+  } catch (e: any) {
+    return res.status(500).json({ message: e?.message || "Failed to load PayPal settings" })
+  }
+}

package/src/api/store/paypal/webhook/route.ts

@@ -0,0 +1,247 @@
+import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+import type PayPalModuleService from "../../../../modules/paypal/service"
+import {
+  computeNextRetryAt,
+  isAllowedEventType,
+  normalizeEventVersion,
+  processPayPalWebhookEvent,
+} from "../../../../modules/paypal/webhook-processor"
+
+const REPLAY_WINDOW_MINUTES = (() => {
+  const configured = Number(process.env.PAYPAL_WEBHOOK_REPLAY_WINDOW_MINUTES)
+  return Number.isFinite(configured) ? configured : 60
+})()
+
+function getHeader(headers: Record<string, string | string[] | undefined>, name: string) {
+  const direct = headers[name]
+  if (Array.isArray(direct)) {
+    return direct[0]
+  }
+  if (typeof direct === "string") {
+    return direct
+  }
+
+  const needle = name.toLowerCase()
+  const key = Object.keys(headers).find((header) => header.toLowerCase() === needle)
+  const value = key ? headers[key] : undefined
+  if (Array.isArray(value)) {
+    return value[0]
+  }
+  return value
+}
+
+function isReplay(headers: Record<string, string | string[] | undefined>) {
+  const transmissionTime = getHeader(headers, "paypal-transmission-time")
+  if (!transmissionTime) {
+    throw new Error("Missing PayPal transmission time header")
+  }
+
+  const parsed = Date.parse(transmissionTime)
+  if (!Number.isFinite(parsed)) {
+    throw new Error("Invalid PayPal transmission time header")
+  }
+
+  const deltaMs = Math.abs(Date.now() - parsed)
+  return deltaMs > REPLAY_WINDOW_MINUTES * 60 * 1000
+}
+
+function resolveWebhookId(
+  environment: string,
+  settings?: Record<string, unknown>
+) {
+  const ids = (settings?.webhook_ids || {}) as Record<string, string | undefined>
+  const legacyLive = settings?.webhook_id_live as string | undefined
+  const legacySandbox = settings?.webhook_id_sandbox as string | undefined
+
+  if (environment === "live") {
+    return ids.live || legacyLive || process.env.PAYPAL_WEBHOOK_ID_LIVE
+  }
+  return ids.sandbox || legacySandbox || process.env.PAYPAL_WEBHOOK_ID_SANDBOX
+}
+
+async function verifyWebhookSignature(
+  paypal: PayPalModuleService,
+  environment: string,
+  body: Record<string, unknown>,
+  headers: Record<string, string | string[] | undefined>
+) {
+  if (isReplay(headers)) {
+    throw new Error("PayPal webhook replay protection triggered")
+  }
+
+  const settings = await paypal.getSettings().catch(() => ({ data: {} }))
+  const webhookId = resolveWebhookId(
+    environment,
+    (settings?.data as Record<string, unknown>) || {}
+  )
+  if (!webhookId) {
+    throw new Error(`Missing PayPal webhook ID for environment "${environment}"`)
+  }
+
+  const base =
+    environment === "live"
+      ? "https://api-m.paypal.com"
+      : "https://api-m.sandbox.paypal.com"
+  const accessToken = await paypal.getAppAccessToken()
+
+  const verifyPayload = {
+    auth_algo: getHeader(headers, "paypal-auth-algo"),
+    cert_url: getHeader(headers, "paypal-cert-url"),
+    transmission_id: getHeader(headers, "paypal-transmission-id"),
+    transmission_sig: getHeader(headers, "paypal-transmission-sig"),
+    transmission_time: getHeader(headers, "paypal-transmission-time"),
+    webhook_id: webhookId,
+    webhook_event: body,
+  }
+
+  const requiredHeaders = [
+    verifyPayload.auth_algo,
+    verifyPayload.cert_url,
+    verifyPayload.transmission_id,
+    verifyPayload.transmission_sig,
+    verifyPayload.transmission_time,
+  ]
+  if (requiredHeaders.some((value) => !value)) {
+    throw new Error("Missing required PayPal webhook signature headers")
+  }
+
+  const resp = await fetch(`${base}/v1/notifications/verify-webhook-signature`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${accessToken}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify(verifyPayload),
+  })
+
+  const json = await resp.json().catch(() => ({}))
+  if (!resp.ok || json?.verification_status !== "VERIFIED") {
+    const debugId = resp.headers.get("paypal-debug-id") || json?.debug_id
+    throw new Error(
+      `PayPal webhook verification failed (${resp.status}): ${JSON.stringify(json)}${
+        debugId ? ` debug_id=${debugId}` : ""
+      }`
+    )
+  }
+}
+
+export async function POST(req: MedusaRequest, res: MedusaResponse) {
+  const paypal = req.scope.resolve<PayPalModuleService>("paypal_onboarding")
+
+  try {
+    const payload = (req.body || {}) as Record<string, any>
+    const eventId = String(payload?.id || payload?.event_id || "")
+    const eventType = String(payload?.event_type || payload?.eventType || "")
+
+    if (!eventId || !eventType) {
+      return res.status(400).json({ message: "Missing PayPal event id or type" })
+    }
+
+    const creds = await paypal.getActiveCredentials()
+    await verifyWebhookSignature(paypal, creds.environment, payload, req.headers)
+    const transmissionId = getHeader(req.headers, "paypal-transmission-id") || null
+    const transmissionTimeHeader = getHeader(req.headers, "paypal-transmission-time")
+    const transmissionTime = transmissionTimeHeader ? new Date(transmissionTimeHeader) : null
+    const eventVersion = normalizeEventVersion(payload)
+
+    if (transmissionId) {
+      const existingByTransmission = await paypal.listPayPalWebhookEvents({
+        transmission_id: transmissionId,
+      })
+      if ((existingByTransmission || []).length > 0) {
+        return res.json({ ok: true, duplicate: true })
+      }
+    }
+
+    const recordResult = await paypal.createWebhookEventRecord({
+      event_id: eventId,
+      event_type: eventType,
+      payload,
+      event_version: eventVersion,
+      transmission_id: transmissionId,
+      transmission_time: transmissionTime,
+      status: "processing",
+      attempt_count: 1,
+    })
+    if (!recordResult.created) {
+      return res.json({ ok: true, duplicate: true })
+    }
+
+    if (!isAllowedEventType(eventType)) {
+      await paypal.recordAuditEvent("webhook_unsupported_event", {
+        event_id: eventId,
+        event_type: eventType,
+      })
+      if (recordResult.event?.id) {
+        await paypal.updateWebhookEventRecord({
+          id: recordResult.event.id,
+          status: "ignored",
+          processed_at: new Date(),
+        })
+      }
+      return res.json({ ok: true, ignored: true })
+    }
+
+    const processed = await processPayPalWebhookEvent(req.scope, {
+      eventType,
+      payload,
+    })
+
+    if (recordResult.event?.id) {
+      await paypal.updateWebhookEventRecord({
+        id: recordResult.event.id,
+        status: "processed",
+        processed_at: new Date(),
+        resource_id:
+          processed.disputeId || processed.refundId || processed.captureId || processed.orderId || null,
+      })
+    }
+
+    console.info("[PayPal] webhook", {
+      event_id: eventId,
+      event_type: eventType,
+      order_id: processed.orderId,
+      capture_id: processed.captureId,
+      refund_id: processed.refundId,
+      cart_id: processed.cartId,
+    })
+
+    try {
+      await paypal.recordMetric("webhook_success")
+    } catch {
+      // ignore metrics failures
+    }
+
+    return res.json({ ok: true })
+  } catch (e: any) {
+    try {
+      const payload = (req.body || {}) as Record<string, any>
+      const eventId = String(payload?.id || payload?.event_id || "")
+      const eventType = String(payload?.event_type || payload?.eventType || "")
+      if (eventId) {
+        const existing = await paypal.listPayPalWebhookEvents({ event_id: eventId })
+        const record = existing?.[0]
+        if (record?.id) {
+          const attemptCount = Number(record.attempt_count || 0) + 1
+          await paypal.updateWebhookEventRecord({
+            id: record.id,
+            status: "failed",
+            attempt_count: attemptCount,
+            next_retry_at: computeNextRetryAt(attemptCount),
+            last_error: e?.message || String(e),
+          })
+        }
+      }
+      await paypal.recordAuditEvent("webhook_failed", {
+        event_id: payload?.id || payload?.event_id,
+        event_type: payload?.event_type || payload?.eventType,
+        message: e?.message || String(e),
+      })
+      await paypal.recordMetric("webhook_failed")
+    } catch {
+      // ignore audit logging failures
+    }
+    console.error("[PayPal] webhook error", e?.message || e)
+    return res.status(500).json({ message: e?.message || "PayPal webhook error" })
+  }
+}

package/src/jobs/paypal-reconcile.ts

@@ -0,0 +1,135 @@
+import type { MedusaContainer } from "@medusajs/framework/types"
+import type PayPalModuleService from "../modules/paypal/service"
+
+const STATUS_MAP: Record<string, "pending" | "authorized" | "captured" | "canceled"> = {
+  CREATED: "pending",
+  APPROVED: "authorized",
+  COMPLETED: "captured",
+  VOIDED: "canceled",
+  CANCELLED: "canceled",
+}
+
+export default async function paypalReconcile(container: MedusaContainer) {
+  const paymentSessionService = container.resolve("payment_session") as any
+  const paypal = container.resolve<PayPalModuleService>("paypal_onboarding")
+
+  const sessions = await paymentSessionService.list({
+    provider_id: ["paypal", "paypal_card"],
+    status: ["pending", "authorized"],
+  })
+
+  let sessionsChecked = 0
+  let sessionsUpdated = 0
+  let driftCount = 0
+  let lastDriftAt: string | null = null
+  let lastDriftOrderId: string | null = null
+  let hadFailure = false
+  let lastErrorMessage: string | null = null
+
+  for (const session of sessions || []) {
+    const data = (session?.data || {}) as Record<string, any>
+    const paypalData = (data.paypal || {}) as Record<string, any>
+    const orderId = String(paypalData.order_id || data.order_id || "")
+    if (!orderId) {
+      continue
+    }
+
+    sessionsChecked += 1
+
+    try {
+      const order = await paypal.getOrderDetails(orderId)
+      const status = STATUS_MAP[String(order?.status || "").toUpperCase()]
+      if (!status) {
+        continue
+      }
+
+      const previousStatus = session?.status
+      if (previousStatus && previousStatus !== status) {
+        driftCount += 1
+        lastDriftAt = new Date().toISOString()
+        lastDriftOrderId = orderId
+        await paypal.recordPaymentLog("reconcile_drift", {
+          session_id: session.id,
+          order_id: orderId,
+          previous_status: previousStatus,
+          next_status: status,
+        })
+        await paypal.recordMetric("reconcile_drift")
+        await paypal.sendAlert({
+          type: "reconcile_drift",
+          message: `PayPal reconciliation drift detected for order ${orderId}.`,
+          metadata: {
+            session_id: session.id,
+            previous_status: previousStatus,
+            next_status: status,
+          },
+        })
+      }
+
+      await paymentSessionService.update(session.id, {
+        status,
+        data: {
+          ...(session.data || {}),
+          paypal: {
+            ...((session.data || {}).paypal || {}),
+            order,
+            reconciliation: {
+              last_reconciled_at: new Date().toISOString(),
+              last_status: status,
+              order_status: order?.status,
+            },
+          },
+        },
+      })
+      sessionsUpdated += 1
+      try {
+        await paypal.recordMetric("reconcile_success")
+      } catch {
+        // ignore metrics failures
+      }
+    } catch (error) {
+      hadFailure = true
+      lastErrorMessage = error instanceof Error ? error.message : String(error)
+      try {
+        await paypal.recordMetric("reconcile_failed")
+      } catch {
+        // ignore metrics failures
+      }
+      await paypal.sendAlert({
+        type: "reconcile_failed",
+        message: `PayPal reconciliation failed for order ${orderId}.`,
+        metadata: {
+          session_id: session.id,
+        },
+      })
+      console.error("[PayPal] reconcile error", error)
+    }
+  }
+
+  try {
+    await paypal.updateReconciliationStatus({
+      status: hadFailure ? "failed" : "success",
+      sessions_checked: sessionsChecked,
+      sessions_updated: sessionsUpdated,
+      drift_count: driftCount,
+      last_drift_at: lastDriftAt,
+      last_drift_order_id: lastDriftOrderId,
+      error_message: hadFailure ? lastErrorMessage : null,
+    })
+  } catch (error: any) {
+    await paypal.updateReconciliationStatus({
+      status: "failed",
+      sessions_checked: sessionsChecked,
+      sessions_updated: sessionsUpdated,
+      drift_count: driftCount,
+      last_drift_at: lastDriftAt,
+      last_drift_order_id: lastDriftOrderId,
+      error_message: error?.message,
+    })
+  }
+}
+
+export const config = {
+  name: "paypal-reconcile",
+  schedule: "*/15 * * * *",
+}

package/src/jobs/paypal-webhook-retry.ts

@@ -0,0 +1,86 @@
+import type { MedusaContainer } from "@medusajs/framework/types"
+import type PayPalModuleService from "../modules/paypal/service"
+import {
+  computeNextRetryAt,
+  isAllowedEventType,
+  processPayPalWebhookEvent,
+} from "../modules/paypal/webhook-processor"
+
+const MAX_WEBHOOK_ATTEMPTS = 5
+
+export default async function paypalWebhookRetry(container: MedusaContainer) {
+  const paypal = container.resolve<PayPalModuleService>("paypal_onboarding")
+  const now = Date.now()
+  const candidates = await paypal.listPayPalWebhookEvents({ status: "failed" })
+
+  for (const event of candidates || []) {
+    const nextRetryAt = event?.next_retry_at ? new Date(event.next_retry_at).getTime() : null
+    if (!nextRetryAt || nextRetryAt > now) {
+      continue
+    }
+
+    const attemptCount = Number(event.attempt_count || 0) + 1
+    if (attemptCount > MAX_WEBHOOK_ATTEMPTS) {
+      continue
+    }
+
+    await paypal.updateWebhookEventRecord({
+      id: event.id,
+      status: "processing",
+      attempt_count: attemptCount,
+      next_retry_at: null,
+      last_error: null,
+    })
+
+    try {
+      const eventType = String(event.event_type || "")
+      if (!isAllowedEventType(eventType)) {
+        await paypal.updateWebhookEventRecord({
+          id: event.id,
+          status: "ignored",
+          processed_at: new Date(),
+        })
+        continue
+      }
+
+      const payload = (event.payload || {}) as Record<string, any>
+      const processed = await processPayPalWebhookEvent(container, {
+        eventType,
+        payload,
+      })
+
+      await paypal.updateWebhookEventRecord({
+        id: event.id,
+        status: "processed",
+        processed_at: new Date(),
+        resource_id:
+          processed.disputeId || processed.refundId || processed.captureId || processed.orderId || null,
+      })
+      try {
+        await paypal.recordMetric("webhook_retry_success")
+      } catch {
+        // ignore metrics failures
+      }
+    } catch (error: any) {
+      const nextRetry = attemptCount >= MAX_WEBHOOK_ATTEMPTS ? null : computeNextRetryAt(attemptCount)
+      await paypal.updateWebhookEventRecord({
+        id: event.id,
+        status: "failed",
+        attempt_count: attemptCount,
+        next_retry_at: nextRetry,
+        last_error: error?.message || String(error),
+      })
+      try {
+        await paypal.recordMetric("webhook_retry_failed")
+      } catch {
+        // ignore metrics failures
+      }
+      console.error("[PayPal] webhook retry error", error)
+    }
+  }
+}
+
+export const config = {
+  name: "paypal-webhook-retry",
+  schedule: "*/10 * * * *",
+}

package/src/modules/paypal/clients/paypal-seller.client.ts

@@ -0,0 +1,59 @@
+export class PayPalSellerClient {
+  constructor(private opts: { environment: "sandbox" | "live"; accessToken: string }) {}
+
+  private baseUrl() {
+    return this.opts.environment === "live"
+      ? "https://api-m.paypal.com"
+      : "https://api-m.sandbox.paypal.com"
+  }
+
+  private headers(extra?: Record<string, string>) {
+    return {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${this.opts.accessToken}`,
+      ...(extra ?? {}),
+    }
+  }
+
+  async createOrder(body: any) {
+    const res = await fetch(`${this.baseUrl()}/v2/checkout/orders`, {
+      method: "POST",
+      headers: this.headers(),
+      body: JSON.stringify(body),
+    })
+    const json = await res.json().catch(() => ({}))
+    if (!res.ok) throw new Error(`PayPal createOrder failed (${res.status}): ${JSON.stringify(json)}`)
+    return json
+  }
+
+  async getOrder(orderId: string) {
+    const res = await fetch(`${this.baseUrl()}/v2/checkout/orders/${orderId}`, {
+      method: "GET",
+      headers: this.headers(),
+    })
+    const json = await res.json().catch(() => ({}))
+    if (!res.ok) throw new Error(`PayPal getOrder failed (${res.status}): ${JSON.stringify(json)}`)
+    return json
+  }
+
+  async captureOrder(orderId: string) {
+    const res = await fetch(`${this.baseUrl()}/v2/checkout/orders/${orderId}/capture`, {
+      method: "POST",
+      headers: this.headers(),
+    })
+    const json = await res.json().catch(() => ({}))
+    if (!res.ok) throw new Error(`PayPal captureOrder failed (${res.status}): ${JSON.stringify(json)}`)
+    return json
+  }
+
+  async refundCapture(captureId: string, body?: any) {
+    const res = await fetch(`${this.baseUrl()}/v2/payments/captures/${captureId}/refund`, {
+      method: "POST",
+      headers: this.headers(),
+      body: body ? JSON.stringify(body) : "{}",
+    })
+    const json = await res.json().catch(() => ({}))
+    if (!res.ok) throw new Error(`PayPal refund failed (${res.status}): ${JSON.stringify(json)}`)
+    return json
+  }
+}

package/src/modules/paypal/index.ts

@@ -0,0 +1,8 @@
+import { Module } from "@medusajs/framework/utils"
+import PayPalModuleService from "./service"
+
+export const PAYPAL_MODULE = "paypal_onboarding"
+
+export default Module(PAYPAL_MODULE, {
+  service: PayPalModuleService,
+})

package/src/modules/paypal/migrations/20260115120000_create_paypal_connection.ts

@@ -0,0 +1,33 @@
+import { Migration } from "@medusajs/framework/mikro-orm/migrations"
+
+export class Migration20260115120000 extends Migration {
+  async up(): Promise<void> {
+    this.addSql(`
+      CREATE TABLE IF NOT EXISTS "paypal_connection" (
+        "id" text NOT NULL,
+        "environment" text NOT NULL DEFAULT 'sandbox',
+        "status" text NOT NULL DEFAULT 'disconnected',
+        "shared_id" text NULL,
+        "auth_code" text NULL,
+        "seller_client_id" text NULL,
+        "seller_client_secret" text NULL,
+        "app_access_token" text NULL,
+        "app_access_token_expires_at" timestamptz NULL,
+        "metadata" jsonb NOT NULL DEFAULT '{}'::jsonb,
+        "created_at" timestamptz NOT NULL DEFAULT now(),
+        "updated_at" timestamptz NOT NULL DEFAULT now(),
+        "deleted_at" timestamptz NULL,
+        CONSTRAINT "paypal_connection_pkey" PRIMARY KEY ("id")
+      );
+
+      CREATE INDEX IF NOT EXISTS "idx_paypal_connection_deleted_at"
+        ON "paypal_connection" ("deleted_at");
+    `)
+  }
+
+  async down(): Promise<void> {
+    this.addSql(`
+      DROP TABLE IF EXISTS "paypal_connection" CASCADE;
+    `)
+  }
+}

package/src/modules/paypal/migrations/20260123090000_create_paypal_settings.ts

@@ -0,0 +1,22 @@
+import { Migration } from "@medusajs/framework/mikro-orm/migrations"
+
+export class Migration20260123090000 extends Migration {
+  async up(): Promise<void> {
+    this.addSql(`
+      CREATE TABLE IF NOT EXISTS "paypal_settings" (
+        "id" text NOT NULL,
+        "data" jsonb NULL,
+        "created_at" timestamptz NOT NULL DEFAULT now(),
+        "updated_at" timestamptz NOT NULL DEFAULT now(),
+        "deleted_at" timestamptz NULL,
+        CONSTRAINT "paypal_settings_pkey" PRIMARY KEY ("id")
+      );
+      CREATE INDEX IF NOT EXISTS "idx_paypal_settings_deleted_at"
+        ON "paypal_settings" ("deleted_at");
+    `)
+  }
+
+  async down(): Promise<void> {
+    this.addSql(`DROP TABLE IF EXISTS "paypal_settings" CASCADE;`)
+  }
+}