PayPal

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:

1
npm install @easypayment/medusa-payment-paypal

⚙️ Setup

Step 1 — Configure Copy to clipboardmedusa-config.ts

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

1234567891011121314151617181920
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-payment-paypal",
      options: {},

Step 2 — Run database migrations

1
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.

🔐 Encrypt secrets at rest (recommended for production). Set Copy to clipboardPAYPAL_ENCRYPTION_KEY to any strong random string. The seller client secret and PayPal app access token are then stored AES‑256‑GCM‑encrypted in the database; without it they are stored in plaintext (the previous default). Encryption is transparent — existing plaintext credentials keep working and are upgraded to ciphertext the next time they are saved/refreshed.



Keep this key safe and backed up: if it is lost, stored credentials cannot be decrypted and you must reconnect PayPal. Rotating the key requires re‑saving credentials.

Step 4 — Enable providers in your region

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

Provider ID Description Copy to clipboardpp_paypal_paypal PayPal Smart Buttons (wallet) Copy to clipboardpp_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 →

📊 Observability

• Metrics — operational counters (e.g. Copy to clipboardcreate_order_success, Copy to clipboardcapture_order_failed, Copy to clipboardwebhook_success, Copy to clipboardwebhook_dead_letter) are persisted in the Copy to clipboardpaypal_metric table.
• Audit trail — security/lifecycle events (credential changes, environment switches, webhook registration, capture/refund failures, alerts) are emitted as structured JSON log lines tagged Copy to clipboard"log":"paypal_audit". In production, ship stdout to your log aggregator and filter on that tag. Sensitive fields (secrets, tokens) are redacted before logging.
• Webhooks — every received event is recorded in Copy to clipboardpaypal_webhook_event with status (Copy to clipboardprocessed / Copy to clipboardfailed / Copy to clipboarddead_letter / Copy to clipboardignored), attempt count, and last error; failures are retried by the Copy to clipboardpaypal-webhook-retry job.

📄 License

MIT © Easy Payment