WonYaSoft Payment Plugin for Medusa

:warning: Under Active Development - This plugin is currently being developed and is not yet production-ready.

A Medusa v2 payment plugin for WonYaSoft (WonyaPay) - Mobile Money payment solutions for the Democratic Republic of Congo.

Table of Contents

• Features
• Requirements
• Installation
• Configuration
• Payment Flow
• API Usage
• Supported Providers
• Development
• Known Limitations
• Troubleshooting
• Support
• License

Features

• Mobile Money Support: M-Pesa, Airtel Money, Orange Money, AfriMoney
• Currency Support: CDF (Congolese Franc) and USD
• C2B Payments: Collect payments from customers via Mobile Money
• B2C Payments: Process refunds to customer Mobile Money accounts
• Automatic Authorization: Built-in polling for payment confirmation
• Transaction Status: Real-time status checking

Requirements

| Requirement | Version | |------------|---------| | Medusa | v2.x | | Node.js | >= 20 | | Medusa CLI | 2.x |

Installation

npm install @erulabs-tech/medusa-plugin-wonyapay
# or
pnpm add @erulabs-tech/medusa-plugin-wonyapay

Configuration

1. Add to medusa-config.ts

module.exports = defineConfig({
  // ... other config
  modules: [
    {
      resolve: "@medusajs/medusa/payment",
      options: {
        providers: [
          {
            resolve: "@erulabs-tech/medusa-plugin-wonyapay/providers/wonyapay",
            id: "payment-wonyapay",
            options: {
              apiKey: process.env.WONYAPAY_API_KEY,
              defaultReceiverID: process.env.WONYAPAY_DEFAULT_RECEIVER_ID,
              baseUrl: process.env.WONYAPAY_BASE_URL,
            },
          },
        ],
      },
    },
  ],
});

2. Environment Variables

Create a .env file with:

# WonYaSoft Payment Configuration
WONYAPAY_API_KEY=your_api_key_here
WONYAPAY_DEFAULT_RECEIVER_ID=your_receiver_id_here
WONYAPAY_BASE_URL=https://app-api.wonyasoft.com

Environment Variables Reference

| Variable | Required | Description | Default | |----------|----------|-------------|---------| | WONYAPAY_API_KEY | Yes | Your WonYaSoft API key (Bearer token) | - | | WONYAPAY_DEFAULT_RECEIVER_ID | Yes | Your merchant receiver ID | - | | WONYAPAY_BASE_URL | No | WonYaSoft API base URL | https://app-api.wonyasoft.com |

Payment Flow

┌─────────────────────────────────────────────────────────────────┐
│                    Payment Flow                                  │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  1. Customer selects "Mobile Money" at checkout                  │
│                                                                  │
│  2. Customer enters:                                              │
│     - Phone number (Mobile Money account)                        │
│     - Provider (M-Pesa, Airtel, Orange, AfriMoney)              │
│                                                                  │
│  3. initiatePayment() → POST /payment                            │
│     - Creates transaction                                        │
│     - Sends USSD prompt to customer phone                        │
│                                                                  │
│  4. authorizePayment() → Polls for confirmation                  │
│     ┌─────────────────────────────────────────────────────────┐  │
│     │ Poll 1: 60 seconds after initiatePayment                │  │
│     │ Poll 2: 30 seconds after Poll 1                         │  │
│     │ Poll 3: 30 seconds after Poll 2                         │  │
│     │ Max wait: 2 minutes                                     │  │
│     └─────────────────────────────────────────────────────────┘  │
│                                                                  │
│  5. Customer confirms payment on phone (enters PIN)              │
│                                                                  │
│  6. Payment authorized → Order completed                        │
│                                                                  │
│  7. If polls exhausted without confirmation → Payment failed    │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

API Usage

Create Payment Session

POST /store/payment-collections/:id/payment-sessions
Content-Type: application/json
x-publishable-api-key: pk_...

{
  "provider_id": "payment-wonyapay",
  "data": {
    "senderPhone": "+243851858485",
    "mobileProvider": "mpesa"
  }
}

Request Body Parameters

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | senderPhone | string | Yes | Customer's Mobile Money phone number | | mobileProvider | string | No | Provider: mpesa, airtel, orange, afrimoney |

Using Medusa JS SDK

// Create payment session with Mobile Money details
await sdk.store.paymentCollection.createPaymentSession(
  paymentCollectionId,
  {
    provider_id: "payment-wonyapay",
    data: {
      senderPhone: "+243851858485",
      mobileProvider: "mpesa",
    },
  }
);

// Complete payment (triggers authorizePayment)
await sdk.store.cart.complete(cartId);

cURL Example

curl -X POST http://localhost:9000/store/payment-collections/paycol_123/payment-sessions \
  -H "Content-Type: application/json" \
  -H "x-publishable-api-key: pk_your_key" \
  -d '{
    "provider_id": "payment-wonyapay",
    "data": {
      "senderPhone": "+243851858485",
      "mobileProvider": "mpesa"
    }
  }'

Supported Providers

| Provider | Code | Status | |----------|------|--------| | M-Pesa | mpesa | :white_check_mark: Supported | | Airtel Money | airtel | :white_check_mark: Supported | | Orange Money | orange | :white_check_mark: Supported | | AfriMoney | afrimoney | :white_check_mark: Supported |

Supported Currencies

| Currency | Code | Description | |----------|------|-------------| | Congolese Franc | CDF | Default currency | | US Dollar | USD | Supported |

WonYaSoft API Endpoints

| Endpoint | Method | Description | |----------|--------|-------------| | /payment | POST | Initiate payment (C2B/B2C) | | /transactionStatus/status/:ref | GET | Check transaction status |

Error Handling

Payment Status Mapping

| WonYaSoft Status | Medusa Status | Description | |------------------|---------------|-------------| | success | authorized | Payment confirmed | | pending | pending | Awaiting confirmation | | failed | error | Payment failed | | cancelled | canceled | Customer cancelled |

Error Scenarios

| Scenario | Result | Action | |----------|--------|--------| | Customer doesn't confirm within 2 minutes | error | Customer must retry | | Invalid phone number | error | Check and retry | | Insufficient funds | error | Customer must add funds | | API failure | error | Check API credentials |

Development

Prerequisites

• Node.js >= 20
• Medusa v2.x
• WonYaSoft API credentials

Build

npm run build

Watch Mode

npm run dev

Testing

npm run test

Known Limitations

:warning: Under Active Development - The following features are planned:

• [ ] Webhook support for instant notifications
• [ ] Admin dashboard configuration
• [ ] Payment retry mechanism
• [ ] Transaction history in admin
• [ ] SMS notifications for payment status
• [ ] Multiple receiver ID support

Troubleshooting

Payment stuck in "pending"

The customer may not have confirmed the payment on their phone. The payment will auto-fail after 2 minutes.

"Invalid phone number" error

Ensure the phone number:

• Starts with country code (e.g., +243 for DRC)
• Is registered with a Mobile Money provider
• Has sufficient funds

API connection errors

1. Verify WONYAPAY_API_KEY is correct
2. Verify WONYAPAY_DEFAULT_RECEIVER_ID is correct
3. Check network connectivity to WonYaSoft API

Support

• Email: [email protected]
• Phone: +243 892 672 472
• Website: https://wonyasoft.com

License

This project is licensed under the MIT License.