Bonaventure OgetoBy Bonaventure Ogeto|

Paystack with Medusa Commerce

Install the medusa-payment-paystack plugin, add it to medusa-config.js under plugins with your PAYSTACK_SECRET_KEY, then add the provider to your region (Settings → Regions → select region → Payment Providers → Enable Paystack). On the storefront, call POST /store/carts/:id/payment-sessions, select paystack, then call POST /store/carts/:id/payment-sessions/:provider_id/authorize to get the Paystack authorization_url.

Installing and Configuring the Medusa Paystack Plugin

npm install medusa-payment-paystack
// medusa-config.js
const plugins = [
  // ... other plugins
  {
    resolve: 'medusa-payment-paystack',
    options: {
      secret_key: process.env.PAYSTACK_SECRET_KEY,
    },
  },
];

module.exports = {
  projectConfig: {
    // ... your existing config
  },
  plugins,
};

Set the environment variable:

PAYSTACK_SECRET_KEY=sk_live_your_key_here

Restart your Medusa server. Then go to the Medusa admin dashboard → Settings → Regions → select your Africa region → Payment Providers → enable Paystack.

Storefront Checkout Flow

// In your Medusa storefront (Next.js example)
async function initializePaystackPayment(cartId) {
  // Create payment session
  await medusaClient.carts.createPaymentSessions(cartId);

  // Select Paystack as provider
  var cartData = await medusaClient.carts.setPaymentSession(cartId, {
    provider_id: 'paystack',
  });

  // Authorize payment — plugin calls Paystack initialize and returns the URL
  var { cart } = await medusaClient.carts.authorizePayment(cartId);

  // The plugin stores the Paystack authorization_url in payment session data
  var authUrl = cart.payment_session.data.authorization_url;
  window.location.href = authUrl; // redirect to Paystack checkout
}

// On callback page (after Paystack redirects back)
async function completePaystackPayment(cartId, reference) {
  // Verify with Paystack and complete the Medusa order
  var { type, data } = await medusaClient.carts.complete(cartId);
  if (type === 'order') {
    router.push('/order/' + data.id + '/confirmed');
  }
}

Learn More

See the Paystack plugins guide for other e-commerce platform integrations.

Sign up for the McTaba newsletter

Key Takeaways

  • Use the community medusa-payment-paystack plugin to add Paystack to Medusa.
  • Configure the plugin in medusa-config.js with your PAYSTACK_SECRET_KEY.
  • Enable Paystack in the Medusa admin under Settings → Regions → Payment Providers.
  • The plugin handles payment session creation, authorization URL generation, and webhook processing.
  • Medusa regions map to Paystack currencies — set your Africa region to use NGN, KES, or GHS as appropriate.

Frequently Asked Questions

Is medusa-payment-paystack an official Medusa plugin?
medusa-payment-paystack is a community plugin, not maintained by the Medusa core team. Check the npm package for its maintenance status and last publish date before using it in production. If the community plugin is outdated, you can build a custom Medusa payment provider using Medusa's PaymentService base class and the Paystack API directly.
How do Medusa regions map to Paystack countries?
Create separate Medusa regions for each Paystack country you support. For example: Nigeria region (currency: NGN, countries: NG), Kenya region (currency: KES, countries: KE). Each region can have Paystack enabled. Your Medusa storefront detects the customer's country and switches to the appropriate region and currency.
How does the Paystack webhook work with Medusa?
The medusa-payment-paystack plugin registers a webhook handler at /paystack/hooks (or similar) in your Medusa backend. Configure Paystack to send webhooks to this endpoint. The plugin handles HMAC validation and updates the Medusa payment session status when charge.success arrives.

Ready to build real-world apps?

Join the McTaba Labs full-stack marathon (4 months full-time · 6 months part-time). Learn M-Pesa, USSD, and WhatsApp engineering while shipping 8 production apps.

Apply to the McTaba Marathon