@easypayment/medusa-payment-paypal 0.9.22 → 0.9.25

package/src/api/admin/payment-collections/[id]/payment-sessions/route.ts

@@ -1,5 +1,5 @@
-import { createPaymentSessionsWorkflow } from "@medusajs/core-flows"
 import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+import { runCoreWorkflow } from "../../../../../modules/paypal/utils/core-workflow"
 
 type CreatePaymentSessionBody = {
   provider_id: string
@@ -25,13 +25,11 @@ export async function POST(req: MedusaRequest, res: MedusaResponse) {
   }
 
   try {
-    const { result } = await createPaymentSessionsWorkflow(req.scope).run({
-      input: {
-        payment_collection_id: collectionId,
-        provider_id,
-        customer_id,
-        data,
-      },
+    const { result } = await runCoreWorkflow(req.scope, "create-payment-sessions", {
+      payment_collection_id: collectionId,
+      provider_id,
+      customer_id,
+      data,
     })
 
     res.status(200).json({ payment_session: result })

package/src/api/admin/paypal/environment/route.ts

@@ -6,9 +6,16 @@ type Body = {
 }
 
 export async function GET(req: MedusaRequest, res: MedusaResponse) {
-  const paypal = req.scope.resolve<PayPalModuleService>("paypal_onboarding")
-  const status = await paypal.getStatus()
-  return res.json({ environment: status.environment })
+  try {
+    const paypal = req.scope.resolve<PayPalModuleService>("paypal_onboarding")
+    const status = await paypal.getStatus()
+    return res.json({ environment: status.environment })
+  } catch {
+    // This GET runs on every connection-page load; an unguarded rejection here
+    // (no connection row yet, transient DB / decrypt error) would surface as an
+    // unhandled 500. Fail soft so the admin page can still render.
+    return res.status(500).json({ message: "Failed to load environment" })
+  }
 }
 
 export async function POST(req: MedusaRequest, res: MedusaResponse) {

package/src/api/admin/paypal/onboard-complete/route.ts

@@ -1,6 +1,13 @@
 import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
 import type PayPalModuleService from "../../../../modules/paypal/service"
 
+/**
+ * The PayPal onboarding `return_url` (the page the mini-browser popup lands on)
+ * is the PUBLIC route `GET /store/paypal/onboard-return` — `/admin/*` routes
+ * require an auth token that a top-level popup navigation cannot carry, which
+ * would leave the popup stuck on a 401 page. This admin GET is therefore not part
+ * of the browser flow; it only documents the contract for the POST below.
+ */
 export async function GET(_req: MedusaRequest, res: MedusaResponse) {
   return res.status(405).json({
     message:

package/src/api/admin/paypal/onboarding-status/route.ts

@@ -9,8 +9,11 @@ export async function GET(req: MedusaRequest, res: MedusaResponse) {
   } catch (e: unknown) {
     const message = e instanceof Error ? e.message : String(e)
     console.error("[paypal_onboarding] onboarding-status error:", message)
+    // Do NOT report a definitive `status: "disconnected"` here — a transient DB
+    // or decrypt error would then look like the merchant is not connected and
+    // could trigger a needless re-onboarding. Signal the error with `unknown`.
     return res.status(500).json({
-      status: "disconnected",
+      status: "unknown",
       message: "Failed to retrieve PayPal status",
     })
   }

package/src/api/store/payment-collections/[id]/payment-sessions/route.ts

@@ -1,6 +1,6 @@
-import { createPaymentSessionsWorkflow } from "@medusajs/core-flows"
 import { MedusaResponse, MedusaStoreRequest, refetchEntity } from "@medusajs/framework/http"
 import { MedusaError } from "@medusajs/framework/utils"
+import { runCoreWorkflow } from "../../../../../modules/paypal/utils/core-workflow"
 
 type CreatePaymentSessionBody = {
   provider_id: string
@@ -27,13 +27,11 @@ export async function POST(req: MedusaStoreRequest, res: MedusaResponse) {
   }
 
   try {
-    await createPaymentSessionsWorkflow(req.scope).run({
-      input: {
-        payment_collection_id: collectionId,
-        provider_id,
-        customer_id: req.auth_context?.actor_id,
-        data,
-      },
+    await runCoreWorkflow(req.scope, "create-payment-sessions", {
+      payment_collection_id: collectionId,
+      provider_id,
+      customer_id: req.auth_context?.actor_id,
+      data,
     })
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error)

package/src/api/store/paypal/capture-order/route.ts

@@ -5,6 +5,7 @@ import { randomUUID } from "crypto"
 import type PayPalModuleService from "../../../../modules/paypal/service"
 import { getPayPalApiBase } from "../../../../modules/paypal/utils/paypal-auth"
 import { paypalFetch } from "../../../../modules/paypal/utils/paypal-fetch"
+import { extractCaptureStatus } from "../../../../modules/paypal/payment-provider/status-utils"
 import {
   findPayPalSessionForCart,
   getStoredPayPalOrderId,
@@ -204,6 +205,20 @@ export async function POST(req: MedusaRequest, res: MedusaResponse) {
     if (paymentAction === "authorize") {
       await attachPayPalAuthorizationToSession(cartId, orderId, payload, req.scope)
     } else {
+      // A 2xx capture response does NOT guarantee the funds settled: PayPal
+      // returns 201 for PENDING (pending review / eCheck), DECLINED and FAILED
+      // captures too. Returning those to the storefront as a successful capture
+      // would let it finalize the cart for a payment that never completed, so
+      // only a COMPLETED capture is reported as success — the webhook will
+      // reconcile a later PENDING→COMPLETED transition.
+      const captureStatus = extractCaptureStatus(payload)
+      if (captureStatus !== "COMPLETED") {
+        throw new Error(
+          `PayPal capture did not complete (status=${captureStatus || "UNKNOWN"})${
+            debugId ? ` debug_id=${debugId}` : ""
+          }`
+        )
+      }
       await attachPayPalCaptureToSession(cartId, orderId, payload, req.scope)
     }
 

package/src/api/store/paypal/onboard-return/route.ts

@@ -0,0 +1,63 @@
+import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+
+/**
+ * Public PayPal onboarding `return_url`.
+ *
+ * When a seller finishes onboarding, PayPal redirects the mini-browser popup to
+ * this URL as a plain top-level navigation (no auth header / no publishable key),
+ * which is why it must live under the public `/store/paypal/*` namespace rather
+ * than `/admin/*`. Leaving the popup on a raw JSON / 401 / 405 page is exactly
+ * what made the popup appear to "never close".
+ *
+ * This route serves a tiny HTML bridge that runs inside the popup and:
+ *   1. relays whatever query params PayPal appended back to the opener
+ *      (the Medusa Admin connection page) via postMessage, and
+ *   2. closes the popup.
+ *
+ * The actual credential exchange happens via the admin POST
+ * /admin/paypal/onboard-complete (driven by partner.js's onboardingCallback and
+ * the admin page's postMessage listener). This page is the safety net that
+ * guarantees the popup closes and the admin page re-checks status even if the
+ * in-flight PayPal completion message was missed.
+ */
+export async function GET(req: MedusaRequest, res: MedusaResponse) {
+  const query = (req.query || {}) as Record<string, unknown>
+  const params: Record<string, string> = {}
+  for (const [k, v] of Object.entries(query)) {
+    if (v == null) continue
+    params[k] = Array.isArray(v) ? String(v[0]) : String(v)
+  }
+
+  // JSON-encode then escape the characters that could break out of the inline
+  // <script> string/tag (including the U+2028/U+2029 separators that are legal in
+  // JSON but illegal in a JS string literal), so the relayed params embed safely.
+  const safePayload = JSON.stringify(params)
+    .replace(/</g, "\\u003c")
+    .replace(/>/g, "\\u003e")
+    .replace(/&/g, "\\u0026")
+    .replace(/[\u2028\u2029]/g, (c) => "\\u" + c.charCodeAt(0).toString(16).padStart(4, "0"))
+
+  const html = `<!doctype html>
+<html lang="en">
+<head><meta charset="utf-8" /><title>PayPal onboarding complete</title></head>
+<body style="font-family: system-ui, sans-serif; padding: 24px; text-align: center; color: #1f2937;">
+<p>PayPal onboarding complete. You can close this window.</p>
+<script>
+(function () {
+  try {
+    var message = { source: "paypal-onboarding-return", params: ${safePayload} };
+    if (window.opener && !window.opener.closed) {
+      try { window.opener.postMessage(message, "*"); } catch (e) {}
+    }
+  } catch (e) {}
+  // Give the opener a moment to react, then close the popup.
+  setTimeout(function () { try { window.close(); } catch (e) {} }, 600);
+})();
+</script>
+</body>
+</html>`
+
+  res.setHeader("Content-Type", "text/html; charset=utf-8")
+  res.setHeader("Cache-Control", "no-store")
+  return res.status(200).send(html)
+}

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

@@ -1,9 +1,9 @@
 import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
 import type { IPaymentModuleService, Logger } from "@medusajs/framework/types"
 import { ContainerRegistrationKeys, Modules } from "@medusajs/framework/utils"
-import { completeCartWorkflow } from "@medusajs/core-flows"
 import { randomUUID } from "crypto"
 import { isPayPalProviderId } from "../../../modules/paypal/utils/provider-ids"
+import { runCoreWorkflow } from "../../../modules/paypal/utils/core-workflow"
 
 export async function POST(req: MedusaRequest, res: MedusaResponse) {
   const logger = req.scope.resolve<Logger>(ContainerRegistrationKeys.LOGGER)
@@ -80,9 +80,11 @@ export async function POST(req: MedusaRequest, res: MedusaResponse) {
     }
 
     try {
-      const { result } = await completeCartWorkflow(req.scope).run({
-        input: { id: cart_id },
-      })
+      const { result } = await runCoreWorkflow<{ id: string }, { id?: string }>(
+        req.scope,
+        "complete-cart",
+        { id: cart_id }
+      )
       logger.info(
         `[paypal] paypal-complete cart completed (request_id=${requestId}, cart_id=${cart_id}, order_id=${result?.id})`
       )

package/src/modules/paypal/payment-provider/card-service.ts

@@ -31,6 +31,12 @@ import {
   assertPayPalCurrencySupported,
   normalizeCurrencyCode,
 } from "../utils/currencies"
+import {
+  extractCaptureStatus,
+  isCaptureCompleted,
+  isRefundFailureStatus,
+  mapPayPalCaptureStatus,
+} from "./status-utils"
 import type PayPalModuleService from "../service"
 
 type Options = {}
@@ -154,23 +160,12 @@ class PayPalAdvancedCardProvider extends AbstractPaymentProvider<Options> {
   }
 
   private mapCaptureStatus(status?: string) {
-    const normalized = String(status || "").toUpperCase()
-    if (!normalized) {
-      return null
-    }
-    if (normalized === "COMPLETED") {
-      return "captured"
-    }
-    if (normalized === "PENDING") {
-      return "pending"
-    }
-    if (["DENIED", "DECLINED", "FAILED"].includes(normalized)) {
-      return "error"
-    }
-    if (["REFUNDED", "PARTIALLY_REFUNDED", "REVERSED"].includes(normalized)) {
-      return "canceled"
-    }
-    return null
+    // Delegate to the shared, unit-tested mapping so the card provider agrees
+    // with the wallet provider and the webhook processor. In particular a
+    // PARTIALLY_REFUNDED capture must stay "captured" (only part of the funds
+    // were returned) — mapping it to "canceled" would wrongly unwind a live
+    // capture.
+    return mapPayPalCaptureStatus(status)
   }
 
   private mapAuthorizationStatus(status?: string) {
@@ -478,7 +473,7 @@ class PayPalAdvancedCardProvider extends AbstractPaymentProvider<Options> {
     const { accessToken, base } = await this.getPayPalAccessToken()
     const order = await this.getOrderDetails(orderId).catch(() => null)
     const existingCapture = order?.purchase_units?.[0]?.payments?.captures?.[0]
-    if (existingCapture?.id) {
+    if (existingCapture?.id && isCaptureCompleted(existingCapture)) {
       return {
         data: {
           ...(data || {}),
@@ -524,26 +519,38 @@ class PayPalAdvancedCardProvider extends AbstractPaymentProvider<Options> {
       data.is_final_capture ??
       data.final_capture ??
       undefined
-    const capturePayload =
-      amount > 0
-        ? {
-            amount: {
-              currency_code: currencyCode || "EUR",
-              value: formatAmountForPayPal(amount, currencyCode || "EUR"),
-            },
-            ...(typeof isFinalCapture === "boolean"
-              ? { is_final_capture: isFinalCapture }
-              : {}),
-          }
-        : {
-            ...(typeof isFinalCapture === "boolean"
-              ? { is_final_capture: isFinalCapture }
-              : {}),
-          }
-
-    const captureUrl = authorizationId
-      ? `${base}/v2/payments/authorizations/${encodeURIComponent(authorizationId)}/capture`
-      : `${base}/v2/checkout/orders/${encodeURIComponent(orderId)}/capture`
+    const captureValue = amount > 0
+      ? formatAmountForPayPal(amount, currencyCode || "EUR")
+      : null
+
+    // `amount` and `is_final_capture` are only honored on the authorizations
+    // capture endpoint. The orders capture endpoint always captures the FULL
+    // order and silently ignores an `amount` body — so a partial amount there
+    // would over-capture while we record the smaller requested value. Route
+    // partial captures through the authorization, and fail closed if a partial
+    // capture is attempted against a capture-intent order.
+    let capturePayload: Record<string, unknown>
+    let captureUrl: string
+    if (authorizationId) {
+      captureUrl = `${base}/v2/payments/authorizations/${encodeURIComponent(authorizationId)}/capture`
+      capturePayload = {
+        ...(captureValue
+          ? { amount: { currency_code: currencyCode || "EUR", value: captureValue } }
+          : {}),
+        ...(typeof isFinalCapture === "boolean" ? { is_final_capture: isFinalCapture } : {}),
+      }
+    } else {
+      captureUrl = `${base}/v2/checkout/orders/${encodeURIComponent(orderId)}/capture`
+      capturePayload = {}
+      const orderTotal = order?.purchase_units?.[0]?.amount?.value
+      if (captureValue && orderTotal && captureValue !== String(orderTotal)) {
+        throw new Error(
+          `PayPal partial capture (${captureValue} ${currencyCode || "EUR"}) is not supported for ` +
+            `capture-intent orders (order total ${orderTotal}). Create the order with intent ` +
+            `AUTHORIZE to capture a partial amount.`
+        )
+      }
+    }
 
     const ppResp = await paypalFetch(captureUrl, {
       method: "POST",
@@ -567,6 +574,19 @@ class PayPalAdvancedCardProvider extends AbstractPaymentProvider<Options> {
     }
 
     const capture = JSON.parse(ppText)
+
+    // A 2xx response does NOT mean the funds were captured. PayPal returns 201
+    // for captures that are PENDING (pending review / eCheck), DECLINED, or
+    // FAILED. Recording any of these as "captured" books money that never
+    // settled, so only a COMPLETED capture is treated as success.
+    const captureStatus = extractCaptureStatus(capture)
+    if (captureStatus !== "COMPLETED") {
+      throw new Error(
+        `PayPal capture did not complete (status=${captureStatus || "UNKNOWN"}). ` +
+          `The payment was not captured.${debugId ? ` debug_id=${debugId}` : ""}`
+      )
+    }
+
     const captureId =
       capture?.id || capture?.purchase_units?.[0]?.payments?.captures?.[0]?.id
     const existingCaptures = Array.isArray(paypalData.captures) ? paypalData.captures : []
@@ -751,6 +771,20 @@ class PayPalAdvancedCardProvider extends AbstractPaymentProvider<Options> {
     }
 
     const refund = JSON.parse(text)
+
+    // As with captures, a 2xx response does not guarantee the refund stuck.
+    // FAILED / CANCELLED / DENIED refunds also return 2xx and must not be
+    // recorded as a successful refund. PENDING is accepted: PayPal processes
+    // refunds asynchronously and a pending refund will settle.
+    const refundStatus = String(refund?.status || "").toUpperCase()
+    if (isRefundFailureStatus(refundStatus)) {
+      const refundDebugId = resp.headers.get("paypal-debug-id")
+      throw new Error(
+        `PayPal refund did not succeed (status=${refundStatus}). The refund was not issued.` +
+          (refundDebugId ? ` debug_id=${refundDebugId}` : "")
+      )
+    }
+
     const existingRefunds = Array.isArray(paypalData.refunds) ? paypalData.refunds : []
     const refundEntry = {
       id: refund?.id,

package/src/modules/paypal/service.ts

@@ -495,7 +495,11 @@ class PayPalModuleService extends MedusaService({
 
   async createOnboardingLink(input?: { email?: string; products?: string[]; env?: Environment }) {
     const { onboarding } = await this.ensureSettingsDefaults()
-    const return_url = `${String(onboarding.backend_url || "").replace(/\/$/, "")}/admin/paypal/onboard-complete`
+    // The popup lands here after onboarding, as a plain top-level navigation with
+    // no auth token — so it must be the PUBLIC store bridge route, not an
+    // /admin/* route (which would 401 and leave the popup stuck). The bridge
+    // relays the result to the opener and closes the popup.
+    const return_url = `${String(onboarding.backend_url || "").replace(/\/$/, "")}/store/paypal/onboard-return`
     // Honor an explicit environment from the caller so the generated link can't
     // depend on a racing "set environment" request having landed first.
     const env =

package/src/modules/paypal/utils/core-workflow.ts

@@ -0,0 +1,46 @@
+import { MedusaWorkflow } from "@medusajs/framework/workflows-sdk"
+import type { MedusaContainer } from "@medusajs/framework"
+
+/**
+ * Run a Medusa *core* workflow by its registered id, without importing it from
+ * `@medusajs/core-flows`.
+ *
+ * Why this exists:
+ * Importing anything from `@medusajs/core-flows` (e.g.
+ * `import { completeCartWorkflow } from "@medusajs/core-flows"`) pulls in the
+ * entire core-flows barrel. Every workflow module in that barrel calls
+ * `createWorkflow(...)` at import time, which registers the workflow in the
+ * global `WorkflowManager`. When this plugin is resolved as a *separate* copy
+ * of `@medusajs/core-flows` from the host application — which is exactly what
+ * happens when the plugin is consumed as a locally-linked package living
+ * outside the app's `node_modules` (e.g. a sibling folder with its own
+ * `node_modules`) — those registrations run a second time and collide with the
+ * host's already-registered workflows. Medusa then aborts boot with:
+ *
+ *   An error occurred while registering API Routes.
+ *   Error: Workflow with id "create-fulfillment-workflow" and step definition
+ *   already exists.
+ *
+ * (The id is whichever core workflow happens to register first.)
+ *
+ * The host registers every core workflow into the global `MedusaWorkflow`
+ * registry at startup. Looking the workflow up there and running it reuses that
+ * single registered instance and never triggers a second registration, so the
+ * plugin works regardless of how it is installed or linked.
+ */
+export async function runCoreWorkflow<TInput = unknown, TResult = unknown>(
+  container: MedusaContainer,
+  workflowId: string,
+  input: TInput
+): Promise<{ result: TResult }> {
+  const workflow = MedusaWorkflow.getWorkflow(workflowId)
+
+  if (!workflow) {
+    throw new Error(
+      `Core workflow "${workflowId}" is not registered. ` +
+        `Ensure the Medusa application has loaded its core workflows.`
+    )
+  }
+
+  return workflow(container).run({ input })
+}