Paypal
PayPal integration for Medusa v2
PayPal for Medusa
Accept PayPal and credit card payments in your Medusa v2 store โ built by an official PayPal Partner.
โจ What you get
| Feature | Details |
|---|---|
| ๐ต PayPal Buttons | One-click PayPal checkout for your customers |
| ๐ณ Card Payments | Secure credit & debit card fields, hosted by PayPal (PCI compliant) |
| ๐ Admin Dashboard | Connect your PayPal account and manage everything from Medusa Admin |
| ๐ Test & Live modes | Try everything safely in Sandbox before going live |
| ๐ 3D Secure | Extra card security, configurable in one click |
| ๐ Reliable by design | Payments are verified with PayPal at every step โ webhooks, retries, and safety nets are handled for you |
โ Requirements
- Medusa v2.12+
- Node.js 20+
- PostgreSQL
๐ Installation
In your Medusa backend folder, run:
โ๏ธ Setup โ 5 steps
1. Add the plugin to
2. Run database migrations
npx medusa db:migrate3. Connect your PayPal account
- Start your Medusa server
- Open Medusa Admin โ Settings โ PayPal
- Choose Sandbox (testing) or Live (real payments)
- Click Connect to PayPal and follow the steps
That's it โ your credentials are saved automatically. Webhooks are registered for you too.
๐ก Prefer manual setup? Click Insert credentials manually and paste your Client ID and Secret from developer.paypal.com.
4. Turn PayPal on in your region
Go to Medusa Admin โ Settings โ Regions โ your region and enable:
| Payment provider | What it is |
|---|---|
| PayPal Buttons | |
| Card payments |
5. Add PayPal to your storefront
The checkout UI comes as a separate package โ install it in your storefront project:
๐ฆ @easypayment/medusa-paypal-ui โ ready-made PayPal components for Next.js storefronts, with a step-by-step guide.
๐จ Customize (optional)
Everything is managed in Medusa Admin โ Settings โ PayPal โ changes apply instantly, no restart needed:
- PayPal Settings โ turn PayPal on/off, button color, shape, and label
- Advanced Card Payments โ turn card payments on/off, 3D Secure mode
- Additional Settings โ capture vs. authorize, brand name shown at PayPal, invoice prefix
๐ Going live โ two things we recommend
- โ set this to any long random text in your server's environment. Your PayPal credentials are then stored encrypted in the database. Keep the key safe: if it's lost, just reconnect PayPal.
- โ set this to your backend's public address (e.g. ) so PayPal can reach your store for payment notifications.
Advanced options (for developers โ everything works without these)
| Variable | Default | What it does |
|---|---|---|
| (request origin, if listed in ) | Storefront address used for PayPal return/cancel pages (can also be set in Admin) | |
| = refuse to save credentials unencrypted | ||
| (partner service nonce) | Only change this if you also run your own ; it must match the nonce that service puts in its onboarding links | |
| first entry | Restricts the onboarding popup to your admin URL | |
| Safety net that finishes an order when the payment succeeded but the buyer's browser closed. disables it | ||
| / | (off) / | Optional request limit for the public checkout routes |
| / | (off) / | Optional request limit for the webhook endpoint (separate from the above) |
| Rejects webhook deliveries older than this | ||
| When the retry job re-picks-up interrupted webhook events | ||
| / | (auto) | Manual webhook-id override (normally automatic) |
| Timeout for calls to PayPal | ||
| Fallback currency if none is configured | ||
| (unset) | Comma-separated URLs that receive operational alerts (including dead-lettered webhook events) | |
| In-process cache for plugin settings reads; disables | ||
| sends the cart's shipping address on PayPal orders () โ improves PayPal Seller Protection eligibility | ||
| (built-in) | Override the partner onboarding service used by the connect flow | |
| / | (built-in) | Override the partner merchant ids used for onboarding |
Declined cards: when PayPal declines a capture, responds with a buyer-friendly plus a structured object โ โ so storefronts can show "insufficient funds, try another card" and decide whether to offer a retry.
Monitoring: operational counters live in the table; every webhook is recorded in with automatic retries (events that exhaust retries are dead-lettered and pushed to ); audit events are logged as JSON lines tagged (secrets redacted).
๐ฌ Support
- ๐ Found a bug? Open an issue
- ๐ก Questions or feature requests? Start a discussion
- ๐ Storefront UI package: @easypayment/medusa-paypal-ui
๐ License
MIT ยฉ Easy Payment