P

Pesapal

Pesapal payment provider plugin for Medusa v2 - Accept payments via Pesapal gateway with support for M-Pesa, Airtel Money, and other East African payment methods

Need customizations for this plugin?

Get in touch

npm install medusa-payment-pesapal

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 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 current configuration
- Save configuration
- Test connection
- Handle IPN callbacks
- 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:
Build the plugin:
Link for local testing:

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:
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.