Pesapal Payment Provider

Pesapal payment gateway integration for Medusa v2 with support for M-Pesa, Airtel Money, and East African payment methods

Overview

The medusa-payment-pesapal plugin is a payment provider integration for Medusa v2 that connects to Pesapal’s payment gateway. This plugin enables East African merchants to process payments through M-Pesa, Airtel Money, bank transfers, and card payments.

Key Features

Complete Payment Lifecycle - Authorization, capture, refunds, and cancellations
Multi-Currency Support - KES, USD, EUR, GBP, UGX, TZS
OAuth 2.0 Authentication - Secure integration with Pesapal API v3
Webhook/IPN Integration - Real-time payment status updates
Admin Configuration Widget - Easy setup through Medusa Admin
Sandbox Support - Test environment for development
East African Payment Methods - M-Pesa, Airtel Money, mobile banking

System Requirements

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

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

Installation

Install the plugin using your preferred package manager:

# Using npm
npm install medusa-payment-pesapal

Configuration

Step 1: Update medusa-config.ts

Add the Pesapal provider to your Medusa configuration file:

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,
            }
          }
        ]
      }
    }
  ]
})

Step 2: Environment Variables

Configure your .env file with these variables:

PESAPAL_CONSUMER_KEY=your_consumer_key
PESAPAL_CONSUMER_SECRET=your_consumer_secret
PESAPAL_ENVIRONMENT=sandbox
PESAPAL_CURRENCY=KES
PESAPAL_MERCHANT_NAME="Your Business Name"
PESAPAL_IPN_URL=https://yourdomain.com/pesapal/webhook

Step 3: Test Credentials (Sandbox)

For sandbox testing in Kenya, use these credentials:

PESAPAL_CONSUMER_KEY=qkio1BGGYAXTu2JOfm7XSXNruoZsrqEW
PESAPAL_CONSUMER_SECRET=osGQ364R49cXKeOYSpaOnT++rHs=

Admin Configuration

After installation, configure Pesapal through Medusa Admin:

Navigate to the Orders section
Locate the “Pesapal Configuration” widget
Enter your credentials
Test the connection
Enable the provider

API Endpoints

The plugin provides the following endpoints:

GET /admin/custom/pesapal/config - Retrieve current settings
POST /admin/custom/pesapal/config - Save new configuration
POST /admin/custom/pesapal/test - Verify connection
GET /store/pesapal/webhook - Receive IPN callbacks
POST /store/pesapal/webhook - Process webhook events

Supported Payment Methods

The plugin accepts:

M-Pesa - Kenya’s leading mobile money platform
Airtel Money - Mobile money across East Africa
Bank Transfers - Direct bank transfers
Card Payments - Visa and Mastercard
Mobile Banking - Equity, KCB, and other platforms

Currency Support

Process transactions in:

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

Webhook Configuration

For production environments, register your webhook URL in the Pesapal merchant dashboard:

Log into your Pesapal account
Go to Settings → IPN Settings
Set IPN URL to: https://yourdomain.com/store/pesapal/webhook
Select desired notification events

Migration Notes

This plugin is designed specifically for Medusa v2 and uses the newer payment provider architecture, making it incompatible with v1 installations.

Support Resources

API Documentation: Pesapal Developer Portal
Repository: GitHub
Issues: Report issues on GitHub
Community: Medusa Discord server

See all guides