@devxhub/medusa-payment-sslcommerz

A professional-grade Medusa v2 payment provider for SSLCommerz, the largest payment gateway in Bangladesh. This plugin enables seamless integration of SSLCommerz's Hosted Checkout and IPN (Instant Payment Notification) into your Medusa commerce engine.

---

🌟 Key Features

• Medusa v2 Ready: Fully optimized for the latest Medusa v2 architecture and modules.
• Hosted Checkout: Securely redirect customers to SSLCommerz's payment page.
• Automatic Capture: Configurable flow for automatic payment capturing upon validation.
• Robust Webhooks (IPN): Built-in handler for Instant Payment Notifications to ensure order status consistency even if the user closes their browser.
• Flexible Redirection: Dynamic Success, Failure, and Cancel URL management via Medusa Admin.
• Seamless Refunds: Support for standard Medusa refund flows directly through the SSLCommerz API.
• Detailed Metadata: Stores transaction IDs, bank IDs, and card details within Medusa's payment records.

---

📋 Prerequisites

Before installing, ensure you have:

• A Medusa v2 backend project.
• An SSLCommerz Merchant Account (Store ID and Store Password).
• sslcommerz-lts package installed (handled automatically).

---

🚀 Installation

Install the package via npm or yarn:

npm install @devxhub/medusa-payment-sslcommerz
# or
yarn add @devxhub/medusa-payment-sslcommerz

---

⚙️ Configuration

1. Register the Plugin

In your medusa-config.ts, add the plugin to the plugins array to enable Admin UI components and API hooks:

plugins: [
  // ... other plugins
  "@devxhub/medusa-payment-sslcommerz",
],

2. Configure the Payment Provider

Still in medusa-config.ts, add the provider to your payment module configuration:

modules: [
  {
    resolve: "@medusajs/medusa/payment",
    options: {
      providers: [
        {
          resolve: "@devxhub/medusa-payment-sslcommerz",
          id: "sslcommerz",
          options: {
            store_id: process.env.SSLCOMMERZ_STORE_ID,
            store_password: process.env.SSLCOMMERZ_STORE_PASSWORD,
            is_live: process.env.SSLCOMMERZ_IS_LIVE === "true",
            base_url: process.env.MEDUSA_BACKEND_URL,
          },
        },
      ],
    },
  },
],

3. Environment Variables

Variable	Description	Example
SSLCOMMERZ_STORE_ID	Your SSLCommerz Store ID	test_store123
SSLCOMMERZ_STORE_PASSWORD	Your SSLCommerz Store Password	password123
SSLCOMMERZ_IS_LIVE	Set to true for Production, false for Sandbox	false
MEDUSA_BACKEND_URL	The public URL of your Medusa backend	https://api.yourstore.com

---

🛠️ Integration & Usage

Admin UI Setup

This plugin includes an Admin UI extension to manage your storefront redirection URLs:

1. Log in to your Medusa Admin.
2. Navigate to Settings > SSLCommerz Settings.
3. Configure your Success URL, Failure URL, and Cancel URL. These are the pages on your Storefront where customers will be redirected after the payment process.

API Webhooks (IPN)

The plugin automatically exposes several endpoints to handle the SSLCommerz lifecycle:

• POST /hooks/payment/sslcommerz/success: Primary success handler.
• POST /hooks/payment/sslcommerz/fail: Primary failure handler.
• POST /hooks/payment/sslcommerz/cancel: Primary cancellation handler.
• POST /hooks/payment/sslcommerz/ipn: Instant Payment Notification handler (Server-to-Server).

Important

Ensure your MEDUSA_BACKEND_URL is accessible by SSLCommerz servers for the IPN to work correctly.

---

📊 Technical Reference

Payment Metadata

Upon successful payment, the following information is stored in the Medusa Payment object's data:

• tran_id: The unique SSLCommerz transaction ID.
• bank_tran_id: The bank's transaction reference.
• card_type: The payment method used (e.g., VISA, Mastercard, BKash).
• val_id: The SSLCommerz validation ID.

Development Commands

npm run build   # Build the plugin
npm run dev     # Watch for changes