Medusa Payment iPay

A Medusa v2 payment provider plugin for iPay Africa, supporting multiple payment channels including M-Pesa, Airtel Money, Credit/Debit Cards, and PesaLink.

Features

• 🚀 Complete iPay Africa Integration - Full support for iPay's payment gateway
• 💳 Multiple Payment Channels:
  • M-Pesa (Safaricom Mobile Money)
  • Airtel Money
  • Credit/Debit Cards (Visa, Mastercard)
  • PesaLink (Bank transfers)
• 🔒 Secure Transactions - HMAC SHA1 signature verification
• 🎛️ Admin Configuration - Easy setup through Medusa Admin dashboard
• 🔄 Webhook Support - Real-time payment status updates
• 🧪 Test Mode - Sandbox environment for development
• 📱 Responsive Design - Works on desktop and mobile

Installation

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

Configuration

1. Add to medusa-config.ts

import { defineConfig } from "@medusajs/medusa"

export default defineConfig({
  // ... other config
  modules: [
    {
      resolve: "@medusajs/medusa/payment",
      options: {
        providers: [
          {
            resolve: "medusa-payment-ipay/providers/ipay",
            id: "ipay",
            options: {
              vid: process.env.IPAY_VID, // Your iPay Vendor ID
              hashKey: process.env.IPAY_HASH_KEY, // Your iPay Hash Key
              live: process.env.IPAY_LIVE === "true", // true for production, false for testing
              enabledChannels: {
                mpesa: true,
                airtel: true,
                creditcard: false, // Enable for card payments (requires PCI compliance)
                pesalink: false // Enable for bank transfers
              }
            }
          }
        ]
      }
    }
  ]
})

2. Environment Variables

Add these to your .env file:

# iPay Configuration
IPAY_VID=your_vendor_id
IPAY_HASH_KEY=your_hash_key
IPAY_LIVE=false  # Set to true for production

# For testing, use these values:
# IPAY_VID=demo
# IPAY_HASH_KEY=demoCHANGED

3. Admin Configuration

1. Navigate to your Medusa Admin dashboard
2. Go to Settings → Payment Providers
3. Enable the iPay provider for your sales regions
4. Configure your iPay credentials through the admin widget

Usage

Test Credentials

For development and testing:

• Vendor ID: demo
• Hash Key: demoCHANGED
• Live Mode: false

Test Card Numbers

When testing credit card payments:

• Success: 4444444444444444
• Failure: 3333333333333333

Payment Flow

1. Customer selects iPay as payment method during checkout
2. Customer is redirected to iPay's secure payment gateway
3. Customer chooses payment channel (M-Pesa, Airtel, Card, etc.)
4. Customer completes payment following iPay's interface
5. Customer is redirected back to your store
6. Webhook confirms payment status

API Reference

Payment Provider Options

interface IPayOptions {
  vid: string                    // iPay Vendor ID
  hashKey: string               // iPay Hash Key
  live: boolean                 // Production mode
  enabledChannels?: {
    mpesa?: boolean            // Enable M-Pesa
    airtel?: boolean           // Enable Airtel Money
    creditcard?: boolean       // Enable Credit/Debit Cards
    pesalink?: boolean         // Enable PesaLink
  }
}

Webhook Endpoint

The plugin automatically creates a webhook endpoint at:

POST /webhooks/ipay/{resource_id}
GET /webhooks/ipay/{resource_id}

iPay will send payment status updates to this endpoint.

Payment Status Mapping

iPay Status	Description	Medusa Status
aei7p7yrx4ae34	Success	AUTHORIZED
bdi6p2yy76etrs	Pending	PENDING
fe2707etr5s4wq	Failed	ERROR
dtfi4p7yty45wq	Less amount	ERROR
cr5i3pgy9867e1	Used code	ERROR

Development

Prerequisites

• Node.js 20+
• Medusa v2.4.0+

Setup

1. Clone the repository

git clone https://github.com/your-org/medusa-payment-ipay.git
cd medusa-payment-ipay

2. Install dependencies

yarn install

3. Build the plugin

yarn build

4. Run in development mode

yarn dev

Testing

# Run tests
yarn test

# Run with coverage
yarn test:coverage

Production Deployment

1. Get Production Credentials:

   • Register with iPay Africa
   • Obtain your production Vendor ID and Hash Key
   • Complete any required verification processes

2. Update Configuration:

   IPAY_VID=your_production_vid
   IPAY_HASH_KEY=your_production_hash_key
   IPAY_LIVE=true

3. Enable Payment Channels:

   • Configure which payment methods to accept
   • For credit cards, ensure PCI compliance
   • Test all payment flows

4. Webhook Configuration:

   • Ensure your webhook endpoint is accessible
   • Configure proper SSL certificates
   • Test webhook delivery

Troubleshooting

Common Issues

1. Payment fails with "hash mismatch"

   • Verify your hash key is correct
   • Ensure no extra spaces in environment variables
   • Check that all required parameters are included

2. Webhook not receiving callbacks

   • Verify webhook URL is publicly accessible
   • Check firewall settings
   • Ensure proper HTTPS configuration

3. Payment gateway not loading

   • Check if you're using correct iPay gateway URL
   • Verify VID and hash key are valid
   • Ensure live mode setting matches your credentials

Debug Mode

Enable debug logging:

// In your medusa-config.ts
export default defineConfig({
  projectConfig: {
    worker_mode: "server",
    // ... other config
  },
  // Add debug logging
  logger: {
    level: "debug"
  }
})

Contributing

Contributions are welcome! Please read our Contributing Guide for details.

Development Workflow

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass: yarn test
6. Commit your changes: git commit -m 'Add amazing feature'
7. Push to the branch: git push origin feature/amazing-feature
8. Open a Pull Request

Support

• 📧 Email: [e-mail]
• 💬 Discord: Join our community
• 🐛 Issues: GitHub Issues
• 📖 Documentation: Full documentation

Related Links

• iPay Africa Documentation
• Medusa Documentation
• Medusa Payment Provider Guide

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• iPay Africa for their payment gateway services
• Medusa team for the excellent e-commerce framework
• Contributors who help improve this plugin

---

⚠️ Important Notes:

• Always test in sandbox mode before going live
• Ensure PCI compliance when accepting credit card payments
• Keep your hash key secure and never commit it to version control
• Regularly update the plugin to get security fixes and new features