Paystack Payment Plugin v2

Robust Paystack payment integration for Medusa v2 with multi-currency support, webhook verification, and complete payment lifecycle management

Overview

The @alexasomba/medusa-paystack-plugin-v2 is a robust payment integration plugin for Medusa v2 that enables seamless payment processing using Paystack’s infrastructure. This plugin provides complete payment flow management with support for the new payment session lifecycle in Medusa v2.8.6+.

Key Features

• Complete Payment Flow - Initialize, authorize, capture, and refund payments
• Secure Transactions - Webhook verification for payment security
• Multi-Currency Support - NGN, USD, GHS, ZAR
• Paystack Popup Integration - Modern payment experience with retry capabilities
• Medusa v2 Compatible - Full compatibility with Medusa v2.8.6+
• Session Management - Intelligent session refresh and expiry handling
• Error Handling - Comprehensive error handling with user-friendly messaging

System Requirements

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

• Medusa server: v2.8.6 or later
• Node.js: v20 or later

Installation

Step 1: Install Package

# Using npm
npm install @alexasomba/medusa-paystack-plugin-v2

Step 2: Environment Configuration

Add to your .env file:

PAYSTACK_SECRET_KEY=sk_test_your_secret_key_here
PAYSTACK_PUBLIC_KEY=pk_test_your_public_key_here
PAYSTACK_WEBHOOK_SECRET=your_webhook_secret_here

Step 3: Medusa Configuration

Update medusa-config.ts:

modules: [
  {
    resolve: "@medusajs/payment",
    options: {
      providers: [
        {
          resolve: "@alexasomba/medusa-paystack-plugin-v2",
          id: "paystack",
          options: {
            secret_key: process.env.PAYSTACK_SECRET_KEY,
            public_key: process.env.PAYSTACK_PUBLIC_KEY,
            webhook_secret: process.env.PAYSTACK_WEBHOOK_SECRET,
          },
        },
      ],
    },
  },
]

Step 4: Build and Start

npm run build
npm run dev

Configuration Details

Frontend Integration

Required Dependencies

Install Paystack’s inline JavaScript library:

npm install @paystack/inline-js

Payment Component

The plugin works with Paystack’s popup interface. Implement payment handling in your checkout flow by:

1. Finding the Paystack session in the cart’s payment collection
2. Using a session hook to monitor readiness
3. Calling the PaystackPayment component when ready
4. Completing the cart upon successful payment

Session Hook

Create a custom usePaystackSession hook to manage payment session state, including:

• Readiness checks
• Session updates with the Medusa backend
• Error state management

Integration Pattern

// Example integration in checkout
const session = cart.payment_collection?.payment_sessions?.find(
  (s) => s.provider_id === "paystack"
)

// Use session hook
const { isReady, updateSession } = usePaystackSession(session)

// Render payment component when ready
{isReady && (
  <PaystackPayment
    session={session}
    onSuccess={handleSuccess}
    onFailure={handleFailure}
  />
)}

Supported Currencies

• NGN - Nigerian Naira
• USD - US Dollar
• GHS - Ghanaian Cedi
• ZAR - South African Rand

Core Dependencies

• @paystack/paystack-sdk (^1.2.1-beta.2) - Official Paystack SDK

Payment Operations

Initialize Payment

Creates a payment session with Paystack and generates a payment reference.

Authorize Payment

Verifies customer payment through Paystack’s secure popup.

Capture Payment

Captures authorized funds to complete the transaction.

Refund Payment

Processes refunds for completed transactions.

Webhook Integration

Configure webhooks in your Paystack dashboard to receive real-time payment status updates. The webhook secret ensures secure verification of webhook events.