@easypayment/medusa-paypal-ui

Production-ready PayPal storefront UI package for Medusa v2 + Next.js.

Includes:

• MedusaNextPayPalAdapter for checkout integration
• Smart Buttons support
• Advanced Card Fields support
• Runtime config loading from /store/paypal/config

Compatibility

• Next.js >=14
• React >=18
• Medusa backend with @easypayment/medusa-paypal

Step-by-step setup (GitHub style)

1) Install dependencies

npm install @easypayment/medusa-paypal-ui @paypal/react-paypal-js
# or
pnpm add @easypayment/medusa-paypal-ui @paypal/react-paypal-js
# or
yarn add @easypayment/medusa-paypal-ui @paypal/react-paypal-js

2) Add storefront environment variables

In your storefront .env.local:

NEXT_PUBLIC_MEDUSA_BACKEND_URL=https://your-medusa-api.example.com
NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY=pk_xxxxxxxxxxxxxxxxxxxxx

Never expose secret keys (sk_*) in NEXT_PUBLIC_* vars.

3) Ensure payment session uses PayPal provider IDs

Common provider IDs:

• pp_paypal_paypal
• pp_paypal_card_paypal_card

When the shopper selects a payment method, initialize a matching Medusa payment session.

4) Render MedusaNextPayPalAdapter in checkout

import { MedusaNextPayPalAdapter } from "@easypayment/medusa-paypal-ui"
import { initiatePaymentSession, placeOrder } from "@lib/data/cart"

const PAYPAL_IDS = ["pp_paypal_paypal", "pp_paypal_card_paypal_card"]

// Example on payment selection
async function setPaymentMethod(providerId: string) {
  await initiatePaymentSession(cart, { provider_id: providerId })
}

<MedusaNextPayPalAdapter
  cartId={cart.id}
  selectedProviderId={selectedPaymentMethod}
  baseUrl={process.env.NEXT_PUBLIC_MEDUSA_BACKEND_URL!}
  publishableApiKey={process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY}
  onSuccess={() => placeOrder(cart.id)}
  onError={(message) => setError(message)}
/>

5) Validate checkout flows

• Test PayPal Wallet flow.
• Test PayPal Advanced Card flow.
• Confirm order placement callback (onSuccess) runs.
• Confirm errors surface through onError.

Props

| Prop | Required | Description | |---|---|---| | cartId | ✅ | Active cart ID | | selectedProviderId | ✅ | Currently selected provider ID | | baseUrl | ✅ | Medusa backend URL | | publishableApiKey | optional | Medusa publishable key | | providerIds | optional | Override default provider IDs | | onSuccess | optional | Called after successful PayPal capture/authorize | | onError | optional | Called on payment error |

Provider ID mapping

Default adapter IDs:

paypal: "pp_paypal_paypal"
paypalCard: "pp_paypal_card_paypal_card"

If backend IDs differ, pass providerIds explicitly.

Quick checklist

• [ ] UI package installed
• [ ] Storefront env vars set
• [ ] Checkout initializes PayPal provider payment session
• [ ] Adapter rendered with required props
• [ ] Wallet + Card flows verified

Build and test (package development)

npm run build
npm test

License

MIT

UI note

The Advanced Card hosted fields (Card number, Expiration date, Security code) use style={cardStyle} on PayPalCardFieldsProvider, including cardStyle.input.height: "46px" (fontSize: 16px, padding: 12px 14px) so PayPal renders the iframe at the correct height and avoids clipping.