@easypayment/medusa-paypal-ui 1.0.42 → 1.0.44

package/README.md

@@ -1,615 +1,818 @@
-<div align="center">
-
-<h1>🅿 medusa-paypal-frontend</h1>
-
-<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 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.
-
-| 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 |
-
----
-
-## 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)
-
----
-
-## Requirements
-
-- **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
-
-```bash
-npm install @easypayment/medusa-paypal-ui
-```
-
-```bash
-yarn add @easypayment/medusa-paypal-ui
-```
-
----
-
-## Environment Variables
-
-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_...
-```
-
-> **Where to get the publishable key:**
-> Medusa Admin → **Settings → API Key Management → Create API Key**
-
----
-
-## 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.
-
----
-
-### Step 1 — Add the import
-
-Add this import alongside your existing imports at the top of the file:
-
-```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)
-```
-
-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.
-
----
-
-### Step 3 — Add the config hook
-
-Add this hook call inside the component, directly after the `const isOpen = ...` line:
-
-```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,
-  })
-```
-
-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.
-
-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)`.
-
----
-
-### Step 5 — Filter the payment method list
-
-In your `RadioGroup`, add a `.filter()` before `.map()` to hide providers that have been disabled by the admin in the PayPal settings panel:
-
-```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
-  ))}
-```
-
----
-
-### Step 6 — Inject admin-configured titles
-
-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"
-
-import { RadioGroup } from "@headlessui/react"
-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 {
-  PayPalPaymentSection,
-  isPayPalProviderId,
-  usePayPalPaymentMethods,
-} from "@easypayment/medusa-paypal-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, useState } from "react"
-
-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 [paypalSessionLoading, setPaypalSessionLoading] = useState(false)
-
-  const searchParams = useSearchParams()
-  const router = useRouter()
-  const pathname = usePathname()
-
-  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) || isPayPalProviderId(method)) {
-      if (isPayPalProviderId(method)) setPaypalSessionLoading(true)
-      try {
-        await initiatePaymentSession(cart, { provider_id: method })
-      } finally {
-        setPaypalSessionLoading(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])
-
-  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 && 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}
-            data-testid="payment-method-error-message"
-          />
-
-          <Button
-            size="large"
-            className="mt-6"
-            onClick={handleSubmit}
-            isLoading={isLoading}
-            disabled={
-              (isStripeLike(selectedPaymentMethod) && !cardComplete) ||
-              (!selectedPaymentMethod && !paidByGiftcard) ||
-              isPayPalProviderId(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 number for Advanced Card fields**
-
-```
-Card number   4111 1111 1111 1111
-Expiry        Any future date
-CVV           Any 3 digits
-```
-
----
+<div align="center">
+
+<h1>🅿 medusa-paypal-frontend</h1>
+
+<p><strong>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 a React UI package that connects your Next.js (App Router) storefront to the `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 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 are rendered by `MedusaNextPayPalAdapter` |
+| **Storefront-controlled flow** | Your payment step controls session creation, loading states, and `placeOrder` |
+
+---
+
+## 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 PayPal helpers and state](#step-2---add-paypal-helpers-and-state)
+  - [Step 3 - Load config from /store/paypal/config](#step-3---load-config-from-storepaypalconfig)
+  - [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)
+
+---
+
+## Requirements
+
+- **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
+
+```bash
+npm install @easypayment/medusa-paypal-ui
+```
+
+```bash
+yarn add @easypayment/medusa-paypal-ui
+```
+
+---
+
+## Environment Variables
+
+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_...
+```
+
+> **Where to get the publishable key:**
+> Medusa Admin → **Settings → API Key Management → Create API Key**
+
+---
+
+## 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.
+
+---
+
+### Step 1 - Add the import
+
+Add this import alongside your existing imports at the top of the file:
+
+```tsx
+import { MedusaNextPayPalAdapter } from "@easypayment/medusa-paypal-ui"
+```
+
+---
+
+### Step 2 - Add PayPal helpers and state
+
+Inside the file, add PayPal provider helpers and the local state used by the updated implementation:
+
+```tsx
+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 [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 config from /store/paypal/config
+
+Instead of using a hook, fetch the PayPal config when the payment step is open:
+
+```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
+
+Replace your existing `setPaymentMethod` function with the following. The key addition is setting `paypalLoading` while the PayPal session is being created:
+
+```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
+
+Add a filtered payment method list before your `RadioGroup` render:
+
+```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 use `filteredPaymentMethods.map(...)` instead of rendering `availablePaymentMethods` directly.
+
+---
+
+### Step 6 - Inject admin-configured titles
+
+Inside your `.map()`, pass an overridden `paymentInfoMap` to the `PaymentContainer` component so the radio button labels reflect the values set in Medusa Admin:
+
+```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
+
+After the closing `</RadioGroup>` tag, render a loading state while the PayPal session is being prepared, then mount `MedusaNextPayPalAdapter`:
+
+```tsx
+{isPayPal(selectedPaymentMethod) && paypalLoading && (
+  <div>
+    <div>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)}
+  />
+)}
+```
+
+> **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
+
+Because PayPal renders its own checkout action, the storefront's "Continue to review" button must be disabled when PayPal is selected.
+
+Add `isPayPal(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) ||
+    isPayPal(selectedPaymentMethod)
+  }
+  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:
+
+```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"
+
+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 number for Advanced Card fields**
+
+```
+Card number   4111 1111 1111 1111
+Expiry        Any future date
+CVV           Any 3 digits
+```