Integration Module 2.0 for Medusa is outRead the announcement
PayPal logo

PayPal

Use PayPal as a payment provider

npm install @alphabite/medusa-paypal
Category
Built by
Service
Version
0.2.6
Last updated
7 months ago
Monthly downloads
Loading downloads

๐Ÿ“ PayPal Plugin for Medusa

Discord Documentation

The Alphabite PayPal Plugin integrates PayPal payment processing into your Medusa store. It handles various payment flows, including capturing payments, managing refunds, and ensuring robust error handling.


๐Ÿ”ข Version Compatibility

Pick the plugin version that matches your Medusa backend version:

Medusa VersionPlugin VersionInstall Command

Instructions

  • Medusa 2.13.* and above: Install the latest version of the plugin. This is the actively maintained release and is required for compatibility with the latest Medusa APIs.
  • Medusa below 2.13.*: Pin the plugin to version . Later plugin versions rely on APIs introduced in Medusa 2.13 and will not work on older backends.

Before installing, verify your Medusa version:

npm list @medusajs/medusa

Then install the matching plugin version:

โš ๏ธ Use the same plugin version across local, staging, and production to avoid runtime errors.


๐Ÿ“ PayPal Plugin for Medusa

Discord Documentation

The Alphabite PayPal Plugin integrates PayPal payment processing into your Medusa store. It handles various payment flows, including capturing payments, managing refunds, and ensuring robust error handling.


๐Ÿ“š Table of Contents


๐ŸŽฏ Core Features

  • โœ… Seamless PayPal payment integration
  • ๐Ÿ”„ Handles various PayPal error states
  • ๐Ÿ’ฐ Supports refunds directly from Medusa Admin
  • ๐Ÿ›’ Creates new order IDs for each payment attempt within the same payment intent
  • ๐Ÿ“ฆ Optional inclusion of shipping and customer data in PayPal orders

๐Ÿงฑ Compatibility

  • Backend: Medusa v2+
  • Frontend: Framework-agnostic (integrates with PayPal's SDK)
  • Admin: Refund functionality integrated into Medusa Admin

๐Ÿ›  Common Use Cases

  • Accepting PayPal payments for products and services
  • Managing payment captures and refunds efficiently
  • Ensuring robust payment processing with comprehensive error handling

๐Ÿ“– Documentation

For complete documentation, visit our PayPal Plugin Documentation.



๐Ÿ“ฆ Installation

This guide walks you through installing and configuring the Alphabite PayPal Plugin in your Medusa backend.


1. Install the Plugin

Install the package via npm:


2. Register the Plugin

Add the plugin to your or :


โš™๏ธ Plugin Options

The following options can be passed to the PayPal plugin in your or file:

OptionTypeDefaultDescription
Required. Your PayPal API client ID.
Required. Your PayPal API client secret.
Whether to use the PayPal Sandbox environment for testing.
Optional. Your PayPal webhook ID. If provided, enables confirmation of payment captures.
Optional. If , shipping data from the storefront order will be added to the PayPal order.
Optional. If , customer data from the storefront order will be added to the PayPal order.

โœ… Compatibility

  • Requires Medusa v2
  • Compatible with both JS and TypeScript projects

๐Ÿš€ Next Steps

๐Ÿ‘‰ Configuration Guide ๐Ÿ‘‰ Join our Discord Community for faster support


๐Ÿ’ป Front End Integration

This guide explains how to integrate the PayPal payment flow into your Next.js storefront using .

1. Install Dependencies

Install the official PayPal React SDK:

2. Environment Variables

Ensure your public PayPal Client ID is available in your environment variables:

NEXT_PUBLIC_PAYPAL_CLIENT_ID=your_paypal_client_id

3. Implementation Overview

The integration involves wrapping your payment form with and .

Key Components:

  • : Loads the PayPal SDK script.
  • : Manages the state and callbacks for the card fields.
  • : Renders the secure input fields.

4. Code Example

Here is a simplified structure of how to implement the PayPal payment component, based on :

5. Payment Flow Details

  1. Client Token: You must fetch a client token from your Medusa backend () and pass it to . This authorizes the client to perform actions on behalf of your account.
  2. Create Order: The callback is triggered when the user attempts to pay. It should initialize a payment session in Medusa and return the PayPal Order ID.
  3. On Approve: The callback runs after PayPal successfully authorizes the payment. Use this to complete the order in Medusa (e.g., ).