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

---

✅ 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:

---

Step 5 — Configure settings (optional)

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

---

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