PayPal Payment Provider (Alphabite)

Alphabite's Medusa PayPal plugin with support for payment captures, refunds, shipping data, and comprehensive error handling

Overview

The @alphabite/medusa-paypal plugin provides seamless PayPal payment integration for Medusa stores with comprehensive support for payment captures, refunds, and error handling. This plugin is designed for Medusa v2+ and includes advanced features like shipping data integration and admin-integrated refund functionality.

Key Features

• Seamless PayPal Integration - Easy integration with Medusa v2+
• Payment Capture & Refunds - Full payment lifecycle management
• Comprehensive Error Handling - Robust error management system
• Shipping Data Support - Optional shipping and customer data inclusion
• Admin Refund Integration - Refund functionality integrated into Medusa Admin
• Phone Number Validation - Built-in validation using libphonenumber-js

System Requirements

Before installing the plugin, ensure your system meets the following requirements:

• Medusa server: v2.x or later
• Node.js: v20 or later

Installation

Install the plugin using your preferred package manager:

# Using npm
npm install @alphabite/medusa-paypal

Configuration

Add the plugin to your medusa-config.js file:

module.exports = {
  modules: [
    {
      resolve: "@medusajs/medusa/payment",
      options: {
        providers: [
          {
            resolve: "@alphabite/medusa-paypal",
            id: "paypal",
            options: {
              clientId: process.env.PAYPAL_CLIENT_ID,
              clientSecret: process.env.PAYPAL_CLIENT_SECRET,
              sandbox: process.env.PAYPAL_SANDBOX === "true",
              intent: "CAPTURE",
              includeShipping: true, // Optional: include shipping data
              includeCustomer: true, // Optional: include customer data
            }
          }
        ]
      }
    }
  ]
}

Environment Variables

Add the following environment variables to your .env file:

PAYPAL_CLIENT_ID=your_paypal_client_id
PAYPAL_CLIENT_SECRET=your_paypal_client_secret
PAYPAL_SANDBOX=true

Core Dependencies

• @paypal/paypal-server-sdk (1.0.0) - Official PayPal server SDK
• libphonenumber-js (^1.12.9) - Phone number parsing and validation

Payment Operations

Payment Capture

The plugin automatically handles payment capture through PayPal’s standard workflow:

1. Customer selects PayPal as payment method
2. Customer approves payment on PayPal
3. Payment is captured and order is confirmed

Refunds

Refunds can be processed directly from the Medusa Admin interface:

1. Navigate to the order in Medusa Admin
2. Select the refund option
3. Specify the refund amount
4. Refund is processed through PayPal

Error Handling

The plugin includes comprehensive error handling for:

• Payment authorization failures
• Network connectivity issues
• Invalid credentials
• Refund processing errors
• Data validation errors

Advanced Configuration

Shipping Data Integration

Enable shipping data transmission to PayPal:

options: {
  includeShipping: true,
  // ... other options
}

Customer Data Integration

Enable customer data transmission to PayPal:

options: {
  includeCustomer: true,
  // ... other options
}