@easypayment/medusa-paypal-ui 1.0.49 → 1.0.50

package/dist/order.d.cts

@@ -0,0 +1,66 @@
+/**
+ * Server-safe helpers for displaying PayPal payments on order / confirmation
+ * pages.
+ *
+ * This module is intentionally free of React and any client-only code, so it
+ * can be imported from Next.js **server components** (e.g. the order
+ * confirmation page) without pulling in the checkout UI.
+ *
+ * @example
+ * import { getPaymentLabel, fetchPayPalConfig } from "@easypayment/medusa-paypal-ui/order"
+ *
+ * // In the (async) server component that renders the payment method:
+ * const titles = await fetchPayPalConfig({
+ *   baseUrl: process.env.NEXT_PUBLIC_MEDUSA_BACKEND_URL!,
+ *   publishableApiKey: process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY,
+ * })
+ *
+ * <Text>
+ *   {getPaymentLabel(
+ *     payment.provider_id,
+ *     paymentInfoMap[payment.provider_id]?.title,
+ *     titles
+ *   )}
+ * </Text>
+ */
+declare const PAYPAL_WALLET_PROVIDER_ID = "pp_paypal_paypal";
+declare const PAYPAL_CARD_PROVIDER_ID = "pp_paypal_card_paypal_card";
+type PayPalPaymentInfo = {
+    title: string;
+};
+/** Built-in fallback titles, used only when admin titles aren't supplied. */
+declare const paypalPaymentInfoMap: Record<string, PayPalPaymentInfo>;
+/** Admin-configured titles, as returned by `GET /store/paypal/config`. */
+type PayPalConfigTitles = {
+    paypal_title?: string | null;
+    card_title?: string | null;
+};
+/** True when the provider id belongs to this PayPal plugin. */
+declare function isPayPalProviderId(providerId?: string | null): boolean;
+/**
+ * Null-safe payment label resolver for order / confirmation pages.
+ *
+ * Precedence for the PayPal providers: **admin-configured title** (`titles`,
+ * from {@link fetchPayPalConfig}) → built-in default. For any other provider:
+ * `fallback` → raw id. Never throws on an unknown / missing provider, which is
+ * what causes the common `Cannot read properties of undefined (reading 'title')`
+ * crash on the order confirmation page.
+ *
+ * @param titles Admin titles so the order page shows the same labels configured
+ *   in Medusa Admin → Settings → PayPal (e.g. a custom "Credit or Debit Card").
+ */
+declare function getPaymentLabel(providerId: string | undefined | null, fallback?: string, titles?: PayPalConfigTitles): string;
+/**
+ * Fetch the admin-configured PayPal titles from the storefront API
+ * (`GET /store/paypal/config`). Server-safe (uses the global `fetch`).
+ *
+ * Returns `{}` on any error/network failure so callers can fall back to the
+ * built-in defaults without their own try/catch.
+ */
+declare function fetchPayPalConfig(opts: {
+    baseUrl: string;
+    publishableApiKey?: string;
+    signal?: AbortSignal;
+}): Promise<PayPalConfigTitles>;
+
+export { PAYPAL_CARD_PROVIDER_ID, PAYPAL_WALLET_PROVIDER_ID, type PayPalConfigTitles, type PayPalPaymentInfo, fetchPayPalConfig, getPaymentLabel, isPayPalProviderId, paypalPaymentInfoMap };

package/dist/order.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Server-safe helpers for displaying PayPal payments on order / confirmation
+ * pages.
+ *
+ * This module is intentionally free of React and any client-only code, so it
+ * can be imported from Next.js **server components** (e.g. the order
+ * confirmation page) without pulling in the checkout UI.
+ *
+ * @example
+ * import { getPaymentLabel, fetchPayPalConfig } from "@easypayment/medusa-paypal-ui/order"
+ *
+ * // In the (async) server component that renders the payment method:
+ * const titles = await fetchPayPalConfig({
+ *   baseUrl: process.env.NEXT_PUBLIC_MEDUSA_BACKEND_URL!,
+ *   publishableApiKey: process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY,
+ * })
+ *
+ * <Text>
+ *   {getPaymentLabel(
+ *     payment.provider_id,
+ *     paymentInfoMap[payment.provider_id]?.title,
+ *     titles
+ *   )}
+ * </Text>
+ */
+declare const PAYPAL_WALLET_PROVIDER_ID = "pp_paypal_paypal";
+declare const PAYPAL_CARD_PROVIDER_ID = "pp_paypal_card_paypal_card";
+type PayPalPaymentInfo = {
+    title: string;
+};
+/** Built-in fallback titles, used only when admin titles aren't supplied. */
+declare const paypalPaymentInfoMap: Record<string, PayPalPaymentInfo>;
+/** Admin-configured titles, as returned by `GET /store/paypal/config`. */
+type PayPalConfigTitles = {
+    paypal_title?: string | null;
+    card_title?: string | null;
+};
+/** True when the provider id belongs to this PayPal plugin. */
+declare function isPayPalProviderId(providerId?: string | null): boolean;
+/**
+ * Null-safe payment label resolver for order / confirmation pages.
+ *
+ * Precedence for the PayPal providers: **admin-configured title** (`titles`,
+ * from {@link fetchPayPalConfig}) → built-in default. For any other provider:
+ * `fallback` → raw id. Never throws on an unknown / missing provider, which is
+ * what causes the common `Cannot read properties of undefined (reading 'title')`
+ * crash on the order confirmation page.
+ *
+ * @param titles Admin titles so the order page shows the same labels configured
+ *   in Medusa Admin → Settings → PayPal (e.g. a custom "Credit or Debit Card").
+ */
+declare function getPaymentLabel(providerId: string | undefined | null, fallback?: string, titles?: PayPalConfigTitles): string;
+/**
+ * Fetch the admin-configured PayPal titles from the storefront API
+ * (`GET /store/paypal/config`). Server-safe (uses the global `fetch`).
+ *
+ * Returns `{}` on any error/network failure so callers can fall back to the
+ * built-in defaults without their own try/catch.
+ */
+declare function fetchPayPalConfig(opts: {
+    baseUrl: string;
+    publishableApiKey?: string;
+    signal?: AbortSignal;
+}): Promise<PayPalConfigTitles>;
+
+export { PAYPAL_CARD_PROVIDER_ID, PAYPAL_WALLET_PROVIDER_ID, type PayPalConfigTitles, type PayPalPaymentInfo, fetchPayPalConfig, getPaymentLabel, isPayPalProviderId, paypalPaymentInfoMap };

package/dist/order.mjs

@@ -0,0 +1,56 @@
+// src/order.ts
+var PAYPAL_WALLET_PROVIDER_ID = "pp_paypal_paypal";
+var PAYPAL_CARD_PROVIDER_ID = "pp_paypal_card_paypal_card";
+var paypalPaymentInfoMap = {
+  [PAYPAL_WALLET_PROVIDER_ID]: { title: "PayPal" },
+  [PAYPAL_CARD_PROVIDER_ID]: { title: "Credit or Debit Card" }
+};
+function isPayPalProviderId(providerId) {
+  return providerId === PAYPAL_WALLET_PROVIDER_ID || providerId === PAYPAL_CARD_PROVIDER_ID;
+}
+function getPaymentLabel(providerId, fallback, titles) {
+  if (!providerId) {
+    return fallback ?? "";
+  }
+  if (providerId === PAYPAL_WALLET_PROVIDER_ID) {
+    return titles?.paypal_title?.trim() || paypalPaymentInfoMap[PAYPAL_WALLET_PROVIDER_ID].title;
+  }
+  if (providerId === PAYPAL_CARD_PROVIDER_ID) {
+    return titles?.card_title?.trim() || paypalPaymentInfoMap[PAYPAL_CARD_PROVIDER_ID].title;
+  }
+  return fallback ?? providerId;
+}
+async function fetchPayPalConfig(opts) {
+  const { baseUrl, publishableApiKey, signal } = opts;
+  if (!baseUrl) {
+    return {};
+  }
+  try {
+    const res = await fetch(`${baseUrl.replace(/\/$/, "")}/store/paypal/config`, {
+      headers: {
+        accept: "application/json",
+        ...publishableApiKey ? { "x-publishable-api-key": publishableApiKey } : {}
+      },
+      signal
+    });
+    if (!res.ok) {
+      return {};
+    }
+    const cfg = await res.json();
+    return {
+      paypal_title: typeof cfg.paypal_title === "string" ? cfg.paypal_title : void 0,
+      card_title: typeof cfg.card_title === "string" ? cfg.card_title : void 0
+    };
+  } catch {
+    return {};
+  }
+}
+export {
+  PAYPAL_CARD_PROVIDER_ID,
+  PAYPAL_WALLET_PROVIDER_ID,
+  fetchPayPalConfig,
+  getPaymentLabel,
+  isPayPalProviderId,
+  paypalPaymentInfoMap
+};
+//# sourceMappingURL=order.mjs.map

package/dist/order.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/order.ts"],"sourcesContent":["/**\r\n * Server-safe helpers for displaying PayPal payments on order / confirmation\r\n * pages.\r\n *\r\n * This module is intentionally free of React and any client-only code, so it\r\n * can be imported from Next.js **server components** (e.g. the order\r\n * confirmation page) without pulling in the checkout UI.\r\n *\r\n * @example\r\n * import { getPaymentLabel, fetchPayPalConfig } from \"@easypayment/medusa-paypal-ui/order\"\r\n *\r\n * // In the (async) server component that renders the payment method:\r\n * const titles = await fetchPayPalConfig({\r\n *   baseUrl: process.env.NEXT_PUBLIC_MEDUSA_BACKEND_URL!,\r\n *   publishableApiKey: process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY,\r\n * })\r\n *\r\n * <Text>\r\n *   {getPaymentLabel(\r\n *     payment.provider_id,\r\n *     paymentInfoMap[payment.provider_id]?.title,\r\n *     titles\r\n *   )}\r\n * </Text>\r\n */\r\n\r\nexport const PAYPAL_WALLET_PROVIDER_ID = \"pp_paypal_paypal\"\r\nexport const PAYPAL_CARD_PROVIDER_ID = \"pp_paypal_card_paypal_card\"\r\n\r\nexport type PayPalPaymentInfo = { title: string }\r\n\r\n/** Built-in fallback titles, used only when admin titles aren't supplied. */\r\nexport const paypalPaymentInfoMap: Record<string, PayPalPaymentInfo> = {\r\n  [PAYPAL_WALLET_PROVIDER_ID]: { title: \"PayPal\" },\r\n  [PAYPAL_CARD_PROVIDER_ID]: { title: \"Credit or Debit Card\" },\r\n}\r\n\r\n/** Admin-configured titles, as returned by `GET /store/paypal/config`. */\r\nexport type PayPalConfigTitles = {\r\n  paypal_title?: string | null\r\n  card_title?: string | null\r\n}\r\n\r\n/** True when the provider id belongs to this PayPal plugin. */\r\nexport function isPayPalProviderId(providerId?: string | null): boolean {\r\n  return (\r\n    providerId === PAYPAL_WALLET_PROVIDER_ID ||\r\n    providerId === PAYPAL_CARD_PROVIDER_ID\r\n  )\r\n}\r\n\r\n/**\r\n * Null-safe payment label resolver for order / confirmation pages.\r\n *\r\n * Precedence for the PayPal providers: **admin-configured title** (`titles`,\r\n * from {@link fetchPayPalConfig}) → built-in default. For any other provider:\r\n * `fallback` → raw id. Never throws on an unknown / missing provider, which is\r\n * what causes the common `Cannot read properties of undefined (reading 'title')`\r\n * crash on the order confirmation page.\r\n *\r\n * @param titles Admin titles so the order page shows the same labels configured\r\n *   in Medusa Admin → Settings → PayPal (e.g. a custom \"Credit or Debit Card\").\r\n */\r\nexport function getPaymentLabel(\r\n  providerId: string | undefined | null,\r\n  fallback?: string,\r\n  titles?: PayPalConfigTitles\r\n): string {\r\n  if (!providerId) {\r\n    return fallback ?? \"\"\r\n  }\r\n  if (providerId === PAYPAL_WALLET_PROVIDER_ID) {\r\n    return (\r\n      titles?.paypal_title?.trim() ||\r\n      paypalPaymentInfoMap[PAYPAL_WALLET_PROVIDER_ID].title\r\n    )\r\n  }\r\n  if (providerId === PAYPAL_CARD_PROVIDER_ID) {\r\n    return (\r\n      titles?.card_title?.trim() ||\r\n      paypalPaymentInfoMap[PAYPAL_CARD_PROVIDER_ID].title\r\n    )\r\n  }\r\n  return fallback ?? providerId\r\n}\r\n\r\n/**\r\n * Fetch the admin-configured PayPal titles from the storefront API\r\n * (`GET /store/paypal/config`). Server-safe (uses the global `fetch`).\r\n *\r\n * Returns `{}` on any error/network failure so callers can fall back to the\r\n * built-in defaults without their own try/catch.\r\n */\r\nexport async function fetchPayPalConfig(opts: {\r\n  baseUrl: string\r\n  publishableApiKey?: string\r\n  signal?: AbortSignal\r\n}): Promise<PayPalConfigTitles> {\r\n  const { baseUrl, publishableApiKey, signal } = opts\r\n  if (!baseUrl) {\r\n    return {}\r\n  }\r\n  try {\r\n    const res = await fetch(`${baseUrl.replace(/\\/$/, \"\")}/store/paypal/config`, {\r\n      headers: {\r\n        accept: \"application/json\",\r\n        ...(publishableApiKey ? { \"x-publishable-api-key\": publishableApiKey } : {}),\r\n      },\r\n      signal,\r\n    })\r\n    if (!res.ok) {\r\n      return {}\r\n    }\r\n    const cfg = (await res.json()) as Record<string, unknown>\r\n    return {\r\n      paypal_title:\r\n        typeof cfg.paypal_title === \"string\" ? cfg.paypal_title : undefined,\r\n      card_title:\r\n        typeof cfg.card_title === \"string\" ? cfg.card_title : undefined,\r\n    }\r\n  } catch {\r\n    return {}\r\n  }\r\n}\r\n"],"mappings":";AA0BO,IAAM,4BAA4B;AAClC,IAAM,0BAA0B;AAKhC,IAAM,uBAA0D;AAAA,EACrE,CAAC,yBAAyB,GAAG,EAAE,OAAO,SAAS;AAAA,EAC/C,CAAC,uBAAuB,GAAG,EAAE,OAAO,uBAAuB;AAC7D;AASO,SAAS,mBAAmB,YAAqC;AACtE,SACE,eAAe,6BACf,eAAe;AAEnB;AAcO,SAAS,gBACd,YACA,UACA,QACQ;AACR,MAAI,CAAC,YAAY;AACf,WAAO,YAAY;AAAA,EACrB;AACA,MAAI,eAAe,2BAA2B;AAC5C,WACE,QAAQ,cAAc,KAAK,KAC3B,qBAAqB,yBAAyB,EAAE;AAAA,EAEpD;AACA,MAAI,eAAe,yBAAyB;AAC1C,WACE,QAAQ,YAAY,KAAK,KACzB,qBAAqB,uBAAuB,EAAE;AAAA,EAElD;AACA,SAAO,YAAY;AACrB;AASA,eAAsB,kBAAkB,MAIR;AAC9B,QAAM,EAAE,SAAS,mBAAmB,OAAO,IAAI;AAC/C,MAAI,CAAC,SAAS;AACZ,WAAO,CAAC;AAAA,EACV;AACA,MAAI;AACF,UAAM,MAAM,MAAM,MAAM,GAAG,QAAQ,QAAQ,OAAO,EAAE,CAAC,wBAAwB;AAAA,MAC3E,SAAS;AAAA,QACP,QAAQ;AAAA,QACR,GAAI,oBAAoB,EAAE,yBAAyB,kBAAkB,IAAI,CAAC;AAAA,MAC5E;AAAA,MACA;AAAA,IACF,CAAC;AACD,QAAI,CAAC,IAAI,IAAI;AACX,aAAO,CAAC;AAAA,IACV;AACA,UAAM,MAAO,MAAM,IAAI,KAAK;AAC5B,WAAO;AAAA,MACL,cACE,OAAO,IAAI,iBAAiB,WAAW,IAAI,eAAe;AAAA,MAC5D,YACE,OAAO,IAAI,eAAe,WAAW,IAAI,aAAa;AAAA,IAC1D;AAAA,EACF,QAAQ;AACN,WAAO,CAAC;AAAA,EACV;AACF;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@easypayment/medusa-paypal-ui",
-  "version": "1.0.49",
+  "version": "1.0.50",
   "description": "Enterprise Gold PayPal UI module for Medusa v2 storefront (Next.js)",
   "license": "MIT",
   "type": "module",
@@ -20,6 +20,11 @@
       "import": "./dist/index.mjs",
       "require": "./dist/index.cjs"
     },
+    "./order": {
+      "types": "./dist/order.d.ts",
+      "import": "./dist/order.mjs",
+      "require": "./dist/order.cjs"
+    },
     "./package.json": "./package.json"
   },
   "peerDependencies": {

package/src/adapters/MedusaNextPayPalAdapter.tsx

@@ -6,6 +6,7 @@ import { PayPalAdvancedCard } from "../components/PayPalAdvancedCard"
 import { PayPalProvider } from "../components/PayPalProvider"
 import { PayPalSmartButtons } from "../components/PayPalSmartButtons"
 import { usePayPalConfig } from "../hooks/usePayPalConfig"
+import { isNextRedirectError } from "../client/paypal"
 
 const DEFAULT_PAYPAL_PROVIDER_ID = "pp_paypal_paypal"
 const DEFAULT_PAYPAL_CARD_PROVIDER_ID = "pp_paypal_card_paypal_card"
@@ -109,9 +110,19 @@ export function MedusaNextPayPalAdapter(props: MedusaNextPayPalAdapterProps) {
   const handlePaid = useCallback(
     (captureResult: unknown) => {
       onPaid?.(captureResult)
-      onSuccess?.(cartId)
+      // onSuccess usually calls placeOrder(), which redirects on success. Run it
+      // without blocking the spinner, but surface real failures so a captured
+      // payment never ends silently with no order and no error shown.
+      Promise.resolve(onSuccess?.(cartId)).catch((e: unknown) => {
+        if (isNextRedirectError(e)) return
+        onError?.(
+          e instanceof Error
+            ? e.message
+            : "Your payment was taken but the order could not be finalized. Please contact support before paying again."
+        )
+      })
     },
-    [cartId, onPaid, onSuccess]
+    [cartId, onPaid, onSuccess, onError]
   )
 
   if (!shouldRender) return null

package/src/client/http.ts

@@ -19,6 +19,8 @@ function toHeaderRecord(headers?: RequestInit["headers"]): Record<string, string
   return { ...headers }
 }
 
+const DEFAULT_TIMEOUT_MS = 30000
+
 export function createHttpClient(opts: HttpOptions) {
   const base = opts.baseUrl.replace(/\/+$/, "")
 
@@ -33,8 +35,36 @@ export function createHttpClient(opts: HttpOptions) {
       headers["x-publishable-api-key"] = opts.publishableApiKey
     }
 
-    const res = await fetch(url, { ...init, headers, credentials: "include" })
-    const text = await res.text().catch(() => "")
+    // Always enforce a timeout so a hung backend can't leave the checkout
+    // spinner up forever, while still honouring a caller-provided abort signal.
+    const controller = new AbortController()
+    let timedOut = false
+    const timer = setTimeout(() => {
+      timedOut = true
+      controller.abort()
+    }, DEFAULT_TIMEOUT_MS)
+    const callerSignal = init?.signal
+    if (callerSignal) {
+      if (callerSignal.aborted) {
+        controller.abort()
+      } else {
+        callerSignal.addEventListener("abort", () => controller.abort(), { once: true })
+      }
+    }
+
+    let res: Response
+    let text: string
+    try {
+      res = await fetch(url, { ...init, headers, credentials: "include", signal: controller.signal })
+      text = await res.text().catch(() => "")
+    } catch (e) {
+      if (timedOut) {
+        throw new Error("[PayPal] Request timed out. Please check your connection and try again.")
+      }
+      throw e
+    } finally {
+      clearTimeout(timer)
+    }
 
     if (!res.ok) {
       if (res.status === 401) {
@@ -47,9 +77,25 @@ export function createHttpClient(opts: HttpOptions) {
           "[PayPal] Forbidden (403) — this request is not allowed. Check your CORS and API key settings."
         )
       }
-      throw new Error(
-        text.slice(0, 500).replace(/<[^>]*>/g, "") || `Request failed (${res.status})`
-      )
+      // Prefer the backend's clean { message, request_id } JSON. For 5xx, do not
+      // surface raw server internals to end users — log them and show a generic
+      // message (with a correlation id when available).
+      type ErrBody = { message?: unknown; request_id?: unknown }
+      let parsed: ErrBody | null = null
+      try {
+        parsed = text ? (JSON.parse(text) as ErrBody) : null
+      } catch {
+        parsed = null
+      }
+      const backendMessage = typeof parsed?.message === "string" ? parsed.message : ""
+      const requestId = typeof parsed?.request_id === "string" ? parsed.request_id : ""
+      if (res.status >= 500) {
+        console.error(`[PayPal] ${path} failed (${res.status})`, text.slice(0, 1000))
+        throw new Error(
+          `Payment service error${requestId ? ` (ref ${requestId})` : ""}. Please try again or contact support.`
+        )
+      }
+      throw new Error(backendMessage || `Request failed (${res.status})`)
     }
     if (!text) {
       throw new Error(`[PayPal] Empty response body from ${path} (${res.status})`)

package/src/client/paypal.ts

@@ -1,11 +1,27 @@
 import type { PayPalConfig, PayPalSettingsResponse } from "./types"
 import { createHttpClient, type HttpOptions } from "./http"
 
+/**
+ * True when an error is a Next.js navigation signal (`redirect()` / `notFound()`
+ * from a server action). These MUST be re-thrown / ignored, never shown as an
+ * error — a successful `placeOrder()` redirect surfaces as one of these.
+ */
+export function isNextRedirectError(e: unknown): boolean {
+  if (!e || typeof e !== "object") {
+    return false
+  }
+  const digest = (e as { digest?: unknown }).digest
+  return (
+    typeof digest === "string" &&
+    (digest.startsWith("NEXT_REDIRECT") || digest === "NEXT_NOT_FOUND")
+  )
+}
+
 export async function markPaymentComplete(
   baseUrl: string,
   cartId: string,
   publishableApiKey?: string
-): Promise<Record<string, any>> {
+): Promise<{ ok: boolean } & Record<string, any>> {
   try {
     const resp = await fetch(`${baseUrl.replace(/\/$/, "")}/store/paypal-complete`, {
       method: "POST",
@@ -17,10 +33,14 @@ export async function markPaymentComplete(
       credentials: "include",
     })
     const data = await resp.json().catch(() => ({}))
-    return data || {}
+    if (!resp.ok) {
+      console.warn("[PayPal] paypal-complete returned", resp.status, data)
+      return { ok: false, ...(data || {}) }
+    }
+    return { ok: true, ...(data || {}) }
   } catch (e) {
     console.warn("[PayPal] paypal-complete call failed:", e)
-    return {}
+    return { ok: false }
   }
 }
 

package/src/components/PayPalAdvancedCard.tsx

@@ -62,10 +62,12 @@ function SubmitButton({
   disabled,
   label,
   onSubmit,
+  onSubmitError,
 }: {
   disabled: boolean
   label: string
   onSubmit: () => void
+  onSubmitError: (message: string) => void
 }) {
   const { cardFieldsForm } = usePayPalCardFields()
   const isDisabled = disabled || !cardFieldsForm
@@ -76,7 +78,17 @@ function SubmitButton({
       disabled={isDisabled}
       onClick={() => {
         onSubmit()
-        cardFieldsForm?.submit()
+        // submit() can reject (network / tokenization / 3DS) WITHOUT firing the
+        // provider onError, which would otherwise leave the "Processing…"
+        // overlay stuck forever. Always catch it and surface the error.
+        const submitted = cardFieldsForm?.submit()
+        if (submitted && typeof submitted.catch === "function") {
+          submitted.catch((e: unknown) => {
+            onSubmitError(
+              e instanceof Error ? e.message : "Card payment failed. Please try again."
+            )
+          })
+        }
       }}
       style={{
         width: "100%",
@@ -321,6 +333,11 @@ export function PayPalAdvancedCard(props: {
               setError(null)
               setSubmitting(true)
             }}
+            onSubmitError={(msg) => {
+              setError(msg)
+              onError?.(msg)
+              setSubmitting(false)
+            }}
           />
 
           {error && (

package/src/components/PayPalPaymentSection.tsx

@@ -6,6 +6,7 @@ import { PayPalAdvancedCard } from "./PayPalAdvancedCard"
 import { PayPalProvider } from "./PayPalProvider"
 import { PayPalSmartButtons } from "./PayPalSmartButtons"
 import { usePayPalConfig } from "../hooks/usePayPalConfig"
+import { isNextRedirectError } from "../client/paypal"
 
 export const PAYPAL_WALLET_PROVIDER_ID = "pp_paypal_paypal" as const
 export const PAYPAL_CARD_PROVIDER_ID = "pp_paypal_card_paypal_card" as const
@@ -142,9 +143,19 @@ export function PayPalPaymentSection({
   const handlePaid = useCallback(
     (captureResult: unknown) => {
       onPaid?.(captureResult)
-      onSuccess?.(cartId)
+      // onSuccess usually calls placeOrder(), which redirects on success. Run it
+      // without blocking the spinner, but surface real failures so a captured
+      // payment never ends silently with no order and no error shown.
+      Promise.resolve(onSuccess?.(cartId)).catch((e: unknown) => {
+        if (isNextRedirectError(e)) return
+        onError?.(
+          e instanceof Error
+            ? e.message
+            : "Your payment was taken but the order could not be finalized. Please contact support before paying again."
+        )
+      })
     },
-    [cartId, onPaid, onSuccess]
+    [cartId, onPaid, onSuccess, onError]
   )
 
   if (!shouldRender) return null

package/src/order.ts

@@ -0,0 +1,124 @@
+/**
+ * Server-safe helpers for displaying PayPal payments on order / confirmation
+ * pages.
+ *
+ * This module is intentionally free of React and any client-only code, so it
+ * can be imported from Next.js **server components** (e.g. the order
+ * confirmation page) without pulling in the checkout UI.
+ *
+ * @example
+ * import { getPaymentLabel, fetchPayPalConfig } from "@easypayment/medusa-paypal-ui/order"
+ *
+ * // In the (async) server component that renders the payment method:
+ * const titles = await fetchPayPalConfig({
+ *   baseUrl: process.env.NEXT_PUBLIC_MEDUSA_BACKEND_URL!,
+ *   publishableApiKey: process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY,
+ * })
+ *
+ * <Text>
+ *   {getPaymentLabel(
+ *     payment.provider_id,
+ *     paymentInfoMap[payment.provider_id]?.title,
+ *     titles
+ *   )}
+ * </Text>
+ */
+
+export const PAYPAL_WALLET_PROVIDER_ID = "pp_paypal_paypal"
+export const PAYPAL_CARD_PROVIDER_ID = "pp_paypal_card_paypal_card"
+
+export type PayPalPaymentInfo = { title: string }
+
+/** Built-in fallback titles, used only when admin titles aren't supplied. */
+export const paypalPaymentInfoMap: Record<string, PayPalPaymentInfo> = {
+  [PAYPAL_WALLET_PROVIDER_ID]: { title: "PayPal" },
+  [PAYPAL_CARD_PROVIDER_ID]: { title: "Credit or Debit Card" },
+}
+
+/** Admin-configured titles, as returned by `GET /store/paypal/config`. */
+export type PayPalConfigTitles = {
+  paypal_title?: string | null
+  card_title?: string | null
+}
+
+/** True when the provider id belongs to this PayPal plugin. */
+export function isPayPalProviderId(providerId?: string | null): boolean {
+  return (
+    providerId === PAYPAL_WALLET_PROVIDER_ID ||
+    providerId === PAYPAL_CARD_PROVIDER_ID
+  )
+}
+
+/**
+ * Null-safe payment label resolver for order / confirmation pages.
+ *
+ * Precedence for the PayPal providers: **admin-configured title** (`titles`,
+ * from {@link fetchPayPalConfig}) → built-in default. For any other provider:
+ * `fallback` → raw id. Never throws on an unknown / missing provider, which is
+ * what causes the common `Cannot read properties of undefined (reading 'title')`
+ * crash on the order confirmation page.
+ *
+ * @param titles Admin titles so the order page shows the same labels configured
+ *   in Medusa Admin → Settings → PayPal (e.g. a custom "Credit or Debit Card").
+ */
+export function getPaymentLabel(
+  providerId: string | undefined | null,
+  fallback?: string,
+  titles?: PayPalConfigTitles
+): string {
+  if (!providerId) {
+    return fallback ?? ""
+  }
+  if (providerId === PAYPAL_WALLET_PROVIDER_ID) {
+    return (
+      titles?.paypal_title?.trim() ||
+      paypalPaymentInfoMap[PAYPAL_WALLET_PROVIDER_ID].title
+    )
+  }
+  if (providerId === PAYPAL_CARD_PROVIDER_ID) {
+    return (
+      titles?.card_title?.trim() ||
+      paypalPaymentInfoMap[PAYPAL_CARD_PROVIDER_ID].title
+    )
+  }
+  return fallback ?? providerId
+}
+
+/**
+ * Fetch the admin-configured PayPal titles from the storefront API
+ * (`GET /store/paypal/config`). Server-safe (uses the global `fetch`).
+ *
+ * Returns `{}` on any error/network failure so callers can fall back to the
+ * built-in defaults without their own try/catch.
+ */
+export async function fetchPayPalConfig(opts: {
+  baseUrl: string
+  publishableApiKey?: string
+  signal?: AbortSignal
+}): Promise<PayPalConfigTitles> {
+  const { baseUrl, publishableApiKey, signal } = opts
+  if (!baseUrl) {
+    return {}
+  }
+  try {
+    const res = await fetch(`${baseUrl.replace(/\/$/, "")}/store/paypal/config`, {
+      headers: {
+        accept: "application/json",
+        ...(publishableApiKey ? { "x-publishable-api-key": publishableApiKey } : {}),
+      },
+      signal,
+    })
+    if (!res.ok) {
+      return {}
+    }
+    const cfg = (await res.json()) as Record<string, unknown>
+    return {
+      paypal_title:
+        typeof cfg.paypal_title === "string" ? cfg.paypal_title : undefined,
+      card_title:
+        typeof cfg.card_title === "string" ? cfg.card_title : undefined,
+    }
+  } catch {
+    return {}
+  }
+}