PayPal for Medusa

Accept PayPal and advanced credit card payments in your Medusa v2 store — built by an official PayPal Partner.

---

📋 Table of Contents

• 📦 What's included
• ✅ Requirements
• 🚀 Installation
• ⚙️ Setup
  • Step 1 — Configure medusa-config.ts
  • Step 2 — Run database migrations
  • Step 3 — Connect your PayPal account
  • Step 4 — Enable providers in your region
  • Step 5 — Configure settings
  • Step 6 — Add PayPal to your storefront
• 📄 License

---

📦 What's included

Feature	Details
🔵 PayPal Smart Buttons	One-click wallet checkout via PayPal
💳 Advanced Card Fields	Hosted, PCI-compliant advanced credit card inputs
🛠 Admin Dashboard	Connect, configure, and switch environments from Medusa Admin
🌍 Sandbox & Live	Toggle between test and production without restarting
⚡ Webhooks	Automatically registered and verified with built-in retry support
🔐 3D Secure	Configurable SCA/3DS per transaction

---

✅ Requirements

• Medusa v2
• Node.js 18+
• PostgreSQL

---

🚀 Installation

In your Medusa backend directory, run:

npm install @easypayment/medusa-paypal

---

⚙️ Setup

Step 1 — Configure medusa-config.ts

Add the plugin and both payment providers to your existing medusa-config.ts:

import { loadEnv, defineConfig } from "@medusajs/framework/utils"

loadEnv(process.env.NODE_ENV || "development", process.cwd())

export default defineConfig({
  projectConfig: {
    databaseUrl: process.env.DATABASE_URL,
    http: {
      storeCors: process.env.STORE_CORS!,
      adminCors: process.env.ADMIN_CORS!,
      authCors: process.env.AUTH_CORS!,
      jwtSecret: process.env.JWT_SECRET || "supersecret",
      cookieSecret: process.env.COOKIE_SECRET || "supersecret",
    },
  },

  plugins: [
    {
      resolve: "@easypayment/medusa-paypal",
      options: {},
    },
  ],

  modules: [
    {
      resolve: "@medusajs/medusa/payment",
      options: {
        providers: [
          {
            // PayPal Smart Buttons (wallet checkout)
            resolve: "@easypayment/medusa-paypal/providers/paypal",
            id: "paypal",
            options: {},
            dependencies: ["paypal_onboarding"],
          },
          {
            // Advanced Card Fields (hosted card inputs)
            resolve: "@easypayment/medusa-paypal/providers/paypal_card",
            id: "paypal_card",
            options: {},
            dependencies: ["paypal_onboarding"],
          },
        ],
      },
    },
  ],
})

---

Step 2 — Run database migrations

npx medusa db:migrate

---

Step 3 — Connect your PayPal account

1. Start your Medusa server
2. Open Medusa Admin → Settings → PayPal → PayPal Connection
3. Choose Sandbox (testing) or Live (production)
4. Click Connect to PayPal and complete the onboarding flow

Credentials are saved automatically. Prefer manual setup? Click Insert credentials manually and paste your Client ID and Secret from developer.paypal.com.

---

Step 4 — Enable providers in your region

1. Go to Medusa Admin → Settings → Regions → [your region]
2. Under Payment Providers, enable:

Provider ID	Description
pp_paypal_paypal	PayPal Smart Buttons (wallet)
pp_paypal_card_paypal_card	Advanced Card Fields (card)

---

Step 5 — Configure settings (optional)

All settings live in Medusa Admin → Settings → PayPal and apply immediately — no server restart needed.

Tab	What you can configure
PayPal Settings	Enable/disable, button color, shape, label
Advanced Card Payments	Enable/disable, 3D Secure mode
Additional Settings	Payment action (capture / authorize), brand name, invoice prefix

---

Step 6 — Add PayPal to your storefront

The checkout UI is shipped as a separate package — install it inside your storefront project, not in this backend.

📦 @easypayment/medusa-paypal-ui — React components, hooks, and a drop-in payment step adapter for Next.js App Router storefronts.

See the storefront integration & testing guide →

---

📄 License

MIT © Easy Payment