@easypayment/medusa-payment-paypal 0.9.16 → 0.9.18

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

@@ -10,7 +10,11 @@ import {
 import { getPayPalApiBase } from "../../../../modules/paypal/utils/paypal-auth"
 import { paypalFetch } from "../../../../modules/paypal/utils/paypal-fetch"
 import type PayPalModuleService from "../../../../modules/paypal/service"
-import { isPayPalProviderId } from "../../../../modules/paypal/utils/provider-ids"
+import {
+  findPayPalSessionForCart,
+  getStoredPayPalOrderId,
+  updatePayPalSessionData,
+} from "../../../../modules/paypal/utils/payment-session"
 
 const BN_CODE = "MBJTechnolabs_SI_SPB"
 
@@ -32,61 +36,35 @@ function resolveIdempotencyKey(req: MedusaRequest, suffix: string, fallback: str
   return fallback || `pp-${suffix}-${randomUUID()}`
 }
 
+// Persist the PayPal order id onto the cart's PayPal payment session so that
+// capture-order can bind the capture to the order this cart created. Resolved
+// through the Payment module service (the previous direct-container resolve of
+// "payment_collection"/"payment_session" did not exist in the request scope, so
+// the id was silently never stored and every capture failed fail-closed).
 async function attachPayPalOrderToSession(
   req: MedusaRequest,
   cartId: string,
   orderId: string
 ) {
-  try {
-    const paymentCollectionService = req.scope.resolve("payment_collection") as any
-    const paymentSessionService = req.scope.resolve("payment_session") as any
-
-    const pc = await paymentCollectionService.retrieveByCartId(cartId).catch(() => null)
-    if (!pc?.id) {
-      return
-    }
-
-    const sessions = await paymentSessionService.list({ payment_collection_id: pc.id })
-    const paypalSession = sessions?.find((s: any) => isPayPalProviderId(s.provider_id))
-    if (!paypalSession) {
-      return
-    }
-
-    await paymentSessionService.update(paypalSession.id, {
-      amount: paypalSession.amount,
-      data: {
-        ...(paypalSession.data || {}),
-        paypal: {
-          ...((paypalSession.data || {}).paypal || {}),
-          order_id: orderId,
-        },
-      },
-    })
-  } catch {
+  const session = await findPayPalSessionForCart(cartId, req.scope)
+  if (!session) {
+    return
   }
+  await updatePayPalSessionData(
+    session.session_id,
+    {
+      paypal: {
+        ...(session.session_data.paypal || {}),
+        order_id: orderId,
+      },
+    },
+    req.scope
+  )
 }
 
 async function getExistingPayPalOrderId(req: MedusaRequest, cartId: string) {
-  try {
-    const paymentCollectionService = req.scope.resolve("payment_collection") as any
-    const paymentSessionService = req.scope.resolve("payment_session") as any
-
-    const pc = await paymentCollectionService.retrieveByCartId(cartId).catch(() => null)
-    if (!pc?.id) {
-      return null
-    }
-
-    const sessions = await paymentSessionService.list({ payment_collection_id: pc.id })
-    const paypalSession = sessions?.find((s: any) => isPayPalProviderId(s.provider_id))
-    if (!paypalSession) {
-      return null
-    }
-
-    const paypalData = (paypalSession.data || {}).paypal || {}
-    return paypalData.order_id ? String(paypalData.order_id) : null
-  } catch {
-    return null
-  }
+  const session = await findPayPalSessionForCart(cartId, req.scope)
+  return getStoredPayPalOrderId(session?.session_data)
 }
 
 function resolveReturnUrl(req: MedusaRequest) {

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

@@ -8,6 +8,11 @@ import {
   normalizeEventVersion,
   processPayPalWebhookEvent,
 } from "../../../../modules/paypal/webhook-processor"
+import {
+  composeVerifyRequestBody,
+  rawBodyToString,
+  resolveWebhookEventJson,
+} from "../../../../modules/paypal/utils/webhook-verify"
 
 const REPLAY_WINDOW_MINUTES = (() => {
   const v = Number(process.env.PAYPAL_WEBHOOK_REPLAY_WINDOW_MINUTES)
@@ -110,7 +115,8 @@ async function verifyWebhookSignature(
   paypal: PayPalModuleService,
   environment: string,
   body: Record<string, unknown>,
-  headers: Record<string, string | string[] | undefined>
+  headers: Record<string, string | string[] | undefined>,
+  rawBody: string | null
 ): Promise<void> {
   const settings = await paypal.getSettings().catch(() => ({ data: {} }))
   const webhookId = resolveWebhookId(
@@ -131,17 +137,16 @@ async function verifyWebhookSignature(
 
   const accessToken = await paypal.getAppAccessToken()
 
-  const verifyPayload = {
+  const verifyFields = {
     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 certUrl = verifyPayload.cert_url
+  const certUrl = verifyFields.cert_url
   if (
     certUrl &&
     !certUrl.startsWith("https://www.paypal.com/") &&
@@ -151,21 +156,29 @@ async function verifyWebhookSignature(
     throw new Error("Invalid paypal-cert-url: must originate from paypal.com")
   }
 
-  const missing = Object.entries(verifyPayload)
-    .filter(([k, v]) => k !== "webhook_id" && k !== "webhook_event" && !v)
+  const missing = Object.entries(verifyFields)
+    .filter(([k, v]) => k !== "webhook_id" && !v)
     .map(([k]) => k)
 
   if (missing.length > 0) {
     throw new Error(`Missing required PayPal webhook headers: ${missing.join(", ")}`)
   }
 
+  // Use the raw bytes PayPal signed for `webhook_event` whenever available
+  // (preserved by the route's `bodyParser: { preserveRawBody: true }`); fall
+  // back to serializing the parsed body so verification still runs if it isn't.
+  const requestBody = composeVerifyRequestBody(
+    verifyFields,
+    resolveWebhookEventJson(rawBody, body)
+  )
+
   const resp = await paypalFetch(`${base}/v1/notifications/verify-webhook-signature`, {
     method: "POST",
     headers: {
       Authorization: `Bearer ${accessToken}`,
       "Content-Type": "application/json",
     },
-    body: JSON.stringify(verifyPayload),
+    body: requestBody,
   })
 
   const json = await resp.json().catch(() => ({}))
@@ -214,7 +227,8 @@ export async function POST(req: MedusaRequest, res: MedusaResponse) {
 
   try {
     const creds = await paypal.getActiveCredentials()
-    await verifyWebhookSignature(paypal, creds.environment, payload, req.headers)
+    const rawBody = rawBodyToString((req as unknown as { rawBody?: unknown }).rawBody)
+    await verifyWebhookSignature(paypal, creds.environment, payload, req.headers, rawBody)
   } catch (e: any) {
     console.error("[PayPal] webhook: signature verification failed:", e?.message)
     return res

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

@@ -32,6 +32,12 @@ import {
 import type PayPalModuleService from "../service"
 import { getPayPalWebhookActionAndData } from "./webhook-utils"
 import { paypalFetch } from "../utils/paypal-fetch"
+import {
+  extractCaptureStatus,
+  isCaptureCompleted,
+  isRefundFailureStatus,
+  mapPayPalCaptureStatus,
+} from "./status-utils"
 
 type Options = {}
 
@@ -154,13 +160,7 @@ class PayPalPaymentProvider 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
+    return mapPayPalCaptureStatus(status)
   }
 
   private mapAuthorizationStatus(status?: string) {
@@ -587,15 +587,19 @@ class PayPalPaymentProvider extends AbstractPaymentProvider<Options> {
       }
     }
 
-    const requestId = this.getIdempotencyKey(input, `capture-${orderId}`)
     const { amount, currencyCode } = await this.normalizePaymentData(input)
+    // Include the amount in the idempotency suffix: PayPal deduplicates by
+    // PayPal-Request-Id, so two sequential partial captures of the same order
+    // that share an upstream idempotency_key would otherwise collide and the
+    // second capture would silently return the first one's result.
+    const requestId = this.getIdempotencyKey(input, `capture-${orderId}-${amount}`)
     let debugId: string | null = null
 
     try {
       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: {
             ...(input.data || {}),
@@ -648,26 +652,35 @@ class PayPalPaymentProvider extends AbstractPaymentProvider<Options> {
       const captureValue = amount > 0
         ? formatAmountForPayPal(amount, currencyCode || "EUR")
         : null
-      const capturePayload =
-        captureValue
-          ? {
-              amount: {
-                currency_code: currencyCode || "EUR",
-                value: captureValue,
-              },
-              ...(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`
+      // `amount` and `is_final_capture` are only valid on the authorizations
+      // capture endpoint. The orders capture endpoint always captures the FULL
+      // order and silently ignores an `amount` body — so sending a partial
+      // amount there would over-capture while we record the (smaller) requested
+      // value. Route partial captures to 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",
@@ -691,6 +704,19 @@ class PayPalPaymentProvider 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 (e.g. 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 : []
@@ -752,7 +778,12 @@ class PayPalPaymentProvider extends AbstractPaymentProvider<Options> {
       )
     }
 
-    const requestId = this.getIdempotencyKey(input, `refund-${captureId}`)
+    // 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)}`
+    )
 
     const currencyOverride = await this.resolveCurrencyOverride()
     const currencyCode = normalizeCurrencyCode(
@@ -804,6 +835,19 @@ class PayPalPaymentProvider extends AbstractPaymentProvider<Options> {
       }
 
       const refund = JSON.parse(ppText)
+
+      // 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)) {
+        throw new Error(
+          `PayPal refund did not succeed (status=${refundStatus}). The refund was not issued.` +
+            (debugId ? ` debug_id=${debugId}` : "")
+        )
+      }
+
       const existingRefunds = Array.isArray(paypalData.refunds) ? paypalData.refunds : []
       const refundEntry = {
         id: refund?.id,

package/src/modules/paypal/payment-provider/status-utils.ts

@@ -0,0 +1,59 @@
+/**
+ * Pure mapping/validation helpers for PayPal capture & refund resource statuses.
+ *
+ * Kept free of any container/IO dependencies so the money-flow decisions (what
+ * counts as a settled capture, when a refund must be rejected, how a PayPal
+ * status maps onto a Medusa payment status) can be unit-tested in isolation.
+ */
+
+/** Map a PayPal capture status onto a Medusa payment status. */
+export function mapPayPalCaptureStatus(
+  status?: string
+): "captured" | "pending" | "error" | "canceled" | null {
+  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"
+  // A partially-refunded capture is still a captured payment — only a portion of
+  // the funds was returned. Mapping it to "canceled" would wrongly unwind a live
+  // capture, so it must stay "captured". A full refund/reversal does unwind it.
+  if (normalized === "PARTIALLY_REFUNDED") return "captured"
+  if (["REFUNDED", "REVERSED"].includes(normalized)) return "canceled"
+  return null
+}
+
+/**
+ * Effective status of a PayPal capture resource.
+ *
+ * The orders-capture response nests the capture under
+ * `purchase_units[].payments.captures[]` — the order's own top-level status can
+ * read COMPLETED while the capture is still PENDING — whereas the
+ * authorizations-capture response is the capture object directly. Prefer the
+ * nested capture status, falling back to the top level.
+ */
+export function extractCaptureStatus(resource: any): string {
+  if (!resource || typeof resource !== "object") return ""
+  const nested = resource?.purchase_units?.[0]?.payments?.captures?.[0]?.status
+  return String(nested ?? resource.status ?? "").toUpperCase()
+}
+
+/**
+ * True only when a capture resource is COMPLETED. A 2xx HTTP response does NOT
+ * imply this: PayPal returns 201 for PENDING (pending review / eCheck),
+ * DECLINED, and FAILED captures too.
+ */
+export function isCaptureCompleted(resource: any): boolean {
+  return extractCaptureStatus(resource) === "COMPLETED"
+}
+
+/**
+ * Refund statuses that mean the refund did NOT go through and must never be
+ * recorded as a successful refund. PENDING is intentionally excluded: PayPal
+ * processes refunds asynchronously and a pending refund settles later.
+ */
+export function isRefundFailureStatus(status?: string): boolean {
+  return ["FAILED", "CANCELLED", "CANCELED", "DENIED"].includes(
+    String(status || "").toUpperCase()
+  )
+}

package/src/modules/paypal/service.ts

@@ -899,7 +899,9 @@ class PayPalModuleService extends MedusaService({
       console.warn("[PayPal] saveAndHydrateSellerCredentials lookup failed:", e?.message || e)
     }
 
-    return await this.getStatus(env)
+    // This is a write context (credentials were just saved), so it is allowed to
+    // backfill the seller profile if it is still missing.
+    return await this.getStatus(env, { hydrateMissingProfile: true })
   }
 
   private async resolveWebhookUrl() {
@@ -1028,7 +1030,19 @@ class PayPalModuleService extends MedusaService({
     )}`
   }
 
-  async getStatus(envOverride?: Environment) {
+  /**
+   * Report the current connection status.
+   *
+   * `hydrateMissingProfile` is opt-in and OFF by default: status is read on
+   * `GET /admin/paypal/status` (and other read-only routes), where it must be a
+   * safe, side-effect-free read. The seller-profile backfill makes an outbound
+   * PayPal call and persists to the DB, so it only runs from write contexts
+   * (e.g. saving credentials) that explicitly request it.
+   */
+  async getStatus(
+    envOverride?: Environment,
+    opts: { hydrateMissingProfile?: boolean } = {}
+  ) {
     const row = await this.getCurrentRow()
     const env = envOverride ?? (await this.getCurrentEnvironment())
 
@@ -1041,7 +1055,7 @@ class PayPalModuleService extends MedusaService({
     let sellerEmail: string | null = c.sellerEmail || row.seller_email || null
     let sellerMerchantId: string | null = c.sellerMerchantId || row.seller_merchant_id || null
 
-    if (!sellerEmail && hasCreds) {
+    if (!sellerEmail && hasCreds && opts.hydrateMissingProfile) {
       try {
         const hydrated = await this.fetchSellerProfileFromDirectCredentials(env)
         if (hydrated.sellerEmail || hydrated.sellerMerchantId) {

package/src/modules/paypal/utils/payment-session.ts

@@ -0,0 +1,104 @@
+import type { IPaymentModuleService } from "@medusajs/framework/types"
+import { Modules } from "@medusajs/framework/utils"
+import { isPayPalProviderId } from "./provider-ids"
+
+/**
+ * Shared PayPal payment-session helpers.
+ *
+ * `create-order` and `capture-order` must agree on (a) which payment session
+ * belongs to a cart and (b) how the PayPal order id is stored/read on it —
+ * otherwise the capture's fail-closed binding (the order id stored by
+ * create-order must equal the one being captured) can never be satisfied.
+ * Keeping the logic here, resolved through the Payment module service
+ * (`Modules.PAYMENT`), guarantees both routes use the same, correct path.
+ */
+
+export type PayPalCartSession = {
+  session_id: string
+  session_data: Record<string, any>
+  session_status: string
+}
+
+/**
+ * Resolve the cart's active PayPal payment session (wallet or card). When a
+ * cart has more than one PayPal session, the most recently created one wins —
+ * both create-order and capture-order rely on this same selection so they
+ * always read and write the same session.
+ */
+export async function findPayPalSessionForCart(
+  cartId: string,
+  scope: any
+): Promise<PayPalCartSession | null> {
+  try {
+    const query = 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",
+      ],
+      filters: { id: cartId },
+    })
+    const cart = carts?.[0]
+    const sessions = cart?.payment_collection?.payment_sessions || []
+    const session = sessions
+      .filter((s: any) => isPayPalProviderId(s.provider_id))
+      .sort(
+        (a: any, b: any) =>
+          new Date(b.created_at || 0).getTime() - new Date(a.created_at || 0).getTime()
+      )[0]
+
+    if (!session) return null
+
+    return {
+      session_id: session.id,
+      session_data: (session.data || {}) as Record<string, any>,
+      session_status: session.status,
+    }
+  } catch (e: any) {
+    console.warn("[PayPal] findPayPalSessionForCart failed:", e?.message)
+    return null
+  }
+}
+
+/**
+ * Read the PayPal order id stored on a session's `data`. Accepts both the
+ * canonical `data.paypal.order_id` and the legacy top-level `data.order_id`.
+ * Returns null when none is present.
+ */
+export function getStoredPayPalOrderId(
+  sessionData?: Record<string, any> | null
+): string | null {
+  const paypal = (sessionData?.paypal || {}) as Record<string, unknown>
+  const id = String(paypal.order_id || sessionData?.order_id || "")
+  return id || null
+}
+
+/**
+ * Shallow-merge `extraData` into a payment session's `data`, preserving the
+ * session's amount/currency. Callers that update the nested `paypal` object are
+ * responsible for spreading its existing keys (see `getStoredPayPalOrderId`).
+ */
+export async function updatePayPalSessionData(
+  sessionId: string,
+  extraData: Record<string, any>,
+  scope: any
+): Promise<void> {
+  try {
+    const paymentModule = scope.resolve(Modules.PAYMENT) as IPaymentModuleService
+    const [existing] = await paymentModule.listPaymentSessions({ id: [sessionId] }, { take: 1 })
+    const mergedData = { ...(existing?.data || {}), ...extraData }
+    await (paymentModule as any).updatePaymentSession({
+      id: sessionId,
+      data: mergedData,
+      amount: existing?.amount,
+      currency_code: existing?.currency_code,
+    })
+  } catch (e: any) {
+    console.error("[PayPal] updatePayPalSessionData failed:", e?.message)
+  }
+}