@easypayment/medusa-paypal-ui 1.0.39 → 1.0.41

package/README.md

@@ -1,118 +1,295 @@
-# @easypayment/medusa-paypal-ui
+<div align="center">
 
-PayPal checkout UI for Medusa v2 storefronts.
+<h1>🅿 medusa-paypal-frontend</h1>
 
-A React storefront package for integrating **PayPal Wallet** and **PayPal Advanced Card Payments** into a Medusa + Next.js checkout.
+<p><strong>Production-ready PayPal checkout UI for Medusa v2 storefronts</strong></p>
+
+<p>
+  <a href="https://www.npmjs.com/package/@easypayment/medusa-paypal-ui"><img src="https://img.shields.io/npm/v/@easypayment/medusa-paypal-ui?color=blue&label=npm" alt="npm version" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-green.svg" alt="License: MIT" /></a>
+  <a href="https://medusajs.com"><img src="https://img.shields.io/badge/Medusa-v2-9b59b6" alt="Medusa v2" /></a>
+  <a href="https://nextjs.org"><img src="https://img.shields.io/badge/Next.js-14%2B-black" alt="Next.js" /></a>
+</p>
+
+<p>PayPal Smart Buttons · Advanced Card Fields · Built-in loading states · Admin-controlled settings</p>
+
+</div>
 
 ---
 
 ## Overview
 
-`@easypayment/medusa-paypal-ui` is used on the **storefront** side and works with the backend package:
+`@easypayment/medusa-paypal-ui` is a React UI package that connects your Next.js (App Router) storefront to the `medusa-paypal-backend` plugin. It ships fully self-contained checkout components — your storefront only needs a single component and one hook added to the existing payment step.
 
-- `@easypayment/medusa-paypal`
+| Feature | Details |
+|---|---|
+| **PayPal Smart Buttons** | Wallet-based checkout via `pp_paypal_paypal` |
+| **Advanced Card Fields** | Hosted PCI-compliant card inputs via `pp_paypal_card_paypal_card` |
+| **Admin-driven config** | Enable/disable providers and set labels from Medusa Admin — no code changes needed |
+| **Built-in UX** | Loading spinners, error display, and currency warnings are all handled internally |
+| **5-minute config cache** | `/store/paypal/config` is fetched once per session — no redundant requests |
 
-It is designed to plug into the Medusa Next.js starter checkout and adds:
+---
 
-- PayPal Wallet rendering in checkout
-- PayPal Advanced Card rendering in checkout
-- runtime config loading from the Medusa backend
-- PayPal-specific payment session initialization
-- success and error callbacks for order placement
+## Table of Contents
+
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Environment Variables](#environment-variables)
+- [Integration Guide](#integration-guide)
+  - [Step 1 — Add the import](#step-1-add-the-import)
+  - [Step 2 — Add session loading state](#step-2-add-session-loading-state)
+  - [Step 3 — Add the config hook](#step-3-add-the-config-hook)
+  - [Step 4 — Update setPaymentMethod](#step-4-update-setpaymentmethod)
+  - [Step 5 — Filter the payment method list](#step-5-filter-the-payment-method-list)
+  - [Step 6 — Inject admin-configured titles](#step-6-inject-admin-configured-titles)
+  - [Step 7 — Render the PayPal UI](#step-7-render-the-paypal-ui)
+  - [Step 8 — Disable the Continue button](#step-8-disable-the-continue-button)
+  - [Step 9 — Fix the summary label](#step-9-fix-the-summary-label)
+- [Complete File](#complete-file)
+- [Testing](#testing)
 
 ---
 
-## Compatibility
+## Requirements
 
-| Component | Version |
-|---|---|
-| Next.js | `15.3.9` |
-| React | `19.0.4` |
-| Storefront starter | `medusa-next@1.0.3` |
-| UI package | `@easypayment/medusa-paypal-ui@1.0.32` |
+- **Node.js** 18+
+- **Next.js** 14+ with App Router
+- **`medusa-paypal-backend`** installed and running on your Medusa server
+- A PayPal account connected in Medusa Admin → Settings → PayPal → PayPal Connection
 
 ---
 
 ## Installation
 
-Install the UI package in your storefront:
-
 ```bash
 npm install @easypayment/medusa-paypal-ui
 ```
 
-If your project does not already include the PayPal React SDK, install it as well:
-
 ```bash
-npm install @paypal/react-paypal-js
+yarn add @easypayment/medusa-paypal-ui
 ```
 
-Or with pnpm:
+---
+
+## Environment Variables
 
-```bash
-pnpm add @easypayment/medusa-paypal-ui @paypal/react-paypal-js
+Add the following to your storefront `.env.local`. Use separate values for development and production.
+
+```env
+# ── Development ───────────────────────────────────────────────────────────────
+NEXT_PUBLIC_MEDUSA_BACKEND_URL=http://localhost:9000
+NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY=pk_...
+
+# ── Production ────────────────────────────────────────────────────────────────
+NEXT_PUBLIC_MEDUSA_BACKEND_URL=https://your-medusa-server.com
+NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY=pk_...
 ```
 
-Or with yarn:
+> **Where to get the publishable key:**
+> Medusa Admin → **Settings → API Key Management → Create API Key**
 
-```bash
-yarn add @easypayment/medusa-paypal-ui @paypal/react-paypal-js
+---
+
+## Integration Guide
+
+All changes are made to a single file in your storefront:
+
+```
+src/modules/checkout/components/payment/index.tsx
 ```
 
+> **Prefer copy-paste?** Skip to [Complete File](#complete-file) for a ready-to-use drop-in replacement.
+
 ---
 
-## Storefront Environment Variables
+### Step 1 — Add the import
 
-Add the required variables to your storefront `.env.local` or `.env` file:
+Add this import alongside your existing imports at the top of the file:
 
-```env
-MEDUSA_BACKEND_URL=http://localhost:9000
-NEXT_PUBLIC_MEDUSA_BACKEND_URL=http://localhost:9000
-NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY=pk_your_publishable_key
-NEXT_PUBLIC_BASE_URL=http://localhost:8000
-NEXT_PUBLIC_DEFAULT_REGION=us
+```tsx
+import {
+  PayPalPaymentSection,
+  isPayPalProviderId,
+  usePayPalPaymentMethods,
+} from "@easypayment/medusa-paypal-ui"
+```
+
+---
+
+### Step 2 — Add session loading state
+
+Inside the `Payment` component, add one new state variable alongside your existing `useState` calls:
+
+```tsx
+const [paypalSessionLoading, setPaypalSessionLoading] = useState(false)
 ```
 
-Other storefront variables such as Stripe, revalidation, or cloud image settings are unrelated to this PayPal package and can stay as they are in the Medusa starter template.
+This is set to `true` while `initiatePaymentSession` is running, allowing the PayPal UI to show a "Setting up payment…" spinner in place of the buttons during that window.
 
 ---
 
-## Backend Requirements
+### Step 3 — Add the config hook
 
-Your Medusa backend must:
+Add this hook call inside the component, directly after the `const isOpen = ...` line:
 
-- have `@easypayment/medusa-paypal` installed
-- register both PayPal providers
-- expose `/store/paypal/config`
-- have PayPal configured from Medusa Admin
+```tsx
+const { paypalEnabled, paypalTitle, cardEnabled, cardTitle } =
+  usePayPalPaymentMethods({
+    baseUrl: process.env.NEXT_PUBLIC_MEDUSA_BACKEND_URL!,
+    publishableApiKey: process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY,
+    cartId: cart.id,
+    enabled: isOpen,
+  })
+```
 
-Typical backend provider IDs:
+This fetches live settings from your Medusa backend — provider enabled/disabled flags and admin-configured display labels. Responses are cached for 5 minutes per cart so there are no duplicate network requests.
 
-```txt
-pp_paypal_paypal
-pp_paypal_card_paypal_card
+Passing `enabled: isOpen` ensures the fetch only runs when the payment step is actually visible.
+
+---
+
+### Step 4 — Update `setPaymentMethod`
+
+Replace your existing `setPaymentMethod` function with the following. The key addition is setting `paypalSessionLoading` while the session is being created:
+
+```tsx
+const setPaymentMethod = async (method: string) => {
+  setError(null)
+  setSelectedPaymentMethod(method)
+  if (isStripeLike(method) || isPayPalProviderId(method)) {
+    if (isPayPalProviderId(method)) setPaypalSessionLoading(true)
+    try {
+      await initiatePaymentSession(cart, { provider_id: method })
+    } finally {
+      setPaypalSessionLoading(false)
+    }
+  }
+}
 ```
 
+> **Note:** `isStripeLike` comes from your storefront's `@lib/constants`. If your project does not use Stripe, remove the `isStripeLike(method)` condition and keep only `isPayPalProviderId(method)`.
+
 ---
 
-## What Changed in Checkout Integration
+### Step 5 — Filter the payment method list
 
-Compared with the original Medusa starter payment step, the PayPal integration adds the following behavior:
+In your `RadioGroup`, add a `.filter()` before `.map()` to hide providers that have been disabled by the admin in the PayPal settings panel:
 
-- imports `MedusaNextPayPalAdapter`
-- imports `placeOrder` for PayPal success completion
-- defines PayPal provider IDs
-- initializes payment sessions for PayPal methods
-- fetches runtime config from `/store/paypal/config`
-- hides PayPal methods when backend config disables them
-- uses backend titles for PayPal Wallet and Card
-- disables the default submit button for PayPal because PayPal handles its own submit flow
+```tsx
+{availablePaymentMethods
+  .filter((m) => {
+    if (m.id === "pp_paypal_paypal" && !paypalEnabled) return false
+    if (m.id === "pp_paypal_card_paypal_card" && !cardEnabled) return false
+    return true
+  })
+  .map((paymentMethod) => (
+    // ... your existing rendering code, unchanged
+  ))}
+```
 
 ---
 
-## Checkout Integration Example
+### Step 6 — Inject admin-configured titles
 
-Below is the updated payment-step pattern based on the current storefront integration:
+Inside your `.map()`, pass an overridden `paymentInfoMap` to the `PaymentContainer` component so the radio button labels reflect whatever the admin has set in Medusa Admin → Settings → PayPal → PayPal Settings:
+
+```tsx
+<PaymentContainer
+  paymentInfoMap={{
+    ...paymentInfoMap,
+    "pp_paypal_paypal": {
+      ...(paymentInfoMap["pp_paypal_paypal"] || {}),
+      title: paypalTitle,
+    },
+    "pp_paypal_card_paypal_card": {
+      ...(paymentInfoMap["pp_paypal_card_paypal_card"] || {}),
+      title: cardTitle,
+    },
+  }}
+  paymentProviderId={paymentMethod.id}
+  selectedPaymentOptionId={selectedPaymentMethod}
+/>
+```
+
+---
+
+### Step 7 — Render the PayPal UI
+
+After the closing `</RadioGroup>` tag, add the `PayPalPaymentSection` component:
+
+```tsx
+<PayPalPaymentSection
+  cartId={cart.id}
+  selectedProviderId={selectedPaymentMethod}
+  baseUrl={process.env.NEXT_PUBLIC_MEDUSA_BACKEND_URL!}
+  publishableApiKey={process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY}
+  sessionLoading={paypalSessionLoading}
+  onSuccess={async () => {
+    await placeOrder(cart.id)
+  }}
+  onError={(msg) => setError(msg)}
+/>
+```
+
+This single component manages everything: config loading, Smart Buttons, Advanced Card fields, spinners, and errors. When a non-PayPal provider is selected it renders nothing, so it is safe to keep it in the tree at all times.
+
+> **Critical — `onSuccess` must call `placeOrder`**
+>
+> `placeOrder` is the Next.js Server Action exported from `@lib/data/cart`. It **must** run server-side — it is the only mechanism that can clear the httpOnly cart cookie set by the server. Replacing it with a client-side `fetch` to `/store/carts/:id/complete` will complete the order in Medusa but leave the cart cookie intact, breaking the storefront session.
+
+---
+
+### Step 8 — Disable the Continue button
+
+`PayPalPaymentSection` renders its own Pay button. The storefront's "Continue to review" button must be disabled when PayPal is selected to avoid checkout flow confusion.
+
+Add `isPayPalProviderId(selectedPaymentMethod)` to your `Button` component's `disabled` prop:
+
+```tsx
+<Button
+  size="large"
+  className="mt-6"
+  onClick={handleSubmit}
+  isLoading={isLoading}
+  disabled={
+    (isStripeLike(selectedPaymentMethod) && !cardComplete) ||
+    (!selectedPaymentMethod && !paidByGiftcard) ||
+    isPayPalProviderId(selectedPaymentMethod)  // ← add this line
+  }
+  data-testid="submit-payment-button"
+>
+  {!activeSession && isStripeLike(selectedPaymentMethod)
+    ? "Enter card details"
+    : "Continue to review"}
+</Button>
+```
+
+---
+
+### Step 9 — Fix the summary label
+
+In the collapsed summary view (shown after the customer has selected a payment method), replace any hardcoded PayPal label with the admin-configured title from the hook:
+
+```tsx
+<Text
+  className="txt-medium text-ui-fg-subtle"
+  data-testid="payment-method-summary"
+>
+  {activeSession?.provider_id === "pp_paypal_paypal"
+    ? paypalTitle
+    : activeSession?.provider_id === "pp_paypal_card_paypal_card"
+    ? cardTitle
+    : paymentInfoMap[activeSession?.provider_id]?.title ||
+      activeSession?.provider_id}
+</Text>
+```
+
+---
+
+## Complete File
+
+The following is a complete, working replacement for your payment step file with all changes from the guide above already applied. Copy and replace the entire contents of `src/modules/checkout/components/payment/index.tsx`.
 
 ```tsx
 "use client"
@@ -122,7 +299,11 @@ import { isStripeLike, paymentInfoMap } from "@lib/constants"
 import { initiatePaymentSession, placeOrder } from "@lib/data/cart"
 import { CheckCircleSolid, CreditCard } from "@medusajs/icons"
 import { Button, Container, Heading, Text, clx } from "@medusajs/ui"
-import { MedusaNextPayPalAdapter } from "@easypayment/medusa-paypal-ui"
+import {
+  PayPalPaymentSection,
+  isPayPalProviderId,
+  usePayPalPaymentMethods,
+} from "@easypayment/medusa-paypal-ui"
 import ErrorMessage from "@modules/checkout/components/error-message"
 import PaymentContainer, {
   StripeCardContainer,
@@ -131,9 +312,6 @@ import Divider from "@modules/common/components/divider"
 import { usePathname, useRouter, useSearchParams } from "next/navigation"
 import { useCallback, useEffect, useState } from "react"
 
-const PAYPAL_IDS = ["pp_paypal_paypal", "pp_paypal_card_paypal_card"]
-const isPayPal = (id: string) => PAYPAL_IDS.includes(id)
-
 const Payment = ({
   cart,
   availablePaymentMethods,
@@ -142,7 +320,7 @@ const Payment = ({
   availablePaymentMethods: any[]
 }) => {
   const activeSession = cart.payment_collection?.payment_sessions?.find(
-    (paymentSession: any) => paymentSession.status === "pending"
+    (paymentSession: any) => paymentSession.status === "pending",
   )
 
   const [isLoading, setIsLoading] = useState(false)
@@ -150,12 +328,9 @@ const Payment = ({
   const [cardBrand, setCardBrand] = useState<string | null>(null)
   const [cardComplete, setCardComplete] = useState(false)
   const [selectedPaymentMethod, setSelectedPaymentMethod] = useState(
-    activeSession?.provider_id ?? ""
+    activeSession?.provider_id ?? "",
   )
-  const [paypalEnabled, setPaypalEnabled] = useState<boolean>(true)
-  const [paypalTitle, setPaypalTitle] = useState<string>("PayPal")
-  const [cardEnabled, setCardEnabled] = useState<boolean>(true)
-  const [cardTitle, setCardTitle] = useState<string>("Credit or Debit Card")
+  const [paypalSessionLoading, setPaypalSessionLoading] = useState(false)
 
   const searchParams = useSearchParams()
   const router = useRouter()
@@ -163,12 +338,24 @@ const Payment = ({
 
   const isOpen = searchParams.get("step") === "payment"
 
+  const { paypalEnabled, paypalTitle, cardEnabled, cardTitle } =
+    usePayPalPaymentMethods({
+      baseUrl: process.env.NEXT_PUBLIC_MEDUSA_BACKEND_URL!,
+      publishableApiKey: process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY,
+      cartId: cart.id,
+      enabled: isOpen,
+    })
+
   const setPaymentMethod = async (method: string) => {
     setError(null)
     setSelectedPaymentMethod(method)
-
-    if (isStripeLike(method) || isPayPal(method)) {
-      await initiatePaymentSession(cart, { provider_id: method })
+    if (isStripeLike(method) || isPayPalProviderId(method)) {
+      if (isPayPalProviderId(method)) setPaypalSessionLoading(true)
+      try {
+        await initiatePaymentSession(cart, { provider_id: method })
+      } finally {
+        setPaypalSessionLoading(false)
+      }
     }
   }
 
@@ -184,7 +371,7 @@ const Payment = ({
       params.set(name, value)
       return params.toString()
     },
-    [searchParams]
+    [searchParams],
   )
 
   const handleEdit = () => {
@@ -198,22 +385,15 @@ const Payment = ({
     try {
       const shouldInputCard =
         isStripeLike(selectedPaymentMethod) && !activeSession
-
       const checkActiveSession =
         activeSession?.provider_id === selectedPaymentMethod
-
       if (!checkActiveSession) {
-        await initiatePaymentSession(cart, {
-          provider_id: selectedPaymentMethod,
-        })
+        await initiatePaymentSession(cart, { provider_id: selectedPaymentMethod })
       }
-
       if (!shouldInputCard) {
         return router.push(
           pathname + "?" + createQueryString("step", "review"),
-          {
-            scroll: false,
-          }
+          { scroll: false },
         )
       }
     } catch (err: any) {
@@ -227,52 +407,6 @@ const Payment = ({
     setError(null)
   }, [isOpen])
 
-  useEffect(() => {
-    if (!isOpen) return
-
-    const backendUrl = process.env.NEXT_PUBLIC_MEDUSA_BACKEND_URL
-    if (!backendUrl) return
-
-    const key = process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY
-
-    fetch(`${backendUrl}/store/paypal/config`, {
-      headers: key ? { "x-publishable-api-key": key } : {},
-    })
-      .then((r) => {
-        if (r.status === 403) {
-          setPaypalEnabled(false)
-          setCardEnabled(false)
-          return null
-        }
-
-        if (!r.ok) {
-          return null
-        }
-
-        return r.json()
-      })
-      .then((cfg) => {
-        if (!cfg) return
-
-        if (typeof cfg?.paypal_enabled === "boolean") {
-          setPaypalEnabled(cfg.paypal_enabled)
-        }
-
-        if (typeof cfg?.paypal_title === "string" && cfg.paypal_title) {
-          setPaypalTitle(cfg.paypal_title)
-        }
-
-        if (typeof cfg?.card_enabled === "boolean") {
-          setCardEnabled(cfg.card_enabled)
-        }
-
-        if (typeof cfg?.card_title === "string" && cfg.card_title) {
-          setCardTitle(cfg.card_title)
-        }
-      })
-      .catch(() => {})
-  }, [isOpen])
-
   return (
     <div className="bg-white">
       <div className="flex flex-row items-center justify-between mb-6">
@@ -283,13 +417,12 @@ const Payment = ({
             {
               "opacity-50 pointer-events-none select-none":
                 !isOpen && !paymentReady,
-            }
+            },
           )}
         >
           Payment
           {!isOpen && paymentReady && <CheckCircleSolid />}
         </Heading>
-
         {!isOpen && paymentReady && (
           <Text>
             <button
@@ -305,69 +438,77 @@ const Payment = ({
 
       <div>
         <div className={isOpen ? "block" : "hidden"}>
-          {!paidByGiftcard &&
-            availablePaymentMethods?.length &&
-            (paypalEnabled ||
-              cardEnabled ||
-              availablePaymentMethods.some((m) => !isPayPal(m.id))) && (
-              <>
-                <RadioGroup
-                  value={selectedPaymentMethod}
-                  onChange={(value: string) => setPaymentMethod(value)}
-                >
-                  {availablePaymentMethods
-                    .filter((m) => {
-                      if (m.id === "pp_paypal_paypal" && !paypalEnabled) return false
-                      if (m.id === "pp_paypal_card_paypal_card" && !cardEnabled) return false
-                      return true
-                    })
-                    .map((paymentMethod) => (
-                      <div key={paymentMethod.id}>
-                        {isStripeLike(paymentMethod.id) ? (
-                          <StripeCardContainer
-                            paymentProviderId={paymentMethod.id}
-                            selectedPaymentOptionId={selectedPaymentMethod}
-                            paymentInfoMap={paymentInfoMap}
-                            setCardBrand={setCardBrand}
-                            setError={setError}
-                            setCardComplete={setCardComplete}
-                          />
-                        ) : (
-                          <PaymentContainer
-                            paymentInfoMap={{
-                              ...paymentInfoMap,
-                              ...(isPayPal(paymentMethod.id)
-                                ? {
-                                    [paymentMethod.id]: {
-                                      ...(paymentInfoMap[paymentMethod.id] || {}),
-                                      title:
-                                        paymentMethod.id === "pp_paypal_card_paypal_card"
-                                          ? cardTitle
-                                          : paypalTitle,
-                                    },
-                                  }
-                                : {}),
-                            }}
-                            paymentProviderId={paymentMethod.id}
-                            selectedPaymentOptionId={selectedPaymentMethod}
-                          />
-                        )}
-                      </div>
-                    ))}
-                </RadioGroup>
-
-                {isPayPal(selectedPaymentMethod) && (
-                  <MedusaNextPayPalAdapter
-                    cartId={cart.id}
-                    selectedProviderId={selectedPaymentMethod}
-                    baseUrl={process.env.NEXT_PUBLIC_MEDUSA_BACKEND_URL!}
-                    publishableApiKey={process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY}
-                    onSuccess={() => placeOrder(cart.id)}
-                    onError={(msg) => setError(msg)}
-                  />
-                )}
-              </>
-            )}
+          {!paidByGiftcard && availablePaymentMethods?.length && (
+            <>
+              <RadioGroup
+                value={selectedPaymentMethod}
+                onChange={(value: string) => setPaymentMethod(value)}
+              >
+                {availablePaymentMethods
+                  .filter((m) => {
+                    if (m.id === "pp_paypal_paypal" && !paypalEnabled) return false
+                    if (m.id === "pp_paypal_card_paypal_card" && !cardEnabled) return false
+                    return true
+                  })
+                  .map((paymentMethod) => (
+                    <div key={paymentMethod.id}>
+                      {isStripeLike(paymentMethod.id) ? (
+                        <StripeCardContainer
+                          paymentProviderId={paymentMethod.id}
+                          selectedPaymentOptionId={selectedPaymentMethod}
+                          paymentInfoMap={paymentInfoMap}
+                          setCardBrand={setCardBrand}
+                          setError={setError}
+                          setCardComplete={setCardComplete}
+                        />
+                      ) : (
+                        <PaymentContainer
+                          paymentInfoMap={{
+                            ...paymentInfoMap,
+                            "pp_paypal_paypal": {
+                              ...(paymentInfoMap["pp_paypal_paypal"] || {}),
+                              title: paypalTitle,
+                            },
+                            "pp_paypal_card_paypal_card": {
+                              ...(paymentInfoMap["pp_paypal_card_paypal_card"] || {}),
+                              title: cardTitle,
+                            },
+                          }}
+                          paymentProviderId={paymentMethod.id}
+                          selectedPaymentOptionId={selectedPaymentMethod}
+                        />
+                      )}
+                    </div>
+                  ))}
+              </RadioGroup>
+
+              <PayPalPaymentSection
+                cartId={cart.id}
+                selectedProviderId={selectedPaymentMethod}
+                baseUrl={process.env.NEXT_PUBLIC_MEDUSA_BACKEND_URL!}
+                publishableApiKey={process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY}
+                sessionLoading={paypalSessionLoading}
+                onSuccess={async () => {
+                  await placeOrder(cart.id)
+                }}
+                onError={(msg) => setError(msg)}
+              />
+            </>
+          )}
+
+          {paidByGiftcard && (
+            <div className="flex flex-col w-1/3">
+              <Text className="txt-medium-plus text-ui-fg-base mb-1">
+                Payment method
+              </Text>
+              <Text
+                className="txt-medium text-ui-fg-subtle"
+                data-testid="payment-method-summary"
+              >
+                Gift card
+              </Text>
+            </div>
+          )}
 
           <ErrorMessage
             error={error}
@@ -382,17 +523,69 @@ const Payment = ({
             disabled={
               (isStripeLike(selectedPaymentMethod) && !cardComplete) ||
               (!selectedPaymentMethod && !paidByGiftcard) ||
-              isPayPal(selectedPaymentMethod)
+              isPayPalProviderId(selectedPaymentMethod)
             }
             data-testid="submit-payment-button"
           >
             {!activeSession && isStripeLike(selectedPaymentMethod)
-              ? " Enter card details"
+              ? "Enter card details"
               : "Continue to review"}
           </Button>
         </div>
-      </div>
 
+        <div className={isOpen ? "hidden" : "block"}>
+          {cart && paymentReady && activeSession ? (
+            <div className="flex items-start gap-x-1 w-full">
+              <div className="flex flex-col w-1/3">
+                <Text className="txt-medium-plus text-ui-fg-base mb-1">
+                  Payment method
+                </Text>
+                <Text
+                  className="txt-medium text-ui-fg-subtle"
+                  data-testid="payment-method-summary"
+                >
+                  {activeSession?.provider_id === "pp_paypal_paypal"
+                    ? paypalTitle
+                    : activeSession?.provider_id === "pp_paypal_card_paypal_card"
+                    ? cardTitle
+                    : paymentInfoMap[activeSession?.provider_id]?.title ||
+                      activeSession?.provider_id}
+                </Text>
+              </div>
+              <div className="flex flex-col w-1/3">
+                <Text className="txt-medium-plus text-ui-fg-base mb-1">
+                  Payment details
+                </Text>
+                <div
+                  className="flex gap-2 txt-medium text-ui-fg-subtle items-center"
+                  data-testid="payment-details-summary"
+                >
+                  <Container className="flex items-center h-7 w-fit p-2 bg-ui-button-neutral-hover">
+                    {paymentInfoMap[selectedPaymentMethod]?.icon || <CreditCard />}
+                  </Container>
+                  <Text>
+                    {isStripeLike(selectedPaymentMethod) && cardBrand
+                      ? cardBrand
+                      : "Another step will appear"}
+                  </Text>
+                </div>
+              </div>
+            </div>
+          ) : paidByGiftcard ? (
+            <div className="flex flex-col w-1/3">
+              <Text className="txt-medium-plus text-ui-fg-base mb-1">
+                Payment method
+              </Text>
+              <Text
+                className="txt-medium text-ui-fg-subtle"
+                data-testid="payment-method-summary"
+              >
+                Gift card
+              </Text>
+            </div>
+          ) : null}
+        </div>
+      </div>
       <Divider className="mt-8" />
     </div>
   )
@@ -403,102 +596,20 @@ export default Payment
 
 ---
 
-## Adapter Usage
+## Testing
 
-Render the adapter only when the selected payment method is a PayPal provider:
+Toggle between sandbox and live in Medusa Admin → **Settings → PayPal → PayPal Connection → Environment**.
 
-```tsx
-{isPayPal(selectedPaymentMethod) && (
-  <MedusaNextPayPalAdapter
-    cartId={cart.id}
-    selectedProviderId={selectedPaymentMethod}
-    baseUrl={process.env.NEXT_PUBLIC_MEDUSA_BACKEND_URL!}
-    publishableApiKey={process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY}
-    onSuccess={() => placeOrder(cart.id)}
-    onError={(msg) => setError(msg)}
-  />
-)}
-```
-
----
+**Sandbox buyer account**
 
-## Runtime Config Endpoint
+Log in at [developer.paypal.com](https://developer.paypal.com) → **Testing → Sandbox Accounts** to find your auto-generated buyer credentials. Sandbox payments do not charge real money.
 
-The storefront reads PayPal runtime settings from:
+**Test card number for Advanced Card fields**
 
-```txt
-/store/paypal/config
 ```
-
-This endpoint is used to control:
-
-- `paypal_enabled`
-- `paypal_title`
-- `card_enabled`
-- `card_title`
-
-If the endpoint returns `403`, the storefront should treat both PayPal methods as disabled.
-
----
-
-## Props
-
-| Prop | Required | Description |
-|---|---|---|
-| `cartId` | Yes | Active cart ID |
-| `selectedProviderId` | Yes | Currently selected payment provider ID |
-| `baseUrl` | Yes | Medusa backend base URL |
-| `publishableApiKey` | No | Publishable API key sent in config request |
-| `providerIds` | No | Override default PayPal provider IDs |
-| `onSuccess` | No | Called after successful PayPal checkout |
-| `onError` | No | Called when PayPal returns an error |
-
----
-
-## Default Provider Mapping
-
-The UI package uses these default provider IDs:
-
-```ts
-{
-  paypal: "pp_paypal_paypal",
-  paypalCard: "pp_paypal_card_paypal_card"
-}
+Card number   4111 1111 1111 1111
+Expiry        Any future date
+CVV           Any 3 digits
 ```
 
-If your backend uses custom IDs, pass them through `providerIds`.
-
----
-
-## Notes for Medusa Starter Users
-
-The original Medusa starter payment step only initialized Stripe-like sessions and used the default review-step submit flow.
-
-To support PayPal, your updated checkout should additionally:
-
-- initialize sessions for PayPal methods
-- render `MedusaNextPayPalAdapter`
-- call `placeOrder` after successful PayPal completion
-- disable the normal submit button while PayPal is selected
-- optionally fetch backend config to control PayPal method visibility and labels
-
----
-
-## Validation Checklist
-
-- Install `@easypayment/medusa-paypal-ui`
-- Install `@paypal/react-paypal-js`
-- Set storefront environment variables
-- Configure backend PayPal package
-- Ensure provider IDs match backend configuration
-- Update checkout payment step
-- Verify PayPal Wallet flow
-- Verify PayPal Card flow
-- Verify order placement after successful payment
-- Verify error handling
-
----
-
-## License
-
-MIT
+---