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

---

✅ Requirements

• Medusa v2
• Node.js 18+
• PostgreSQL

---

🚀 Installation

In your Medusa backend directory, run:

npm install @easypayment/medusa-payment-paypal

---

⚙️ Setup

Step 1 — Configure medusa-config.ts

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

1import { loadEnv, defineConfig } from "@medusajs/framework/utils"
2
3loadEnv(process.env.NODE_ENV || "development", process.cwd())
4
5export default defineConfig({
6  projectConfig: {
7    databaseUrl: process.env.DATABASE_URL,
8    http: {
9      storeCors: process.env.STORE_CORS!,
10      adminCors: process.env.ADMIN_CORS!,
11      authCors: process.env.AUTH_CORS!,
12      jwtSecret: process.env.JWT_SECRET || "supersecret",
13      cookieSecret: process.env.COOKIE_SECRET || "supersecret",
14    },
15  },
16
17  plugins: [
18    {
19      resolve: "@easypayment/medusa-payment-paypal",
20      options: {},
21    },
22  ],
23
24  modules: [
25    {
26      resolve: "@medusajs/medusa/payment",
27      options: {
28        providers: [
29          {
30            // PayPal Smart Buttons (wallet checkout)
31            resolve: "@easypayment/medusa-payment-paypal/providers/paypal",
32            id: "paypal",
33            options: {},
34            dependencies: ["paypal_onboarding"],
35          },
36          {
37            // Advanced Card Fields (hosted card inputs)
38            resolve: "@easypayment/medusa-payment-paypal/providers/paypal_card",
39            id: "paypal_card",
40            options: {},
41            dependencies: ["paypal_onboarding"],
42          },
43        ],
44      },
45    },
46  ],
47})

---

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.

🔐 Encrypt secrets at rest (recommended for production). Set PAYPAL_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:

---

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 →

---

📊 Observability

• Metrics — operational counters (e.g. create_order_success, capture_order_failed, webhook_success, webhook_dead_letter) are persisted in the paypal_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 "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 paypal_webhook_event with status (processed / failed / dead_letter / ignored), attempt count, and last error; failures are retried by the paypal-webhook-retry job.

---

📄 License

MIT © Easy Payment