Medusa Payment Pesapal

A Pesapal payment provider plugin for Medusa v2 that enables seamless integration with Pesapal's payment gateway, supporting popular East African payment methods including M-Pesa, Airtel Money, and more.

Features

🔄 Full Payment Lifecycle: Support for authorization, capture, refunds, and cancellations
🌍 Multi-Currency: Support for KES, USD, EUR, GBP, UGX, TZS and more
📱 East African Payment Methods: M-Pesa, Airtel Money, Bank transfers, and credit cards
🔒 Secure: Industry-standard security practices with OAuth 2.0 authentication
🎛️ Admin Dashboard: Easy configuration and management through Medusa Admin
🔔 Webhooks: Real-time payment status updates via IPN (Instant Payment Notifications)
🧪 Sandbox Support: Full testing environment with provided test credentials
🌍 East African Payment Methods: Support for M-Pesa, Airtel Money, bank transfers, and card payments
🔒 Secure Authentication: OAuth 2.0 integration with Pesapal API v3
🎯 Sandbox & Production: Easy environment switching for testing and live payments
🎛️ Admin Configuration: Beautiful admin widget for easy setup and management
🔔 Webhook Support: Real-time payment status updates via IPN callbacks
💱 Multi-Currency: Support for KES, USD, EUR, GBP, UGX, TZS and more
⚡ Modern Architecture: Built specifically for Medusa v2 framework

Installation

npm install medusa-payment-pesapal
# or
yarn add medusa-payment-pesapal

Configuration

1. Add to medusa-config.ts

import { defineConfig } from '@medusajs/framework/utils'

export default defineConfig({
  modules: [
    {
      resolve: "@medusajs/medusa/payment",
      options: {
        providers: [
          {
            resolve: "medusa-payment-pesapal",
            id: "pesapal",
            options: {
              consumer_key: process.env.PESAPAL_CONSUMER_KEY,
              consumer_secret: process.env.PESAPAL_CONSUMER_SECRET,
              environment: process.env.PESAPAL_ENVIRONMENT || "sandbox",
              currency: process.env.PESAPAL_CURRENCY || "KES",
              merchant_name: process.env.PESAPAL_MERCHANT_NAME,
              ipn_url: process.env.PESAPAL_IPN_URL,
            }
          }
        ]
      }
    }
  ]
})

2. Environment Variables

Add these variables to your .env file:

# Pesapal Configuration
PESAPAL_CONSUMER_KEY=your_consumer_key
PESAPAL_CONSUMER_SECRET=your_consumer_secret
PESAPAL_ENVIRONMENT=sandbox # or 'live' for production
PESAPAL_CURRENCY=KES
PESAPAL_MERCHANT_NAME="Your Business Name"
PESAPAL_IPN_URL=https://yourdomain.com/pesapal/webhook

3. Sandbox Credentials (for testing)

For Kenyan merchants, you can use these test credentials:

PESAPAL_CONSUMER_KEY=qkio1BGGYAXTu2JOfm7XSXNruoZsrqEW
PESAPAL_CONSUMER_SECRET=osGQ364R49cXKeOYSpaOnT++rHs=

Admin Configuration

After installation, you can configure Pesapal directly from the Medusa Admin:

Navigate to the Orders section in your admin panel
Look for the "Pesapal Configuration" widget
Fill in your credentials and settings
Test the connection
Enable the payment provider

API Endpoints

The plugin automatically creates these endpoints:

GET /admin/custom/pesapal/config - Get current configuration
POST /admin/custom/pesapal/config - Save configuration
POST /admin/custom/pesapal/test - Test connection
GET /store/pesapal/webhook - Handle IPN callbacks
POST /store/pesapal/webhook - Handle IPN callbacks

Usage

In Your Storefront

The payment provider will be automatically available in your checkout flow. Customers can select Pesapal as a payment method and will be redirected to Pesapal's secure payment page.

Supported Payment Methods

M-Pesa (Kenya, Tanzania)
Airtel Money (Kenya, Uganda, Tanzania)
Bank Transfers (Multiple banks across East Africa)
Credit/Debit Cards (Visa, Mastercard)
Mobile Banking (Equity, KCB, etc.)

Currency Support

KES (Kenyan Shilling)
USD (US Dollar)
EUR (Euro)
GBP (British Pound)
UGX (Ugandan Shilling)
TZS (Tanzanian Shilling)

Development

Local Development

Clone the repository
Install dependencies: npm install
Build the plugin: npm run build
Link for local testing: npm link

Building

npm run build

Testing

npm test

Webhook Configuration

For production use, configure your webhook URL in the Pesapal merchant dashboard:

Login to your Pesapal merchant account
Go to Settings > IPN Settings
Set your IPN URL to: https://yourdomain.com/store/pesapal/webhook
Select the events you want to receive notifications for

Migration from v1

If you're migrating from Medusa v1, please note that this plugin is specifically designed for Medusa v2 and uses the new payment provider architecture.

Support

Documentation: Pesapal API Documentation
Issues: GitHub Issues
Community: Medusa Discord

Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests to help improve this plugin.

License

Author

Antony Ngigge (Machomaniac)

Made with ❤️ for the East African e-commerce community