@easypayment/medusa-payment-paypal 0.7.4

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

@@ -0,0 +1,325 @@
+import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+import type PayPalModuleService from "../../../../modules/paypal/service"
+import {
+  computeNextRetryAt,
+  isAllowedEventType,
+  isRetryableError,
+  normalizeEventVersion,
+  processPayPalWebhookEvent,
+} from "../../../../modules/paypal/webhook-processor"
+
+const REPLAY_WINDOW_MINUTES = (() => {
+  const v = Number(process.env.PAYPAL_WEBHOOK_REPLAY_WINDOW_MINUTES)
+  return Number.isFinite(v) && v > 0 ? v : 60
+})()
+
+function getHeader(
+  headers: Record<string, string | string[] | undefined>,
+  name: string
+): string | undefined {
+  const direct = headers[name]
+  if (Array.isArray(direct)) return direct[0]
+  if (typeof direct === "string") return direct
+  const lower = name.toLowerCase()
+  const key = Object.keys(headers).find((h) => h.toLowerCase() === lower)
+  if (!key) return undefined
+  const val = headers[key]
+  return Array.isArray(val) ? val[0] : val
+}
+
+interface ValidationFail {
+  ok: false
+  status: number
+  message: string
+}
+
+interface ValidationPass {
+  ok: true
+  eventId: string
+  eventType: string
+  transmissionId: string | null
+  transmissionTime: Date | null
+}
+
+function validateRequest(req: MedusaRequest): ValidationFail | ValidationPass {
+  const payload = (req.body || {}) as Record<string, any>
+  const eventId = String(payload?.id || payload?.event_id || "").trim()
+  const eventType = String(payload?.event_type || payload?.eventType || "").trim()
+
+  if (!eventId || !eventType) {
+    return { ok: false, status: 400, message: "Missing required fields: id and event_type" }
+  }
+
+  const transmissionTimeHeader = getHeader(req.headers, "paypal-transmission-time")
+  if (!transmissionTimeHeader) {
+    return {
+      ok: false,
+      status: 400,
+      message: "Missing required header: paypal-transmission-time",
+    }
+  }
+
+  const transmissionMs = Date.parse(transmissionTimeHeader)
+  if (!Number.isFinite(transmissionMs)) {
+    return {
+      ok: false,
+      status: 400,
+      message: "Invalid paypal-transmission-time header value",
+    }
+  }
+
+  const ageMs = Math.abs(Date.now() - transmissionMs)
+  if (ageMs > REPLAY_WINDOW_MINUTES * 60 * 1000) {
+    return {
+      ok: false,
+      status: 400,
+      message: `Webhook rejected: outside ${REPLAY_WINDOW_MINUTES}-minute replay window`,
+    }
+  }
+
+  return {
+    ok: true,
+    eventId,
+    eventType,
+    transmissionId: getHeader(req.headers, "paypal-transmission-id") || null,
+    transmissionTime: new Date(transmissionMs),
+  }
+}
+
+function resolveWebhookId(
+  environment: string,
+  settings: Record<string, unknown>
+): string | undefined {
+  const ids = (settings?.webhook_ids || {}) as Record<string, string | undefined>
+  if (environment === "live") {
+    return (
+      ids.live ||
+      (settings?.webhook_id_live as string) ||
+      process.env.PAYPAL_WEBHOOK_ID_LIVE
+    )
+  }
+  return (
+    ids.sandbox ||
+    (settings?.webhook_id_sandbox as string) ||
+    process.env.PAYPAL_WEBHOOK_ID_SANDBOX
+  )
+}
+
+async function verifyWebhookSignature(
+  paypal: PayPalModuleService,
+  environment: string,
+  body: Record<string, unknown>,
+  headers: Record<string, string | string[] | undefined>
+): Promise<void> {
+  const settings = await paypal.getSettings().catch(() => ({ data: {} }))
+  const webhookId = resolveWebhookId(
+    environment,
+    (settings?.data as Record<string, unknown>) || {}
+  )
+
+  if (!webhookId) {
+    throw new Error(
+      `PayPal webhook ID not configured for environment "${environment}". Set PAYPAL_WEBHOOK_ID_${environment.toUpperCase()} or configure it in admin settings.`
+    )
+  }
+
+  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 missing = Object.entries(verifyPayload)
+    .filter(([k, v]) => k !== "webhook_id" && k !== "webhook_event" && !v)
+    .map(([k]) => k)
+
+  if (missing.length > 0) {
+    throw new Error(`Missing required PayPal webhook headers: ${missing.join(", ")}`)
+  }
+
+  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(() => ({}))
+  const debugId = resp.headers.get("paypal-debug-id") || json?.debug_id
+
+  if (!resp.ok) {
+    throw new Error(
+      `PayPal signature verification API error (${resp.status}): ${JSON.stringify(json)}` +
+        (debugId ? ` debug_id=${debugId}` : "")
+    )
+  }
+  if (json?.verification_status !== "VERIFIED") {
+    throw new Error(
+      `PayPal webhook signature not verified. Status: ${json?.verification_status}` +
+        (debugId ? ` debug_id=${debugId}` : "")
+    )
+  }
+}
+
+export async function POST(req: MedusaRequest, res: MedusaResponse) {
+  const paypal = req.scope.resolve<PayPalModuleService>("paypal_onboarding")
+
+  const validation = validateRequest(req)
+  if (!validation.ok) {
+    console.warn("[PayPal] webhook: validation failed:", validation.message)
+    return res.status(validation.status).json({ message: validation.message })
+  }
+
+  const { eventId, eventType, transmissionId, transmissionTime } = validation
+  const payload = (req.body || {}) as Record<string, any>
+
+  if (transmissionId) {
+    try {
+      const existing = await paypal.listPayPalWebhookEvents({ transmission_id: transmissionId })
+      if ((existing || []).length > 0) {
+        console.info("[PayPal] webhook: duplicate transmission_id", {
+          transmissionId,
+          eventId,
+        })
+        return res.json({ ok: true, duplicate: true })
+      }
+    } catch (e: any) {
+      console.warn("[PayPal] webhook: transmission_id dedup check failed:", e?.message)
+    }
+  }
+
+  try {
+    const creds = await paypal.getActiveCredentials()
+    await verifyWebhookSignature(paypal, creds.environment, payload, req.headers)
+  } catch (e: any) {
+    console.error("[PayPal] webhook: signature verification failed:", e?.message)
+    return res
+      .status(401)
+      .json({ message: e?.message || "Webhook signature verification failed" })
+  }
+
+  const eventVersion = normalizeEventVersion(payload)
+  let recordId: string | null = null
+
+  try {
+    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) {
+      console.info("[PayPal] webhook: duplicate event_id", { eventId, eventType })
+      return res.json({ ok: true, duplicate: true })
+    }
+
+    recordId = recordResult.event?.id ?? null
+  } catch (e: any) {
+    console.error("[PayPal] webhook: failed to create DB record:", e?.message)
+    return res.status(500).json({ message: "Failed to record webhook event" })
+  }
+
+  if (!isAllowedEventType(eventType)) {
+    console.info("[PayPal] webhook: unsupported event type, ignoring", { eventType })
+    await paypal.recordAuditEvent("webhook_unsupported_event", {
+      event_id: eventId,
+      event_type: eventType,
+    })
+    if (recordId) {
+      await paypal
+        .updateWebhookEventRecord({
+          id: recordId,
+          status: "ignored",
+          processed_at: new Date(),
+        })
+        .catch(() => {})
+    }
+    return res.json({ ok: true, ignored: true })
+  }
+
+  try {
+    const processed = await processPayPalWebhookEvent(req.scope, { eventType, payload })
+
+    if (recordId) {
+      await paypal
+        .updateWebhookEventRecord({
+          id: recordId,
+          status: "processed",
+          processed_at: new Date(),
+          resource_id:
+            processed.refundId || processed.captureId || processed.orderId || null,
+        })
+        .catch(() => {})
+    }
+
+    console.info("[PayPal] webhook: processed", {
+      event_id: eventId,
+      event_type: eventType,
+      order_id: processed.orderId,
+      capture_id: processed.captureId,
+      refund_id: processed.refundId,
+      cart_id: processed.cartId,
+      session_updated: processed.sessionUpdated,
+    })
+
+    await paypal.recordMetric("webhook_success").catch(() => {})
+    return res.json({ ok: true })
+  } catch (e: any) {
+    console.error("[PayPal] webhook: processing failed", {
+      event_id: eventId,
+      event_type: eventType,
+      error: e?.message,
+    })
+
+    const retryable = isRetryableError(e)
+    const nextStatus = retryable ? "failed" : "dead_letter"
+
+    if (recordId) {
+      await paypal
+        .updateWebhookEventRecord({
+          id: recordId,
+          status: nextStatus,
+          attempt_count: 1,
+          next_retry_at: retryable ? computeNextRetryAt(1) : null,
+          last_error: e?.message || String(e),
+        })
+        .catch(() => {})
+    }
+
+    await paypal
+      .recordAuditEvent("webhook_processing_failed", {
+        event_id: eventId,
+        event_type: eventType,
+        retryable,
+        message: e?.message || String(e),
+      })
+      .catch(() => {})
+
+    await paypal.recordMetric("webhook_failed").catch(() => {})
+
+    if (!retryable) {
+      return res.status(200).json({ ok: false, message: e?.message })
+    }
+    return res
+      .status(500)
+      .json({ message: e?.message || "PayPal webhook processing error" })
+  }
+}

package/src/api/store/paypal-complete/route.ts

@@ -0,0 +1,95 @@
+import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+import type { IPaymentModuleService } from "@medusajs/framework/types"
+import { Modules } from "@medusajs/framework/utils"
+import type PayPalModuleService from "../../../modules/paypal/service"
+
+export async function POST(req: MedusaRequest, res: MedusaResponse) {
+  const { cart_id } = req.body as { cart_id: string }
+
+  if (!cart_id) {
+    return res.status(400).json({ error: "cart_id is required" })
+  }
+
+  try {
+    const query = req.scope.resolve("query")
+    const { data: carts } = await query.graph({
+      entity: "cart",
+      fields: [
+        "id",
+        "payment_collection.payment_sessions.id",
+        "payment_collection.payment_sessions.data",
+        "payment_collection.payment_sessions.status",
+        "payment_collection.payment_sessions.provider_id",
+        "payment_collection.payment_sessions.created_at",
+        "payment_collection.payment_sessions.amount",
+        "payment_collection.payment_sessions.currency_code",
+      ],
+      filters: { id: cart_id },
+    })
+
+    const sessions = carts?.[0]?.payment_collection?.payment_sessions || []
+    const session = sessions
+      .filter((s: any) => String(s.provider_id || "").includes("paypal"))
+      .sort(
+        (a: any, b: any) =>
+          new Date(b.created_at || 0).getTime() - new Date(a.created_at || 0).getTime()
+      )[0]
+
+    if (!session) {
+      return res.status(400).json({ error: "No PayPal payment session found for cart" })
+    }
+
+    const currentStatus = String(session.status || "")
+    if (currentStatus === "authorized" || currentStatus === "captured") {
+      console.info("[paypal-complete] session already in terminal status:", currentStatus)
+      return res.json({ success: true, session_id: session.id, status: currentStatus })
+    }
+
+    const paymentModule = req.scope.resolve(Modules.PAYMENT) as IPaymentModuleService
+
+    const [liveSession] = await paymentModule.listPaymentSessions(
+      { id: [session.id] },
+      { take: 1 }
+    )
+
+    const liveData = (liveSession?.data || {}) as Record<string, any>
+
+    const paypal = req.scope.resolve<PayPalModuleService>("paypal_onboarding")
+    const settings = await paypal.getSettings().catch(() => ({}))
+    const settingsData =
+      settings && typeof settings === "object" && "data" in settings
+        ? ((settings as { data?: Record<string, any> }).data ?? {})
+        : {}
+    const additionalSettings = (settingsData.additional_settings || {}) as Record<string, any>
+    const paymentAction =
+      typeof additionalSettings.paymentAction === "string"
+        ? additionalSettings.paymentAction
+        : "capture"
+
+    const timestampKey = paymentAction === "authorize" ? "authorized_at" : "captured_at"
+
+    if (!liveData[timestampKey]) {
+      await (paymentModule as any).updatePaymentSession({
+        id: session.id,
+        data: {
+          ...liveData,
+          [timestampKey]: new Date().toISOString(),
+        },
+        amount: liveSession?.amount ?? session.amount,
+        currency_code: liveSession?.currency_code ?? session.currency_code,
+      })
+    }
+
+    try {
+      await (paymentModule as any).authorizePaymentSession(session.id, {})
+      console.info("[paypal-complete] authorizePaymentSession succeeded for session", session.id)
+    } catch (e: any) {
+      console.warn("[paypal-complete] authorizePaymentSession non-fatal:", e?.message)
+    }
+
+    return res.json({ success: true, session_id: session.id })
+  } catch (e: any) {
+    console.error("[paypal-complete] error:", e?.message || e)
+    return res.status(500).json({ error: e?.message || "Internal error" })
+  }
+}

package/src/index.ts

@@ -0,0 +1 @@
+export { default } from "./modules/paypal"

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

@@ -0,0 +1,149 @@
+import type { MedusaContainer } from "@medusajs/framework/types"
+import type PayPalModuleService from "../modules/paypal/service"
+import {
+  computeNextRetryAt,
+  isAllowedEventType,
+  isRetryableError,
+  MAX_WEBHOOK_ATTEMPTS,
+  processPayPalWebhookEvent,
+} from "../modules/paypal/webhook-processor"
+
+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" })
+  if (!candidates?.length) return
+
+  console.info(
+    `[PayPal] webhook-retry: evaluating ${candidates.length} failed event(s)`
+  )
+
+  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)
+
+    if (attemptCount >= MAX_WEBHOOK_ATTEMPTS) {
+      await paypal
+        .updateWebhookEventRecord({
+          id: event.id,
+          status: "dead_letter",
+          next_retry_at: null,
+          last_error: `Exceeded max attempts (${MAX_WEBHOOK_ATTEMPTS})`,
+        })
+        .catch(() => {})
+      console.warn("[PayPal] webhook-retry: dead-lettered (max attempts)", {
+        id: event.id,
+        event_type: event.event_type,
+        attempts: attemptCount,
+      })
+      await paypal.recordMetric("webhook_dead_letter").catch(() => {})
+      continue
+    }
+
+    await paypal
+      .updateWebhookEventRecord({
+        id: event.id,
+        status: "processing",
+        attempt_count: attemptCount + 1,
+        next_retry_at: null,
+        last_error: null,
+      })
+      .catch(() => {})
+
+    const eventType = String(event.event_type || "")
+
+    if (!isAllowedEventType(eventType)) {
+      await paypal
+        .updateWebhookEventRecord({
+          id: event.id,
+          status: "ignored",
+          processed_at: new Date(),
+        })
+        .catch(() => {})
+      console.info("[PayPal] webhook-retry: ignored unsupported event type", {
+        id: event.id,
+        event_type: eventType,
+      })
+      continue
+    }
+
+    try {
+      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.refundId || processed.captureId || processed.orderId || null,
+        })
+        .catch(() => {})
+
+      console.info("[PayPal] webhook-retry: processed successfully", {
+        id: event.id,
+        event_type: eventType,
+        attempt: attemptCount + 1,
+        order_id: processed.orderId,
+        capture_id: processed.captureId,
+        cart_id: processed.cartId,
+        session_updated: processed.sessionUpdated,
+      })
+
+      await paypal.recordMetric("webhook_retry_success").catch(() => {})
+    } catch (error: any) {
+      const retryable = isRetryableError(error)
+      const nextAttempt = attemptCount + 1
+
+      if (!retryable || nextAttempt >= MAX_WEBHOOK_ATTEMPTS) {
+        await paypal
+          .updateWebhookEventRecord({
+            id: event.id,
+            status: "dead_letter",
+            attempt_count: nextAttempt,
+            next_retry_at: null,
+            last_error: error?.message || String(error),
+          })
+          .catch(() => {})
+        console.error("[PayPal] webhook-retry: dead-lettered after error", {
+          id: event.id,
+          event_type: eventType,
+          attempt: nextAttempt,
+          retryable,
+          error: error?.message,
+        })
+        await paypal.recordMetric("webhook_dead_letter").catch(() => {})
+      } else {
+        const nextRetry = computeNextRetryAt(nextAttempt)
+        await paypal
+          .updateWebhookEventRecord({
+            id: event.id,
+            status: "failed",
+            attempt_count: nextAttempt,
+            next_retry_at: nextRetry,
+            last_error: error?.message || String(error),
+          })
+          .catch(() => {})
+        console.warn("[PayPal] webhook-retry: scheduled retry", {
+          id: event.id,
+          event_type: eventType,
+          attempt: nextAttempt,
+          next_retry_at: nextRetry?.toISOString(),
+          error: error?.message,
+        })
+        await paypal.recordMetric("webhook_retry_failed").catch(() => {})
+      }
+    }
+  }
+}
+
+export const config = {
+  name: "paypal-webhook-retry",
+  schedule: "*/10 * * * *",
+}

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

@@ -0,0 +1,62 @@
+export class PayPalSellerClient {
+  private static readonly BN_CODE = "MBJTechnolabs_SI_SPB"
+
+  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}`,
+      "PayPal-Partner-Attribution-Id": PayPalSellerClient.BN_CODE,
+      ...(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;`)
+  }
+}