@easypayment/medusa-payment-paypal 0.9.25 → 0.9.27

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

@@ -1,4 +1,5 @@
 import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+import type PayPalModuleService from "../../../../modules/paypal/service"
 
 /**
  * Public PayPal onboarding `return_url`.
@@ -9,16 +10,18 @@ import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
  * 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.
+ * This route is the authoritative, partner.js-independent completion path. It:
+ *   1. exchanges PayPal's `authCode` + `sharedId` for seller credentials
+ *      server-side (idempotent — safe even if partner.js's onboardingCallback or
+ *      admin status polling also completes the exchange),
+ *   2. relays whatever query params PayPal appended back to the opener (the
+ *      Medusa Admin connection page) via postMessage so it can refresh
+ *      immediately, and
+ *   3. 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.
+ * Because the exchange no longer depends on the opener receiving an in-flight
+ * postMessage, onboarding completes (and the admin page flips to "connected" via
+ * its status poll) even when partner.js never fires its callback.
  */
 export async function GET(req: MedusaRequest, res: MedusaResponse) {
   const query = (req.query || {}) as Record<string, unknown>
@@ -28,6 +31,28 @@ export async function GET(req: MedusaRequest, res: MedusaResponse) {
     params[k] = Array.isArray(v) ? String(v[0]) : String(v)
   }
 
+  // PayPal appends the seller's authorization code + shared id to the return_url
+  // (plus the env we pinned when generating the link). When present, complete the
+  // exchange right here so credentials are saved even if no other path runs.
+  const authCode = params.authCode || params.auth_code
+  const sharedId = params.sharedId || params.shared_id
+  const env =
+    params.env === "sandbox" || params.env === "live" ? params.env : undefined
+
+  if (authCode && sharedId) {
+    try {
+      const paypal = req.scope.resolve<PayPalModuleService>("paypal_onboarding")
+      await paypal.exchangeAndSaveSellerCredentials({ authCode, sharedId, env })
+    } catch (e: unknown) {
+      // Don't break the popup close on failure — relay the params so the opener
+      // (partner.js / admin polling) can still attempt to complete.
+      console.error(
+        "[PayPal] onboard-return exchange failed:",
+        e instanceof Error ? e.message : e
+      )
+    }
+  }
+
   // 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.

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

@@ -1,4 +1,4 @@
-import { AbstractPaymentProvider } from "@medusajs/framework/utils"
+import { AbstractPaymentProvider, MedusaError } from "@medusajs/framework/utils"
 import { randomUUID } from "crypto"
 import type {
   AuthorizePaymentInput,
@@ -25,7 +25,7 @@ import type {
   WebhookActionResult,
 } from "@medusajs/framework/types"
 import { getPayPalWebhookActionAndData } from "./webhook-utils"
-import { formatAmountForPayPal } from "../utils/amounts"
+import { formatAmountForPayPal, toAmountNumber } from "../utils/amounts"
 import { paypalFetch } from "../utils/paypal-fetch"
 import {
   assertPayPalCurrencySupported,
@@ -727,84 +727,104 @@ class PayPalAdvancedCardProvider extends AbstractPaymentProvider<Options> {
     const paypalData = (data.paypal || {}) as Record<string, any>
     const captureId = String(paypalData.capture_id || data.capture_id || "")
     if (!captureId) {
-      throw new Error("PayPal capture_id is required to refund payment. No capture found in session data.")
+      throw new MedusaError(
+        MedusaError.Types.INVALID_DATA,
+        "PayPal capture_id is required to refund payment. No capture found in session data."
+      )
     }
 
-    const requestId = this.getIdempotencyKey(_input, `refund-${captureId}`)
     // Use the refund amount Medusa passes (top-level input), not the session
     // amount in `data` — otherwise a partial refund would refund the full order.
-    const amount = Number(_input.amount ?? 0)
+    // Medusa passes it as a BigNumberInput, so coerce it to a number; a naive
+    // Number() of the object form yields NaN and silently refunds the full
+    // capture.
+    const amount = toAmountNumber(_input.amount)
+    const requestId = this.getIdempotencyKey(_input, `refund-${captureId}-${amount}`)
     const currencyOverride = await this.resolveCurrencyOverride()
     const currencyCode = normalizeCurrencyCode(
       data.currency_code || currencyOverride || "EUR"
     )
-    const { accessToken, base } = await this.getPayPalAccessToken()
-    const refundPayload: Record<string, any> =
-      amount > 0
-        ? {
-            amount: {
-              currency_code: currencyCode,
-              value: formatAmountForPayPal(amount, currencyCode),
-            },
-          }
-        : {}
 
-    const resp = await paypalFetch(`${base}/v2/payments/captures/${encodeURIComponent(captureId)}/refund`, {
-      method: "POST",
-      headers: {
-        Authorization: `Bearer ${accessToken}`,
-        "Content-Type": "application/json",
-        "PayPal-Request-Id": requestId,
-        "PayPal-Partner-Attribution-Id": BN_CODE,
-      },
-      body: JSON.stringify(refundPayload),
-    })
+    try {
+      const { accessToken, base } = await this.getPayPalAccessToken()
+      const refundPayload: Record<string, any> =
+        amount > 0
+          ? {
+              amount: {
+                currency_code: currencyCode,
+                value: formatAmountForPayPal(amount, currencyCode),
+              },
+            }
+          : {}
 
-    const text = await resp.text()
-    if (!resp.ok) {
-      const debugId = resp.headers.get("paypal-debug-id")
-      throw new Error(
-        `PayPal refund error (${resp.status}): ${text}${
-          debugId ? ` debug_id=${debugId}` : ""
-        }`
-      )
-    }
+      const resp = await paypalFetch(`${base}/v2/payments/captures/${encodeURIComponent(captureId)}/refund`, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${accessToken}`,
+          "Content-Type": "application/json",
+          "PayPal-Request-Id": requestId,
+          "PayPal-Partner-Attribution-Id": BN_CODE,
+        },
+        body: JSON.stringify(refundPayload),
+      })
 
-    const refund = JSON.parse(text)
+      const text = await resp.text()
+      if (!resp.ok) {
+        const debugId = resp.headers.get("paypal-debug-id")
+        throw new MedusaError(
+          MedusaError.Types.UNEXPECTED_STATE,
+          `PayPal refund error (${resp.status}): ${text}${
+            debugId ? ` debug_id=${debugId}` : ""
+          }`
+        )
+      }
 
-    // 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 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 MedusaError(
+          MedusaError.Types.UNEXPECTED_STATE,
+          `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,
-      status: refund?.status,
-      amount: refund?.amount,
-      raw: refund,
-    }
+      const existingRefunds = Array.isArray(paypalData.refunds) ? paypalData.refunds : []
+      const refundEntry = {
+        id: refund?.id,
+        status: refund?.status,
+        amount: refund?.amount,
+        raw: refund,
+      }
 
-    return {
-      data: {
-        ...(data || {}),
-        paypal: {
-          ...paypalData,
-          refund_id: refund?.id,
-          refund_status: refund?.status,
-          refunds: [...existingRefunds, refundEntry],
-          refund,
+      return {
+        data: {
+          ...(data || {}),
+          paypal: {
+            ...paypalData,
+            refund_id: refund?.id,
+            refund_status: refund?.status,
+            refunds: [...existingRefunds, refundEntry],
+            refund,
+          },
+          refunded_at: new Date().toISOString(),
         },
-        refunded_at: new Date().toISOString(),
-      },
+      }
+    } catch (error: any) {
+      // Surface the real reason: Medusa masks any non-MedusaError as a generic
+      // "An unknown error occurred." in production, hiding the PayPal failure.
+      throw error instanceof MedusaError
+        ? error
+        : new MedusaError(
+            MedusaError.Types.UNEXPECTED_STATE,
+            error?.message || "PayPal refund failed."
+          )
     }
   }
 

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

@@ -1,4 +1,4 @@
-import { AbstractPaymentProvider } from "@medusajs/framework/utils"
+import { AbstractPaymentProvider, MedusaError } from "@medusajs/framework/utils"
 import { randomUUID } from "crypto"
 import type {
   AuthorizePaymentInput,
@@ -24,7 +24,7 @@ import type {
   ProviderWebhookPayload,
   WebhookActionResult,
 } from "@medusajs/framework/types"
-import { formatAmountForPayPal, getCurrencyExponent } from "../utils/amounts"
+import { formatAmountForPayPal, getCurrencyExponent, toAmountNumber } from "../utils/amounts"
 import {
   assertPayPalCurrencySupported,
   normalizeCurrencyCode,
@@ -773,16 +773,22 @@ class PayPalPaymentProvider extends AbstractPaymentProvider<Options> {
       paypalData.refund_reason_code || data.refund_reason_code || data.reason_code || ""
     ).trim()
     if (!captureId) {
-      throw new Error(
+      throw new MedusaError(
+        MedusaError.Types.INVALID_DATA,
         "PayPal capture_id is required to refund payment. No capture found in session data."
       )
     }
 
+    // Medusa passes the refund amount as a BigNumberInput (BigNumber instance or
+    // serialized { value, precision }); coerce it to a number so partial refunds
+    // send the correct value instead of silently refunding the full capture.
+    const refundAmount = toAmountNumber(input.amount)
+
     // Include the amount in the idempotency suffix so two sequential partial
     // refunds of the same capture are not deduplicated by PayPal into one.
     const requestId = this.getIdempotencyKey(
       input,
-      `refund-${captureId}-${Number(input.amount ?? 0)}`
+      `refund-${captureId}-${refundAmount}`
     )
 
     const currencyOverride = await this.resolveCurrencyOverride()
@@ -790,7 +796,6 @@ class PayPalPaymentProvider extends AbstractPaymentProvider<Options> {
       data.currency_code || currencyOverride || "EUR"
     )
 
-    const refundAmount = Number(input.amount ?? 0)
     const refundValue = refundAmount > 0
       ? formatAmountForPayPal(refundAmount, currencyCode)
       : null
@@ -810,7 +815,9 @@ class PayPalPaymentProvider extends AbstractPaymentProvider<Options> {
           : {}
 
       if (refundReason) {
-        refundPayload.note_to_payer = refundReason
+        // PayPal rejects a note_to_payer longer than 255 characters with a 422
+        // (which would otherwise fail the whole refund); truncate defensively.
+        refundPayload.note_to_payer = refundReason.slice(0, 255)
       }
 
       const ppResp = await paypalFetch(`${base}/v2/payments/captures/${encodeURIComponent(captureId)}/refund`, {
@@ -891,7 +898,15 @@ class PayPalPaymentProvider extends AbstractPaymentProvider<Options> {
         debug_id: debugId,
         message: error?.message,
       })
-      throw error
+      // Surface the real reason to the admin. Medusa's error handler masks any
+      // non-MedusaError as a generic "An unknown error occurred." in production,
+      // which hid the actual PayPal failure from the order refund UI.
+      throw error instanceof MedusaError
+        ? error
+        : new MedusaError(
+            MedusaError.Types.UNEXPECTED_STATE,
+            error?.message || "PayPal refund failed."
+          )
     }
   }
 

package/src/modules/paypal/service.ts

@@ -495,17 +495,20 @@ class PayPalModuleService extends MedusaService({
 
   async createOnboardingLink(input?: { email?: string; products?: string[]; env?: Environment }) {
     const { onboarding } = await this.ensureSettingsDefaults()
-    // 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 =
       input?.env === "sandbox" || input?.env === "live"
         ? input.env
         : await this.getCurrentEnvironment()
+    // 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
+    // exchanges the auth code for seller credentials server-side, relays the
+    // result to the opener, and closes the popup. We pin the environment in the
+    // URL so the bridge saves credentials under the correct env even though
+    // PayPal's redirect carries no auth/session.
+    const return_url = `${String(onboarding.backend_url || "").replace(/\/$/, "")}/store/paypal/onboard-return?env=${env}`
     const partner_merchant_id = await this.getPartnerMerchantId(env)
 
     const email = (input?.email || "").trim()
@@ -653,9 +656,23 @@ class PayPalModuleService extends MedusaService({
     sharedId: string
     env?: "sandbox" | "live"
   }) {
-    await this.saveOnboardCallback({ authCode: input.authCode, sharedId: input.sharedId })
-
     const env = (input.env || (await this.getCurrentEnvironment())) as Environment
+
+    // Onboarding completion can now arrive via several redundant paths
+    // (partner.js's onboardingCallback in the opener, the return_url bridge that
+    // runs inside the popup, and admin status polling). PayPal's authorization
+    // code is single-use, so a second exchange of the same code would fail with
+    // invalid_grant. If we already exchanged this exact code and hold seller
+    // credentials for this environment, treat the duplicate as a success no-op.
+    const existingRow = await this.getCurrentRow()
+    if (existingRow && existingRow.auth_code === input.authCode) {
+      const existingCreds = this.getEnvCreds(existingRow, env)
+      if (existingCreds.clientId && existingCreds.clientSecret) {
+        return
+      }
+    }
+
+    await this.saveOnboardCallback({ authCode: input.authCode, sharedId: input.sharedId })
     const baseUrl = env === "live" ? "https://api-m.paypal.com" : "https://api-m.sandbox.paypal.com"
 
     const { onboarding } = await this.ensureSettingsDefaults()
@@ -690,6 +707,16 @@ class PayPalModuleService extends MedusaService({
     }
 
     if (!tokenRes.ok) {
+      // Two redundant completion paths can race to exchange the same single-use
+      // code; the loser gets invalid_grant. If credentials were saved in the
+      // meantime (the other path won), the onboarding actually succeeded.
+      const racedRow = await this.getCurrentRow()
+      if (racedRow) {
+        const racedCreds = this.getEnvCreds(racedRow, env)
+        if (racedCreds.clientId && racedCreds.clientSecret) {
+          return
+        }
+      }
       throw new Error(
         `PayPal authorization_code token exchange failed (${tokenRes.status}): ${tokenText || JSON.stringify(tokenJson)}`
       )

package/src/modules/paypal/utils/amounts.ts

@@ -36,6 +36,42 @@ export function getCurrencyExponent(currencyCode: string) {
   return 2
 }
 
+/**
+ * Coerce a Medusa monetary amount into a plain JS number.
+ *
+ * Medusa passes amounts to payment providers as a `BigNumberInput`, which can be
+ * a plain `number`/`string`, a `BigNumber` instance (exposing a `numeric`
+ * getter), or the serialized raw form `{ value, precision }`. A naive
+ * `Number(amount)` returns `NaN` for the object forms — which silently turns a
+ * partial refund/capture into a full one and produces a `…-NaN` idempotency key.
+ */
+export function toAmountNumber(amount: unknown): number {
+  if (amount === null || amount === undefined) {
+    return 0
+  }
+  if (typeof amount === "number") {
+    return Number.isFinite(amount) ? amount : 0
+  }
+  if (typeof amount === "string") {
+    const parsed = Number(amount)
+    return Number.isFinite(parsed) ? parsed : 0
+  }
+  if (typeof amount === "object") {
+    const obj = amount as Record<string, unknown>
+    // Medusa BigNumber instance.
+    if (typeof obj.numeric === "number" && Number.isFinite(obj.numeric)) {
+      return obj.numeric
+    }
+    // Serialized raw form: { value: "20", precision: 20 }.
+    if (obj.value !== undefined && obj.value !== null) {
+      const parsed = Number(obj.value)
+      return Number.isFinite(parsed) ? parsed : 0
+    }
+  }
+  const fallback = Number(amount as never)
+  return Number.isFinite(fallback) ? fallback : 0
+}
+
 /**
  * Format a Medusa amount for the PayPal REST API.
  *