Getting Started with PayPal Payment for Medusa

In this guide, you'll learn how to install and configure the PayPal payment provider for Medusa.

• Medusa v2.17.2 or later
• Node.js v22.23.4, v24.22.1, v26.12.1 or later
• A PayPal Business account – sign in or create one
• An app in the PayPal Developer Dashboard – sign in or create one
• Integration Module

yarn add @gorgo/medusa-integration @gorgo/medusa-payment-paypal

Add the configurations of the Integration Module provider and of the Medusa Payment Module in your medusa-config.ts file of the Medusa Admin application:

medusa-config.ts
1// ...
2const PAYPAL_INTEGRATION_ID = "paypal-1"
3
4module.exports = defineConfig({
5  // ...
6  plugins: [
7    // ...
8    {
9      resolve: "@gorgo/medusa-integration",
10      options: {
11        encryptionKey: process.env.INTEGRATION_ENCRYPTION_KEY,
12        providers: [
13          {
14            resolve: "@gorgo/medusa-payment-paypal/providers/integration-paypal",
15            id: PAYPAL_INTEGRATION_ID,
16            options: {},
17          },
18        ],
19      },
20    },
21    {
22      resolve: "@gorgo/medusa-payment-paypal",
23      options: {},
24    },
25  ],
26  modules: [
27    // ...
28    {
29      resolve: "@medusajs/medusa/payment",
30      options: {
31        providers: [
32          {
33            resolve: "@gorgo/medusa-payment-paypal/providers/payment-paypal",
34            id: "paypal",
35            options: {
36              id: PAYPAL_INTEGRATION_ID
37            }
38          },
39        ],
40      },
41    },
42  ],
43})

The payment provider registered this way gets the id pp_paypal_paypal, and its webhook route is /hooks/payment/paypal_paypal.

Add environment variables with your secret Encryption Key:

.env
INTEGRATION_ENCRYPTION_KEY=supersecret

The client ID, the secret key and the other PayPal settings are not provider options. You enter them in Medusa Admin, as described in Manage PayPal Settings in Medusa Admin.

To properly handle payment notifications from PayPal, configure the webhook URL in your PayPal app as following:

1. Open your app under Apps & Credentials, with the Sandbox or Live environment that matches the plugin's settings.

2. In the Webhooks section, click Add Webhook.

3. Add a new webhook URL in the following format:

   Webhook URL
   https://{YOUR_MEDUSA_DOMAIN}/hooks/payment/paypal_paypal

   Change {YOUR_MEDUSA_DOMAIN} with your medusa store domain.

4. Subscribe the webhook to the PAYMENT.AUTHORIZATION.CREATED and PAYMENT.CAPTURE.COMPLETED events, and save it.

5. Copy the webhook ID and enter it in the Webhook ID field of the PayPal settings in Medusa Admin. Test connection then checks that the webhook exists in that environment and is subscribed to both events.