@easypayment/medusa-payment-paypal 0.9.17 → 0.9.19

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

@@ -8,6 +8,7 @@ import type PayPalModuleService from "../../../../modules/paypal/service"
 type Body = {
   email?: string
   products?: string[]
+  environment?: "sandbox" | "live"
 }
 
 export async function POST(req: AuthenticatedMedusaRequest, res: MedusaResponse) {
@@ -19,10 +20,15 @@ export async function POST(req: AuthenticatedMedusaRequest, res: MedusaResponse)
         ? String(req.auth_context.user_metadata.email)
         : undefined
     const email = authEmail ?? body.email ?? "admin@paypal.com"
+    const env =
+      body.environment === "sandbox" || body.environment === "live"
+        ? body.environment
+        : undefined
 
     const link = await paypal.createOnboardingLink({
       email,
       products: body.products,
+      env,
     })
 
     return res.json({

package/src/api/middlewares.ts

@@ -2,6 +2,15 @@ import { defineMiddlewares } from "@medusajs/framework/http"
 
 export default defineMiddlewares({
   routes: [
+    {
+      // Keep the exact bytes PayPal signed (`req.rawBody`) so webhook signature
+      // verification hashes the original payload, not a re-serialized copy. This
+      // entry must precede the "/store/paypal/:path*" catch-all below.
+      matcher: "/store/paypal/webhook",
+      method: ["POST"],
+      bodyParser: { preserveRawBody: true },
+      middlewares: [],
+    },
     {
       matcher: "/store/paypal-complete",
       middlewares: [],

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

@@ -493,10 +493,15 @@ class PayPalModuleService extends MedusaService({
     return await this.getCurrentRow()
   }
 
-  async createOnboardingLink(input?: { email?: string; products?: string[] }) {
+  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`
-    const env = await this.getCurrentEnvironment()
+    // 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()
     const partner_merchant_id = await this.getPartnerMerchantId(env)
 
     const email = (input?.email || "").trim()
@@ -899,7 +904,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 +1035,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 +1060,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/secret-crypto.ts

@@ -1,4 +1,4 @@
-import { createCipheriv, createDecipheriv, createHash, randomBytes } from "crypto"
+import { createCipheriv, createDecipheriv, createHash, randomBytes, scryptSync } from "crypto"
 
 /**
  * Opt-in encryption-at-rest for PayPal secrets (client secret, app access
@@ -8,15 +8,35 @@ import { createCipheriv, createDecipheriv, createHash, randomBytes } from "crypt
  * default), both functions are the identity — behavior is byte-for-byte
  * unchanged, so existing deployments are unaffected.
  *
- * Format: `enc:v1:<iv_b64>:<tag_b64>:<ciphertext_b64>` using AES-256-GCM
- * (authenticated, so tampering is detected on decrypt). Legacy plaintext values
- * (no prefix) are returned as-is on decrypt, so secrets stored before
- * encryption was enabled keep working and are upgraded on the next save.
+ * Format (current): `enc:v2:<salt_b64>:<iv_b64>:<tag_b64>:<ciphertext_b64>`
+ * using AES-256-GCM with a key derived via **scrypt** over the env key and a
+ * random per-secret salt. scrypt is a memory-hard KDF, so even a low-entropy
+ * passphrase resists brute-force/rainbow-table attacks (the previous unsalted,
+ * single-pass SHA-256 did not).
+ *
+ * Format (legacy): `enc:v1:<iv_b64>:<tag_b64>:<ciphertext_b64>` with an
+ * unsalted SHA-256 key. Still decryptable so secrets written before the KDF
+ * upgrade keep working; they are transparently upgraded to v2 on the next save.
+ *
+ * Legacy plaintext values (no prefix) are returned as-is on decrypt.
  */
-const PREFIX = "enc:v1:"
+const PREFIX_V2 = "enc:v2:"
+const PREFIX_V1 = "enc:v1:"
+
+// scrypt cost parameters. N=2^14 with r=8 needs ~16MB (128*N*r), which stays
+// under Node's default 32MB scrypt memory limit while imposing a meaningful
+// per-derivation cost. Derived keys are cached, so this runs at most once per
+// (env key, salt) pair rather than on every encrypt/decrypt.
+const SCRYPT_N = 16384
+const SCRYPT_R = 8
+const SCRYPT_P = 1
+const KEY_LEN = 32
+const SALT_LEN = 16
 
 let cachedRaw: string | undefined
-let cachedKey: Buffer | null = null
+let cachedRawKey: string | null = null
+let legacyV1Key: Buffer | null = null
+const v2KeyCache = new Map<string, Buffer>()
 
 /**
  * `@types/node` 22.0-22.6 typed `Buffer` as `Buffer<ArrayBufferLike>`, which is
@@ -27,41 +47,75 @@ let cachedKey: Buffer | null = null
  */
 const bytes = (view: Buffer): Uint8Array => view as unknown as Uint8Array
 
-function getKey(): Buffer | null {
+/** The raw env key (trimmed), or null when encryption is disabled. */
+function getRawKey(): string | null {
   const raw = (process.env.PAYPAL_ENCRYPTION_KEY || "").trim()
   if (raw !== cachedRaw) {
     cachedRaw = raw
-    // Accept a key of any length/format; derive a stable 32-byte AES key.
-    cachedKey = raw ? createHash("sha256").update(raw).digest() : null
+    cachedRawKey = raw || null
+    // The unsalted SHA-256 key is only needed to decrypt legacy v1 values.
+    legacyV1Key = raw ? createHash("sha256").update(raw).digest() : null
+    v2KeyCache.clear()
+  }
+  return cachedRawKey
+}
+
+/** Derive (and cache) the AES key for a v2 secret from the env key + salt. */
+function deriveV2Key(raw: string, salt: Buffer): Buffer {
+  const cacheKey = `${raw}::${salt.toString("base64")}`
+  let key = v2KeyCache.get(cacheKey)
+  if (!key) {
+    key = scryptSync(raw, bytes(salt), KEY_LEN, {
+      N: SCRYPT_N,
+      r: SCRYPT_R,
+      p: SCRYPT_P,
+    })
+    v2KeyCache.set(cacheKey, key)
   }
-  return cachedKey
+  return key
+}
+
+function gcmDecrypt(key: Buffer, ivB64: string, tagB64: string, ctB64: string): string {
+  const decipher = createDecipheriv("aes-256-gcm", bytes(key), bytes(Buffer.from(ivB64, "base64")))
+  decipher.setAuthTag(bytes(Buffer.from(tagB64, "base64")))
+  const plaintext = Buffer.concat([
+    bytes(decipher.update(bytes(Buffer.from(ctB64, "base64")))),
+    bytes(decipher.final()),
+  ])
+  return plaintext.toString("utf8")
 }
 
 export function isSecretEncryptionEnabled(): boolean {
-  return getKey() !== null
+  return getRawKey() !== null
 }
 
 export function isEncrypted(value: unknown): boolean {
-  return typeof value === "string" && value.startsWith(PREFIX)
+  return (
+    typeof value === "string" &&
+    (value.startsWith(PREFIX_V2) || value.startsWith(PREFIX_V1))
+  )
 }
 
 /**
  * Encrypt a secret for storage. Returns the input unchanged when no key is
- * configured or when the value is empty/already encrypted.
+ * configured or when the value is empty/already encrypted. Always writes the
+ * current (v2) format.
  */
 export function encryptSecret<T extends string | null | undefined>(value: T): T | string {
   if (!value) {
     return value
   }
-  const key = getKey()
-  if (!key || isEncrypted(value)) {
+  const raw = getRawKey()
+  if (!raw || isEncrypted(value)) {
     return value
   }
+  const salt = randomBytes(SALT_LEN)
+  const key = deriveV2Key(raw, salt)
   const iv = randomBytes(12)
   const cipher = createCipheriv("aes-256-gcm", bytes(key), bytes(iv))
   const ciphertext = Buffer.concat([bytes(cipher.update(String(value), "utf8")), bytes(cipher.final())])
   const tag = cipher.getAuthTag()
-  return `${PREFIX}${iv.toString("base64")}:${tag.toString("base64")}:${ciphertext.toString("base64")}`
+  return `${PREFIX_V2}${salt.toString("base64")}:${iv.toString("base64")}:${tag.toString("base64")}:${ciphertext.toString("base64")}`
 }
 
 /**
@@ -73,22 +127,31 @@ export function decryptSecret<T extends string | null | undefined>(value: T): T
   if (!value || !isEncrypted(value)) {
     return value
   }
-  const key = getKey()
-  if (!key) {
+  const raw = getRawKey()
+  if (!raw) {
     throw new Error(
       "PayPal secret is encrypted but PAYPAL_ENCRYPTION_KEY is not set. Restore the key to decrypt stored credentials."
     )
   }
-  const body = String(value).slice(PREFIX.length)
+
+  if (String(value).startsWith(PREFIX_V2)) {
+    const body = String(value).slice(PREFIX_V2.length)
+    const [saltB64, ivB64, tagB64, ctB64] = body.split(":")
+    if (!saltB64 || !ivB64 || !tagB64 || !ctB64) {
+      throw new Error("PayPal secret ciphertext is malformed.")
+    }
+    const key = deriveV2Key(raw, Buffer.from(saltB64, "base64"))
+    return gcmDecrypt(key, ivB64, tagB64, ctB64)
+  }
+
+  // Legacy v1 (unsalted SHA-256 key).
+  const body = String(value).slice(PREFIX_V1.length)
   const [ivB64, tagB64, ctB64] = body.split(":")
   if (!ivB64 || !tagB64 || !ctB64) {
     throw new Error("PayPal secret ciphertext is malformed.")
   }
-  const decipher = createDecipheriv("aes-256-gcm", bytes(key), bytes(Buffer.from(ivB64, "base64")))
-  decipher.setAuthTag(bytes(Buffer.from(tagB64, "base64")))
-  const plaintext = Buffer.concat([
-    bytes(decipher.update(bytes(Buffer.from(ctB64, "base64")))),
-    bytes(decipher.final()),
-  ])
-  return plaintext.toString("utf8")
+  if (!legacyV1Key) {
+    throw new Error("PayPal secret is encrypted but PAYPAL_ENCRYPTION_KEY is not set.")
+  }
+  return gcmDecrypt(legacyV1Key, ivB64, tagB64, ctB64)
 }

package/src/modules/paypal/utils/webhook-verify.ts

@@ -0,0 +1,61 @@
+/**
+ * Helpers for calling PayPal's `verify-webhook-signature` API correctly.
+ *
+ * PayPal computes the expected signature over the EXACT bytes it transmitted.
+ * Re-serializing the parsed body (`JSON.stringify(req.body)`) can change those
+ * bytes — key ordering, non-ASCII escaping (`José` vs `José`), number and
+ * whitespace formatting — which makes verification intermittently return
+ * FAILURE for legitimate webhooks. When the original raw body is available we
+ * inject it verbatim as `webhook_event`; otherwise we fall back to serializing
+ * the parsed body so behavior never regresses.
+ */
+
+/** Normalize Medusa's `req.rawBody` (a Buffer when `preserveRawBody` is set) to a string. */
+export function rawBodyToString(rawBody: unknown): string | null {
+  if (rawBody == null) {
+    return null
+  }
+  if (typeof rawBody === "string") {
+    return rawBody.length > 0 ? rawBody : null
+  }
+  if (Buffer.isBuffer(rawBody)) {
+    return rawBody.length > 0 ? rawBody.toString("utf8") : null
+  }
+  if (rawBody instanceof Uint8Array) {
+    return rawBody.length > 0 ? Buffer.from(rawBody).toString("utf8") : null
+  }
+  return null
+}
+
+/**
+ * Compose the JSON request body for `verify-webhook-signature`.
+ *
+ * `fields` are the transmission headers + webhook_id; `webhookEventJson` is the
+ * raw webhook body verbatim (preferred) or a serialized fallback. Undefined /
+ * null header values are omitted. The webhook event is concatenated as raw JSON
+ * (not re-encoded) so the bytes PayPal hashes match what it signed.
+ */
+export function composeVerifyRequestBody(
+  fields: Record<string, string | undefined | null>,
+  webhookEventJson: string
+): string {
+  const head = Object.entries(fields)
+    .filter(([, v]) => v !== undefined && v !== null)
+    .map(([k, v]) => `${JSON.stringify(k)}:${JSON.stringify(v)}`)
+    .join(",")
+  return `{${head}${head ? "," : ""}"webhook_event":${webhookEventJson}}`
+}
+
+/**
+ * Pick the bytes to use for `webhook_event`: the raw body when present and
+ * non-blank, otherwise a JSON serialization of the parsed body.
+ */
+export function resolveWebhookEventJson(
+  rawBody: string | null | undefined,
+  parsedBody: unknown
+): string {
+  if (typeof rawBody === "string" && rawBody.trim().length > 0) {
+    return rawBody
+  }
+  return JSON.stringify(parsedBody ?? {})
+}