@easypayment/medusa-paypal-ui 1.1.1 → 1.2.2

package/README.md

@@ -1,760 +1,782 @@
-# PayPal for Medusa Frontend UI
-
-**PayPal checkout UI for Medusa v2 storefronts — Smart Buttons, Advanced Card Fields**
-
-[![npm version](https://img.shields.io/npm/v/@easypayment/medusa-paypal-ui?color=blue&label=npm)](https://www.npmjs.com/package/@easypayment/medusa-paypal-ui)
-[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
-[![Medusa v2](https://img.shields.io/badge/Medusa-v2-9b59b6)](https://medusajs.com)
-[![Next.js](https://img.shields.io/badge/Next.js-14%2B-black)](https://nextjs.org)
-
----
-
-## 📋 Table of Contents
-
-- [📦 Overview](#-overview)
-- [✅ 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 PayPal helpers and state](#step-2--add-paypal-helpers-and-state)
-  - [Step 3 — Load PayPal config](#step-3--load-paypal-config)
-  - [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)
-- [📄 License](#-license)
-
----
-
-## 📦 Overview
-
-`@easypayment/medusa-paypal-ui` is the **storefront UI package** that connects your Next.js (App Router) storefront to the `@easypayment/medusa-paypal` backend plugin. It ships the PayPal adapter used inside your checkout payment step — your storefront adds the adapter, provider filtering, and backend config handling to the existing Medusa payment UI.
-
-| Feature | Details |
-|---|---|
-| 🔵 **PayPal Smart Buttons** | Wallet-based checkout via `pp_paypal_paypal` |
-| 💳 **Advanced Card Fields** | Hosted PCI-compliant advanced credit card inputs via `pp_paypal_card_paypal_card` |
-| 🛠 **Admin-driven config** | Enable/disable providers and set labels from Medusa Admin |
-| ⚡ **Built-in UX** | Smart Buttons and Advanced Card UI rendered by `MedusaNextPayPalAdapter` |
-| 🔄 **Storefront-controlled flow** | Your payment step controls session creation, loading states, and `placeOrder` |
-
----
-
-## ✅ Requirements
-
-- **Node.js** 18+
-- **Next.js** 14+ with App Router
-- **`@easypayment/medusa-paypal`** installed and running on your Medusa server
-- A PayPal account connected in **Medusa Admin → Settings → PayPal → PayPal Connection**
-
----
-
-## 🚀 Installation
-
-**In your storefront directory**, run:
-
-```bash
-npm install @easypayment/medusa-paypal-ui
-```
-
----
-
-## 🔑 Environment Variables
-
-Add the following to your storefront `.env.local`. Use separate values for development and production.
-
-```env
-NEXT_PUBLIC_MEDUSA_BACKEND_URL=http://localhost:9000
-NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY=pk_...
-```
-
-> **Where to get the publishable key:**
-> Medusa Admin → **Settings → API Key Management → Create API Key**
-
----
-
-## 🔗 Integration Guide
-
-All changes in this guide are made to **one single file** in your storefront:
-
-```
-src/modules/checkout/components/payment/index.tsx
-```
-
-Open that file and follow each step in order.
-
-> **Prefer to copy-paste the whole file?** Skip straight to [Complete File](#-complete-file) and replace the entire contents in one go. The complete file has all 9 steps already applied.
-
----
-
-### Step 1 — Add the import
-
-**Where:** At the very top of the file, alongside your other imports.
-
-```tsx
-import { MedusaNextPayPalAdapter } from "@easypayment/medusa-paypal-ui"
-```
-
----
-
-### Step 2 — Add PayPal helpers and state
-
-**Where:** At the top of the file, outside the component — add the constants. Inside the `Payment` component, add the `useState` lines alongside your other state declarations.
-
-```tsx
-// Outside the component — add these constants
-const PAYPAL_PROVIDER_ID = "pp_paypal_paypal"
-const PAYPAL_CARD_PROVIDER_ID = "pp_paypal_card_paypal_card"
-const PAYPAL_PROVIDER_IDS = [PAYPAL_PROVIDER_ID, PAYPAL_CARD_PROVIDER_ID]
-
-const isPayPal = (id: string) => PAYPAL_PROVIDER_IDS.includes(id)
-```
-
-```tsx
-// Inside the Payment component — add alongside your other useState declarations
-const [paypalEnabled, setPaypalEnabled] = useState(true)
-const [paypalTitle, setPaypalTitle] = useState("PayPal")
-const [cardEnabled, setCardEnabled] = useState(true)
-const [cardTitle, setCardTitle] = useState("Credit or Debit Card")
-const [paypalLoading, setPaypalLoading] = useState(false)
-```
-
----
-
-### Step 3 — Load PayPal config
-
-**Where:** Inside the `Payment` component, alongside your other `useEffect` hooks.
-
-This fetches PayPal settings from your backend whenever the payment step is opened, so the UI always reflects the latest admin configuration.
-
-```tsx
-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
-  const controller = new AbortController()
-
-  const loadPayPalConfig = async () => {
-    try {
-      const response = await fetch(`${backendUrl}/store/paypal/config`, {
-        headers: key ? { "x-publishable-api-key": key } : {},
-        signal: controller.signal,
-      })
-
-      if (response.status === 403) {
-        setPaypalEnabled(false)
-        setCardEnabled(false)
-        return
-      }
-
-      if (!response.ok) return
-
-      const config = await response.json()
-
-      if (typeof config?.paypal_enabled === "boolean") setPaypalEnabled(config.paypal_enabled)
-      if (typeof config?.paypal_title === "string" && config.paypal_title) setPaypalTitle(config.paypal_title)
-      if (typeof config?.card_enabled === "boolean") setCardEnabled(config.card_enabled)
-      if (typeof config?.card_title === "string" && config.card_title) setCardTitle(config.card_title)
-    } catch (err) {
-      if ((err as Error).name !== "AbortError") setPaypalLoading(false)
-    }
-  }
-
-  void loadPayPalConfig()
-  return () => controller.abort()
-}, [isOpen])
-```
-
----
-
-### Step 4 — Update setPaymentMethod
-
-**Where:** Inside the `Payment` component. Find your existing `setPaymentMethod` function and **replace it entirely** with the version below.
-
-The key addition is `paypalLoading` — it shows a loading indicator while the PayPal payment session is being created in the background.
-
-```tsx
-const setPaymentMethod = async (method: string) => {
-  setError(null)
-  setSelectedPaymentMethod(method)
-
-  if (!isStripeLike(method) && !isPayPal(method)) return
-
-  if (isPayPal(method)) setPaypalLoading(true)
-
-  try {
-    await initiatePaymentSession(cart, { provider_id: method })
-  } finally {
-    if (isPayPal(method)) setPaypalLoading(false)
-  }
-}
-```
-
----
-
-### Step 5 — Filter the payment method list
-
-**Where:** Inside the `Payment` component, alongside your other `useMemo` declarations — add this before the `return` statement.
-
-This hides PayPal or Card from the list if they have been disabled in Medusa Admin.
-
-```tsx
-const filteredPaymentMethods = useMemo(
-  () =>
-    availablePaymentMethods.filter((paymentMethod) => {
-      if (paymentMethod.id === PAYPAL_PROVIDER_ID) return paypalEnabled
-      if (paymentMethod.id === PAYPAL_CARD_PROVIDER_ID) return cardEnabled
-      return true
-    }),
-  [availablePaymentMethods, cardEnabled, paypalEnabled],
-)
-```
-
-Then in your JSX, find where you render `availablePaymentMethods.map(...)` and **replace** `availablePaymentMethods` with `filteredPaymentMethods`:
-
-```tsx
-// Before
-availablePaymentMethods.map((paymentMethod) => ( ... ))
-
-// After
-filteredPaymentMethods.map((paymentMethod) => ( ... ))
-```
-
----
-
-### Step 6 — Inject admin-configured titles
-
-**Where:** Inside the `.map()` loop from Step 5, find your `<PaymentContainer>` component and **replace** its `paymentInfoMap` prop with the version below.
-
-This makes the radio button labels show the titles configured in Medusa Admin instead of hardcoded defaults.
-
-```tsx
-<PaymentContainer
-  paymentInfoMap={{
-    ...paymentInfoMap,
-    ...(paymentMethod.id === PAYPAL_PROVIDER_ID
-      ? { [paymentMethod.id]: { ...(paymentInfoMap[paymentMethod.id] || {}), title: paypalTitle } }
-      : {}),
-    ...(paymentMethod.id === PAYPAL_CARD_PROVIDER_ID
-      ? { [paymentMethod.id]: { ...(paymentInfoMap[paymentMethod.id] || {}), title: cardTitle } }
-      : {}),
-  }}
-  paymentProviderId={paymentMethod.id}
-  selectedPaymentOptionId={selectedPaymentMethod}
-/>
-```
-
----
-
-### Step 7 — Render the PayPal UI
-
-**Where:** In the JSX, immediately after the closing `</RadioGroup>` tag.
-
-The first block shows a loading spinner while the session is being set up. The second block renders the PayPal buttons or card fields once the session is ready.
-
-```tsx
-{/* Loading state while PayPal session is being created */}
-{isPayPal(selectedPaymentMethod) && paypalLoading && (
-  <div>Setting up payment...</div>
-)}
-
-{/* PayPal buttons or card fields */}
-{isPayPal(selectedPaymentMethod) && !paypalLoading && (
-  <MedusaNextPayPalAdapter
-    cartId={cart.id}
-    selectedProviderId={selectedPaymentMethod}
-    baseUrl={process.env.NEXT_PUBLIC_MEDUSA_BACKEND_URL!}
-    publishableApiKey={process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY}
-    onSuccess={async () => {
-      await placeOrder(cart.id)
-    }}
-    onError={(message) => setError(message)}
-  />
-)}
-```
-
----
-
-### Step 8 — Disable the Continue button
-
-**Where:** In the JSX, find your existing `<Button>` with `data-testid="submit-payment-button"` and **add** `isPayPal(selectedPaymentMethod)` to its `disabled` prop.
-
-PayPal handles its own checkout action, so the "Continue to review" button must be hidden from the flow when PayPal is selected.
-
-```tsx
-<Button
-  size="large"
-  className="mt-6"
-  onClick={handleSubmit}
-  isLoading={isLoading}
-  disabled={
-    (isStripeLike(selectedPaymentMethod) && !cardComplete) ||
-    (!selectedPaymentMethod && !paidByGiftcard) ||
-    isPayPal(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
-
-**Where:** In the collapsed summary view (shown after the customer has completed the payment step). Find the `<Text>` with `data-testid="payment-method-summary"` and **replace its content** with the version below.
-
-This shows the admin-configured title instead of a hardcoded or missing label.
-
-```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
-
-If you prefer to copy-paste the entire file at once, replace the full contents of `src/modules/checkout/components/payment/index.tsx` with the following:
-
-```tsx
-"use client"
-
-import { RadioGroup } from "@headlessui/react"
-import { initiatePaymentSession, placeOrder } from "@lib/data/cart"
-import { isStripeLike, paymentInfoMap } from "@lib/constants"
-import { MedusaNextPayPalAdapter } from "@easypayment/medusa-paypal-ui"
-import { CheckCircleSolid, CreditCard } from "@medusajs/icons"
-import { Button, Container, Heading, Text, clx } from "@medusajs/ui"
-import ErrorMessage from "@modules/checkout/components/error-message"
-import PaymentContainer, {
-  StripeCardContainer,
-} from "@modules/checkout/components/payment-container"
-import Divider from "@modules/common/components/divider"
-import { usePathname, useRouter, useSearchParams } from "next/navigation"
-import { useCallback, useEffect, useMemo, useState } from "react"
-
-const PAYPAL_PROVIDER_ID = "pp_paypal_paypal"
-const PAYPAL_CARD_PROVIDER_ID = "pp_paypal_card_paypal_card"
-const PAYPAL_PROVIDER_IDS = [PAYPAL_PROVIDER_ID, PAYPAL_CARD_PROVIDER_ID]
-
-const isPayPal = (id: string) => PAYPAL_PROVIDER_IDS.includes(id)
-
-const Payment = ({
-  cart,
-  availablePaymentMethods,
-}: {
-  cart: any
-  availablePaymentMethods: any[]
-}) => {
-  const activeSession = cart.payment_collection?.payment_sessions?.find(
-    (paymentSession: any) => paymentSession.status === "pending",
-  )
-
-  const [isLoading, setIsLoading] = useState(false)
-  const [error, setError] = useState<string | null>(null)
-  const [cardBrand, setCardBrand] = useState<string | null>(null)
-  const [cardComplete, setCardComplete] = useState(false)
-  const [selectedPaymentMethod, setSelectedPaymentMethod] = useState(
-    activeSession?.provider_id ?? "",
-  )
-  const [paypalEnabled, setPaypalEnabled] = useState(true)
-  const [paypalTitle, setPaypalTitle] = useState("PayPal")
-  const [cardEnabled, setCardEnabled] = useState(true)
-  const [cardTitle, setCardTitle] = useState("Credit or Debit Card")
-  const [paypalLoading, setPaypalLoading] = useState(false)
-
-  const searchParams = useSearchParams()
-  const router = useRouter()
-  const pathname = usePathname()
-
-  const isOpen = searchParams.get("step") === "payment"
-
-  const filteredPaymentMethods = useMemo(
-    () =>
-      availablePaymentMethods.filter((paymentMethod) => {
-        if (paymentMethod.id === PAYPAL_PROVIDER_ID) return paypalEnabled
-        if (paymentMethod.id === PAYPAL_CARD_PROVIDER_ID) return cardEnabled
-        return true
-      }),
-    [availablePaymentMethods, cardEnabled, paypalEnabled],
-  )
-
-  const setPaymentMethod = async (method: string) => {
-    setError(null)
-    setSelectedPaymentMethod(method)
-
-    if (!isStripeLike(method) && !isPayPal(method)) return
-
-    if (isPayPal(method)) setPaypalLoading(true)
-
-    try {
-      await initiatePaymentSession(cart, { provider_id: method })
-    } finally {
-      if (isPayPal(method)) setPaypalLoading(false)
-    }
-  }
-
-  const paidByGiftcard =
-    cart?.gift_cards && cart?.gift_cards?.length > 0 && cart?.total === 0
-
-  const paymentReady =
-    (activeSession && cart?.shipping_methods.length !== 0) || paidByGiftcard
-
-  const createQueryString = useCallback(
-    (name: string, value: string) => {
-      const params = new URLSearchParams(searchParams)
-      params.set(name, value)
-      return params.toString()
-    },
-    [searchParams],
-  )
-
-  const handleEdit = () => {
-    router.push(pathname + "?" + createQueryString("step", "payment"), {
-      scroll: false,
-    })
-  }
-
-  const handleSubmit = async () => {
-    setIsLoading(true)
-
-    try {
-      const shouldInputCard =
-        isStripeLike(selectedPaymentMethod) && !activeSession
-      const checkActiveSession =
-        activeSession?.provider_id === selectedPaymentMethod
-
-      if (!checkActiveSession) {
-        await initiatePaymentSession(cart, {
-          provider_id: selectedPaymentMethod,
-        })
-      }
-
-      if (!shouldInputCard) {
-        return router.push(
-          pathname + "?" + createQueryString("step", "review"),
-          { scroll: false },
-        )
-      }
-    } catch (err: any) {
-      setError(err.message)
-    } finally {
-      setIsLoading(false)
-    }
-  }
-
-  useEffect(() => {
-    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
-    const controller = new AbortController()
-
-    const loadPayPalConfig = async () => {
-      try {
-        const response = await fetch(`${backendUrl}/store/paypal/config`, {
-          headers: key ? { "x-publishable-api-key": key } : {},
-          signal: controller.signal,
-        })
-
-        if (response.status === 403) {
-          setPaypalEnabled(false)
-          setCardEnabled(false)
-          return
-        }
-
-        if (!response.ok) return
-
-        const config = await response.json()
-
-        if (typeof config?.paypal_enabled === "boolean") setPaypalEnabled(config.paypal_enabled)
-        if (typeof config?.paypal_title === "string" && config.paypal_title) setPaypalTitle(config.paypal_title)
-        if (typeof config?.card_enabled === "boolean") setCardEnabled(config.card_enabled)
-        if (typeof config?.card_title === "string" && config.card_title) setCardTitle(config.card_title)
-      } catch (err) {
-        if ((err as Error).name !== "AbortError") setPaypalLoading(false)
-      }
-    }
-
-    void loadPayPalConfig()
-    return () => controller.abort()
-  }, [isOpen])
-
-  return (
-    <div className="bg-white">
-      <div className="flex flex-row items-center justify-between mb-6">
-        <Heading
-          level="h2"
-          className={clx(
-            "flex flex-row text-3xl-regular gap-x-2 items-baseline",
-            {
-              "opacity-50 pointer-events-none select-none":
-                !isOpen && !paymentReady,
-            },
-          )}
-        >
-          Payment
-          {!isOpen && paymentReady && <CheckCircleSolid />}
-        </Heading>
-        {!isOpen && paymentReady && (
-          <Text>
-            <button
-              onClick={handleEdit}
-              className="text-ui-fg-interactive hover:text-ui-fg-interactive-hover"
-              data-testid="edit-payment-button"
-            >
-              Edit
-            </button>
-          </Text>
-        )}
-      </div>
-
-      <div>
-        <div className={isOpen ? "block" : "hidden"}>
-          {!paidByGiftcard &&
-            filteredPaymentMethods.length > 0 &&
-            (paypalEnabled ||
-              cardEnabled ||
-              availablePaymentMethods.some((method) => !isPayPal(method.id))) && (
-              <>
-                <RadioGroup
-                  value={selectedPaymentMethod}
-                  onChange={(value: string) => setPaymentMethod(value)}
-                >
-                  {filteredPaymentMethods.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,
-                            ...(paymentMethod.id === PAYPAL_PROVIDER_ID
-                              ? {
-                                  [paymentMethod.id]: {
-                                    ...(paymentInfoMap[paymentMethod.id] || {}),
-                                    title: paypalTitle,
-                                  },
-                                }
-                              : {}),
-                            ...(paymentMethod.id === PAYPAL_CARD_PROVIDER_ID
-                              ? {
-                                  [paymentMethod.id]: {
-                                    ...(paymentInfoMap[paymentMethod.id] || {}),
-                                    title: cardTitle,
-                                  },
-                                }
-                              : {}),
-                          }}
-                          paymentProviderId={paymentMethod.id}
-                          selectedPaymentOptionId={selectedPaymentMethod}
-                        />
-                      )}
-                    </div>
-                  ))}
-                </RadioGroup>
-
-                {isPayPal(selectedPaymentMethod) && paypalLoading && (
-                  <div
-                    style={{
-                      display: "flex",
-                      alignItems: "center",
-                      gap: 12,
-                      padding: "14px 16px",
-                      marginTop: 8,
-                      background: "#f9fafb",
-                      border: "1px solid #e5e7eb",
-                      borderRadius: 10,
-                    }}
-                  >
-                    <style>{`@keyframes _idx_spin{to{transform:rotate(360deg)}}`}</style>
-                    <div
-                      style={{
-                        width: 20,
-                        height: 20,
-                        borderRadius: "50%",
-                        border: "2.5px solid #e5e7eb",
-                        borderTopColor: "#0070ba",
-                        animation: "_idx_spin .7s linear infinite",
-                        flexShrink: 0,
-                      }}
-                    />
-                    <div
-                      style={{
-                        fontSize: 13,
-                        fontWeight: 500,
-                        color: "#111827",
-                      }}
-                    >
-                      Setting up payment...
-                    </div>
-                  </div>
-                )}
-
-                {isPayPal(selectedPaymentMethod) && !paypalLoading && (
-                  <MedusaNextPayPalAdapter
-                    cartId={cart.id}
-                    selectedProviderId={selectedPaymentMethod}
-                    baseUrl={process.env.NEXT_PUBLIC_MEDUSA_BACKEND_URL!}
-                    publishableApiKey={process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY}
-                    onSuccess={async () => {
-                      await placeOrder(cart.id)
-                    }}
-                    onError={(message) => setError(message)}
-                  />
-                )}
-              </>
-            )}
-
-          {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}
-            data-testid="payment-method-error-message"
-          />
-
-          <Button
-            size="large"
-            className="mt-6"
-            onClick={handleSubmit}
-            isLoading={isLoading}
-            disabled={
-              (isStripeLike(selectedPaymentMethod) && !cardComplete) ||
-              (!selectedPaymentMethod && !paidByGiftcard) ||
-              isPayPal(selectedPaymentMethod)
-            }
-            data-testid="submit-payment-button"
-          >
-            {!activeSession && isStripeLike(selectedPaymentMethod)
-              ? "Enter card details"
-              : "Continue to review"}
-          </Button>
-        </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>
-  )
-}
-
-export default Payment
-```
-
----
-
-## 🧪 Testing
-
-Toggle between sandbox and live in **Medusa Admin → Settings → PayPal → PayPal Connection → Environment**.
-
-**Sandbox buyer account** — 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.
-
-**Test card for Advanced Card Fields:**
-
-```
-Card number   4111 1111 1111 1111
-Expiry        Any future date
-CVV           Any 3 digits
-```
-
----
-
-## 📄 License
-
+# PayPal for Medusa Frontend UI
+
+**PayPal checkout UI for Medusa v2 storefronts — Smart Buttons, Advanced Card Fields**
+
+[![npm version](https://img.shields.io/npm/v/@easypayment/medusa-paypal-ui?color=blue&label=npm)](https://www.npmjs.com/package/@easypayment/medusa-paypal-ui)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![Medusa v2](https://img.shields.io/badge/Medusa-v2-9b59b6)](https://medusajs.com)
+[![Next.js](https://img.shields.io/badge/Next.js-14%2B-black)](https://nextjs.org)
+
+---
+
+## 📋 Table of Contents
+
+- [📦 Overview](#-overview)
+- [✅ 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 PayPal helpers and state](#step-2--add-paypal-helpers-and-state)
+  - [Step 3 — Load PayPal config](#step-3--load-paypal-config)
+  - [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)
+- [🛡 Built-in payment protection](#-built-in-payment-protection)
+- [🧪 Testing](#-testing)
+- [📄 License](#-license)
+
+---
+
+## 📦 Overview
+
+`@easypayment/medusa-paypal-ui` is the **storefront UI package** that connects your Next.js (App Router) storefront to the `@easypayment/medusa-paypal` backend plugin. It ships the PayPal adapter used inside your checkout payment step — your storefront adds the adapter, provider filtering, and backend config handling to the existing Medusa payment UI.
+
+| Feature | Details |
+|---|---|
+| 🔵 **PayPal Smart Buttons** | Wallet-based checkout via `pp_paypal_paypal` |
+| 💳 **Advanced Card Fields** | Hosted PCI-compliant advanced credit card inputs via `pp_paypal_card_paypal_card` |
+| 🛠 **Admin-driven config** | Enable/disable providers and set labels from Medusa Admin |
+| ⚡ **Built-in UX** | Smart Buttons and Advanced Card UI rendered by `MedusaNextPayPalAdapter` |
+| 🔄 **Storefront-controlled flow** | Your payment step controls session creation, loading states, and `placeOrder` |
+
+---
+
+## ✅ Requirements
+
+- **Node.js** 18+
+- **Next.js** 14+ with App Router
+- **`@easypayment/medusa-paypal`** installed and running on your Medusa server
+- A PayPal account connected in **Medusa Admin → Settings → PayPal → PayPal Connection**
+
+---
+
+## 🚀 Installation
+
+**In your storefront directory**, run:
+
+```bash
+npm install @easypayment/medusa-paypal-ui
+```
+
+---
+
+## 🔑 Environment Variables
+
+Add the following to your storefront `.env.local`. Use separate values for development and production.
+
+```env
+NEXT_PUBLIC_MEDUSA_BACKEND_URL=http://localhost:9000
+NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY=pk_...
+```
+
+> **Where to get the publishable key:**
+> Medusa Admin → **Settings → API Key Management → Create API Key**
+
+---
+
+## 🔗 Integration Guide
+
+All changes in this guide are made to **one single file** in your storefront:
+
+```
+src/modules/checkout/components/payment/index.tsx
+```
+
+Open that file and follow each step in order.
+
+> **Prefer to copy-paste the whole file?** Skip straight to [Complete File](#-complete-file) and replace the entire contents in one go. The complete file has all 9 steps already applied.
+
+---
+
+### Step 1 — Add the import
+
+**Where:** At the very top of the file, alongside your other imports.
+
+```tsx
+import { MedusaNextPayPalAdapter } from "@easypayment/medusa-paypal-ui"
+```
+
+---
+
+### Step 2 — Add PayPal helpers and state
+
+**Where:** At the top of the file, outside the component — add the constants. Inside the `Payment` component, add the `useState` lines alongside your other state declarations.
+
+```tsx
+// Outside the component — add these constants
+const PAYPAL_PROVIDER_ID = "pp_paypal_paypal"
+const PAYPAL_CARD_PROVIDER_ID = "pp_paypal_card_paypal_card"
+const PAYPAL_PROVIDER_IDS = [PAYPAL_PROVIDER_ID, PAYPAL_CARD_PROVIDER_ID]
+
+const isPayPal = (id: string) => PAYPAL_PROVIDER_IDS.includes(id)
+```
+
+```tsx
+// Inside the Payment component — add alongside your other useState declarations
+const [paypalEnabled, setPaypalEnabled] = useState(true)
+const [paypalTitle, setPaypalTitle] = useState("PayPal")
+const [cardEnabled, setCardEnabled] = useState(true)
+const [cardTitle, setCardTitle] = useState("Credit or Debit Card")
+const [paypalLoading, setPaypalLoading] = useState(false)
+```
+
+---
+
+### Step 3 — Load PayPal config
+
+**Where:** Inside the `Payment` component, alongside your other `useEffect` hooks.
+
+This fetches PayPal settings from your backend whenever the payment step is opened, so the UI always reflects the latest admin configuration.
+
+```tsx
+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
+  const controller = new AbortController()
+
+  const loadPayPalConfig = async () => {
+    try {
+      const response = await fetch(`${backendUrl}/store/paypal/config`, {
+        headers: key ? { "x-publishable-api-key": key } : {},
+        signal: controller.signal,
+      })
+
+      if (response.status === 403) {
+        setPaypalEnabled(false)
+        setCardEnabled(false)
+        return
+      }
+
+      if (!response.ok) return
+
+      const config = await response.json()
+
+      if (typeof config?.paypal_enabled === "boolean") setPaypalEnabled(config.paypal_enabled)
+      if (typeof config?.paypal_title === "string" && config.paypal_title) setPaypalTitle(config.paypal_title)
+      if (typeof config?.card_enabled === "boolean") setCardEnabled(config.card_enabled)
+      if (typeof config?.card_title === "string" && config.card_title) setCardTitle(config.card_title)
+    } catch (err) {
+      if ((err as Error).name !== "AbortError") setPaypalLoading(false)
+    }
+  }
+
+  void loadPayPalConfig()
+  return () => controller.abort()
+}, [isOpen])
+```
+
+---
+
+### Step 4 — Update setPaymentMethod
+
+**Where:** Inside the `Payment` component. Find your existing `setPaymentMethod` function and **replace it entirely** with the version below.
+
+The key addition is `paypalLoading` — it shows a loading indicator while the PayPal payment session is being created in the background.
+
+```tsx
+const setPaymentMethod = async (method: string) => {
+  setError(null)
+  setSelectedPaymentMethod(method)
+
+  if (!isStripeLike(method) && !isPayPal(method)) return
+
+  if (isPayPal(method)) setPaypalLoading(true)
+
+  try {
+    await initiatePaymentSession(cart, { provider_id: method })
+  } finally {
+    if (isPayPal(method)) setPaypalLoading(false)
+  }
+}
+```
+
+---
+
+### Step 5 — Filter the payment method list
+
+**Where:** Inside the `Payment` component, alongside your other `useMemo` declarations — add this before the `return` statement.
+
+This hides PayPal or Card from the list if they have been disabled in Medusa Admin.
+
+```tsx
+const filteredPaymentMethods = useMemo(
+  () =>
+    availablePaymentMethods.filter((paymentMethod) => {
+      if (paymentMethod.id === PAYPAL_PROVIDER_ID) return paypalEnabled
+      if (paymentMethod.id === PAYPAL_CARD_PROVIDER_ID) return cardEnabled
+      return true
+    }),
+  [availablePaymentMethods, cardEnabled, paypalEnabled],
+)
+```
+
+Then in your JSX, find where you render `availablePaymentMethods.map(...)` and **replace** `availablePaymentMethods` with `filteredPaymentMethods`:
+
+```tsx
+// Before
+availablePaymentMethods.map((paymentMethod) => ( ... ))
+
+// After
+filteredPaymentMethods.map((paymentMethod) => ( ... ))
+```
+
+---
+
+### Step 6 — Inject admin-configured titles
+
+**Where:** Inside the `.map()` loop from Step 5, find your `<PaymentContainer>` component and **replace** its `paymentInfoMap` prop with the version below.
+
+This makes the radio button labels show the titles configured in Medusa Admin instead of hardcoded defaults.
+
+```tsx
+<PaymentContainer
+  paymentInfoMap={{
+    ...paymentInfoMap,
+    ...(paymentMethod.id === PAYPAL_PROVIDER_ID
+      ? { [paymentMethod.id]: { ...(paymentInfoMap[paymentMethod.id] || {}), title: paypalTitle } }
+      : {}),
+    ...(paymentMethod.id === PAYPAL_CARD_PROVIDER_ID
+      ? { [paymentMethod.id]: { ...(paymentInfoMap[paymentMethod.id] || {}), title: cardTitle } }
+      : {}),
+  }}
+  paymentProviderId={paymentMethod.id}
+  selectedPaymentOptionId={selectedPaymentMethod}
+/>
+```
+
+---
+
+### Step 7 — Render the PayPal UI
+
+**Where:** In the JSX, immediately after the closing `</RadioGroup>` tag.
+
+The first block shows a loading spinner while the session is being set up. The second block renders the PayPal buttons or card fields once the session is ready.
+
+```tsx
+{/* Loading state while PayPal session is being created */}
+{isPayPal(selectedPaymentMethod) && paypalLoading && (
+  <div>Setting up payment...</div>
+)}
+
+{/* PayPal buttons or card fields */}
+{isPayPal(selectedPaymentMethod) && !paypalLoading && (
+  <MedusaNextPayPalAdapter
+    cartId={cart.id}
+    selectedProviderId={selectedPaymentMethod}
+    baseUrl={process.env.NEXT_PUBLIC_MEDUSA_BACKEND_URL!}
+    publishableApiKey={process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY}
+    onSuccess={async () => {
+      await placeOrder(cart.id)
+    }}
+    onError={(message) => setError(message)}
+  />
+)}
+```
+
+---
+
+### Step 8 — Disable the Continue button
+
+**Where:** In the JSX, find your existing `<Button>` with `data-testid="submit-payment-button"` and **add** `isPayPal(selectedPaymentMethod)` to its `disabled` prop.
+
+PayPal handles its own checkout action, so the "Continue to review" button must be hidden from the flow when PayPal is selected.
+
+```tsx
+<Button
+  size="large"
+  className="mt-6"
+  onClick={handleSubmit}
+  isLoading={isLoading}
+  disabled={
+    (isStripeLike(selectedPaymentMethod) && !cardComplete) ||
+    (!selectedPaymentMethod && !paidByGiftcard) ||
+    isPayPal(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
+
+**Where:** In the collapsed summary view (shown after the customer has completed the payment step). Find the `<Text>` with `data-testid="payment-method-summary"` and **replace its content** with the version below.
+
+This shows the admin-configured title instead of a hardcoded or missing label.
+
+```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
+
+If you prefer to copy-paste the entire file at once, replace the full contents of `src/modules/checkout/components/payment/index.tsx` with the following:
+
+```tsx
+"use client"
+
+import { RadioGroup } from "@headlessui/react"
+import { initiatePaymentSession, placeOrder } from "@lib/data/cart"
+import { isStripeLike, paymentInfoMap } from "@lib/constants"
+import { MedusaNextPayPalAdapter } from "@easypayment/medusa-paypal-ui"
+import { CheckCircleSolid, CreditCard } from "@medusajs/icons"
+import { Button, Container, Heading, Text, clx } from "@medusajs/ui"
+import ErrorMessage from "@modules/checkout/components/error-message"
+import PaymentContainer, {
+  StripeCardContainer,
+} from "@modules/checkout/components/payment-container"
+import Divider from "@modules/common/components/divider"
+import { usePathname, useRouter, useSearchParams } from "next/navigation"
+import { useCallback, useEffect, useMemo, useState } from "react"
+
+const PAYPAL_PROVIDER_ID = "pp_paypal_paypal"
+const PAYPAL_CARD_PROVIDER_ID = "pp_paypal_card_paypal_card"
+const PAYPAL_PROVIDER_IDS = [PAYPAL_PROVIDER_ID, PAYPAL_CARD_PROVIDER_ID]
+
+const isPayPal = (id: string) => PAYPAL_PROVIDER_IDS.includes(id)
+
+const Payment = ({
+  cart,
+  availablePaymentMethods,
+}: {
+  cart: any
+  availablePaymentMethods: any[]
+}) => {
+  const activeSession = cart.payment_collection?.payment_sessions?.find(
+    (paymentSession: any) => paymentSession.status === "pending",
+  )
+
+  const [isLoading, setIsLoading] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+  const [cardBrand, setCardBrand] = useState<string | null>(null)
+  const [cardComplete, setCardComplete] = useState(false)
+  const [selectedPaymentMethod, setSelectedPaymentMethod] = useState(
+    activeSession?.provider_id ?? "",
+  )
+  const [paypalEnabled, setPaypalEnabled] = useState(true)
+  const [paypalTitle, setPaypalTitle] = useState("PayPal")
+  const [cardEnabled, setCardEnabled] = useState(true)
+  const [cardTitle, setCardTitle] = useState("Credit or Debit Card")
+  const [paypalLoading, setPaypalLoading] = useState(false)
+
+  const searchParams = useSearchParams()
+  const router = useRouter()
+  const pathname = usePathname()
+
+  const isOpen = searchParams.get("step") === "payment"
+
+  const filteredPaymentMethods = useMemo(
+    () =>
+      availablePaymentMethods.filter((paymentMethod) => {
+        if (paymentMethod.id === PAYPAL_PROVIDER_ID) return paypalEnabled
+        if (paymentMethod.id === PAYPAL_CARD_PROVIDER_ID) return cardEnabled
+        return true
+      }),
+    [availablePaymentMethods, cardEnabled, paypalEnabled],
+  )
+
+  const setPaymentMethod = async (method: string) => {
+    setError(null)
+    setSelectedPaymentMethod(method)
+
+    if (!isStripeLike(method) && !isPayPal(method)) return
+
+    if (isPayPal(method)) setPaypalLoading(true)
+
+    try {
+      await initiatePaymentSession(cart, { provider_id: method })
+    } finally {
+      if (isPayPal(method)) setPaypalLoading(false)
+    }
+  }
+
+  const paidByGiftcard =
+    cart?.gift_cards && cart?.gift_cards?.length > 0 && cart?.total === 0
+
+  const paymentReady =
+    (activeSession && cart?.shipping_methods.length !== 0) || paidByGiftcard
+
+  const createQueryString = useCallback(
+    (name: string, value: string) => {
+      const params = new URLSearchParams(searchParams)
+      params.set(name, value)
+      return params.toString()
+    },
+    [searchParams],
+  )
+
+  const handleEdit = () => {
+    router.push(pathname + "?" + createQueryString("step", "payment"), {
+      scroll: false,
+    })
+  }
+
+  const handleSubmit = async () => {
+    setIsLoading(true)
+
+    try {
+      const shouldInputCard =
+        isStripeLike(selectedPaymentMethod) && !activeSession
+      const checkActiveSession =
+        activeSession?.provider_id === selectedPaymentMethod
+
+      if (!checkActiveSession) {
+        await initiatePaymentSession(cart, {
+          provider_id: selectedPaymentMethod,
+        })
+      }
+
+      if (!shouldInputCard) {
+        return router.push(
+          pathname + "?" + createQueryString("step", "review"),
+          { scroll: false },
+        )
+      }
+    } catch (err: any) {
+      setError(err.message)
+    } finally {
+      setIsLoading(false)
+    }
+  }
+
+  useEffect(() => {
+    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
+    const controller = new AbortController()
+
+    const loadPayPalConfig = async () => {
+      try {
+        const response = await fetch(`${backendUrl}/store/paypal/config`, {
+          headers: key ? { "x-publishable-api-key": key } : {},
+          signal: controller.signal,
+        })
+
+        if (response.status === 403) {
+          setPaypalEnabled(false)
+          setCardEnabled(false)
+          return
+        }
+
+        if (!response.ok) return
+
+        const config = await response.json()
+
+        if (typeof config?.paypal_enabled === "boolean") setPaypalEnabled(config.paypal_enabled)
+        if (typeof config?.paypal_title === "string" && config.paypal_title) setPaypalTitle(config.paypal_title)
+        if (typeof config?.card_enabled === "boolean") setCardEnabled(config.card_enabled)
+        if (typeof config?.card_title === "string" && config.card_title) setCardTitle(config.card_title)
+      } catch (err) {
+        if ((err as Error).name !== "AbortError") setPaypalLoading(false)
+      }
+    }
+
+    void loadPayPalConfig()
+    return () => controller.abort()
+  }, [isOpen])
+
+  return (
+    <div className="bg-white">
+      <div className="flex flex-row items-center justify-between mb-6">
+        <Heading
+          level="h2"
+          className={clx(
+            "flex flex-row text-3xl-regular gap-x-2 items-baseline",
+            {
+              "opacity-50 pointer-events-none select-none":
+                !isOpen && !paymentReady,
+            },
+          )}
+        >
+          Payment
+          {!isOpen && paymentReady && <CheckCircleSolid />}
+        </Heading>
+        {!isOpen && paymentReady && (
+          <Text>
+            <button
+              onClick={handleEdit}
+              className="text-ui-fg-interactive hover:text-ui-fg-interactive-hover"
+              data-testid="edit-payment-button"
+            >
+              Edit
+            </button>
+          </Text>
+        )}
+      </div>
+
+      <div>
+        <div className={isOpen ? "block" : "hidden"}>
+          {!paidByGiftcard &&
+            filteredPaymentMethods.length > 0 &&
+            (paypalEnabled ||
+              cardEnabled ||
+              availablePaymentMethods.some((method) => !isPayPal(method.id))) && (
+              <>
+                <RadioGroup
+                  value={selectedPaymentMethod}
+                  onChange={(value: string) => setPaymentMethod(value)}
+                >
+                  {filteredPaymentMethods.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,
+                            ...(paymentMethod.id === PAYPAL_PROVIDER_ID
+                              ? {
+                                  [paymentMethod.id]: {
+                                    ...(paymentInfoMap[paymentMethod.id] || {}),
+                                    title: paypalTitle,
+                                  },
+                                }
+                              : {}),
+                            ...(paymentMethod.id === PAYPAL_CARD_PROVIDER_ID
+                              ? {
+                                  [paymentMethod.id]: {
+                                    ...(paymentInfoMap[paymentMethod.id] || {}),
+                                    title: cardTitle,
+                                  },
+                                }
+                              : {}),
+                          }}
+                          paymentProviderId={paymentMethod.id}
+                          selectedPaymentOptionId={selectedPaymentMethod}
+                        />
+                      )}
+                    </div>
+                  ))}
+                </RadioGroup>
+
+                {isPayPal(selectedPaymentMethod) && paypalLoading && (
+                  <div
+                    style={{
+                      display: "flex",
+                      alignItems: "center",
+                      gap: 12,
+                      padding: "14px 16px",
+                      marginTop: 8,
+                      background: "#f9fafb",
+                      border: "1px solid #e5e7eb",
+                      borderRadius: 10,
+                    }}
+                  >
+                    <style>{`@keyframes _idx_spin{to{transform:rotate(360deg)}}`}</style>
+                    <div
+                      style={{
+                        width: 20,
+                        height: 20,
+                        borderRadius: "50%",
+                        border: "2.5px solid #e5e7eb",
+                        borderTopColor: "#0070ba",
+                        animation: "_idx_spin .7s linear infinite",
+                        flexShrink: 0,
+                      }}
+                    />
+                    <div
+                      style={{
+                        fontSize: 13,
+                        fontWeight: 500,
+                        color: "#111827",
+                      }}
+                    >
+                      Setting up payment...
+                    </div>
+                  </div>
+                )}
+
+                {isPayPal(selectedPaymentMethod) && !paypalLoading && (
+                  <MedusaNextPayPalAdapter
+                    cartId={cart.id}
+                    selectedProviderId={selectedPaymentMethod}
+                    baseUrl={process.env.NEXT_PUBLIC_MEDUSA_BACKEND_URL!}
+                    publishableApiKey={process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY}
+                    onSuccess={async () => {
+                      await placeOrder(cart.id)
+                    }}
+                    onError={(message) => setError(message)}
+                  />
+                )}
+              </>
+            )}
+
+          {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}
+            data-testid="payment-method-error-message"
+          />
+
+          <Button
+            size="large"
+            className="mt-6"
+            onClick={handleSubmit}
+            isLoading={isLoading}
+            disabled={
+              (isStripeLike(selectedPaymentMethod) && !cardComplete) ||
+              (!selectedPaymentMethod && !paidByGiftcard) ||
+              isPayPal(selectedPaymentMethod)
+            }
+            data-testid="submit-payment-button"
+          >
+            {!activeSession && isStripeLike(selectedPaymentMethod)
+              ? "Enter card details"
+              : "Continue to review"}
+          </Button>
+        </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>
+  )
+}
+
+export default Payment
+```
+
+---
+
+## 🛡 Built-in payment protection
+
+You don't need to do anything for these — they're automatic:
+
+- **No double charges.** Once a customer has paid, the checkout only ever offers a *"Retry — finish placing my order"* button — even if the page is reloaded or the browser crashes mid-checkout.
+- **Always the right amount.** If the customer changes their cart during checkout, a fresh PayPal order is created at the new total.
+- **Clear messages.** Customers see friendly, actionable messages instead of technical errors, and a payment method you've disabled in Medusa Admin shows a polite "currently unavailable" note.
+
+<details>
+<summary><b>For developers</b></summary>
+
+<br>
+
+- `usePayPalPaymentMethods` returns an `error` field (non-null when the config fetch failed and the enabled flags are optimistic defaults).
+- Captured-state helpers are exported for custom flows: `markCartCaptured` / `wasCartCaptured` / `clearCartCaptured` (per-cart `sessionStorage` flag behind the reload-safe retry).
+- If your backend responds with `Access-Control-Allow-Origin: *`, pass `credentials: "omit"` to `createPayPalStoreApi({ ... })` — browsers block credentialed requests against a wildcard origin. Default stays `"include"`.
+
+</details>
+
+---
+
+## 🧪 Testing
+
+Toggle between sandbox and live in **Medusa Admin → Settings → PayPal → PayPal Connection → Environment**.
+
+**Sandbox buyer account** — 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.
+
+**Test card for Advanced Card Fields:**
+
+```
+Card number   4111 1111 1111 1111
+Expiry        Any future date
+CVV           Any 3 digits
+```
+
+---
+
+## 📄 License
+
 MIT © [Easy Payment](https://www.npmjs.com/package/@easypayment/medusa-paypal-ui)