PayU Payment Plugin for MedusaJS 2

PayU India payment gateway plugin for MedusaJS 2.x with redirect-based checkout flow.

Features

• ✅ Redirect-based checkout - Seamless PayU hosted checkout integration
• ✅ Webhook support - Automatic payment status updates via PayU webhooks
• ✅ Refund support - Full and partial refunds through PayU API
• ✅ Hash verification - Secure SHA-512 transaction validation
• ✅ TypeScript - Full type safety with comprehensive type definitions
• ✅ Payment verification workflow - Built-in workflow for custom payment verification

Installation

npm install medusa-payu-payment-plugin
# or
yarn add medusa-payu-payment-plugin

Configuration

1. Environment Variables

Add to your .env file:

# PayU Credentials
PAYU_MERCHANT_KEY=your_merchant_key
PAYU_MERCHANT_SALT=your_merchant_salt
PAYU_ENVIRONMENT=test  # or "production"

# Your storefront URL (for redirect callbacks)
STOREFRONT_URL=http://localhost:8000

2. MedusaJS Config

Add to your medusa-config.ts:

import { defineConfig } from "@medusajs/framework/utils"

export default defineConfig({
  // ... other config
  modules: [
    {
      resolve: "@medusajs/medusa/payment",
      options: {
        providers: [
          {
            resolve: "medusa-payu-payment-plugin/providers/payu",
            id: "payu",
            options: {
              merchantKey: process.env.PAYU_MERCHANT_KEY,
              merchantSalt: process.env.PAYU_MERCHANT_SALT,
              environment: process.env.PAYU_ENVIRONMENT || "test",
            },
          },
        ],
      },
    },
  ],
})

3. Enable for Region

In Medusa Admin:

1. Go to Settings → Regions
2. Select your region
3. Add payu as a payment provider

Frontend Integration

Payment Flow Overview

1. Customer selects PayU at checkout
2. Frontend retrieves payment session from cart
3. Frontend creates a form and redirects to PayU
4. Customer completes payment on PayU's hosted page
5. PayU redirects back to your storefront
6. Webhook updates order status automatically

React/Next.js Example

"use client"

function PayUPaymentButton({ cart }) {
  const handlePayment = async () => {
    // Get PayU payment session
    const paymentSession = cart.payment_collection?.payment_sessions?.find(
      (session) => session.provider_id === "pp_payu_payu"
    )

    if (!paymentSession?.data?.form_data) {
      console.error("PayU session not found")
      return
    }

    const { form_data, paymentUrl } = paymentSession.data

    // Create and submit hidden form
    const form = document.createElement("form")
    form.method = "POST"
    form.action = paymentUrl

    Object.entries(form_data).forEach(([key, value]) => {
      const input = document.createElement("input")
      input.type = "hidden"
      input.name = key
      input.value = String(value)
      form.appendChild(input)
    })

    document.body.appendChild(form)
    form.submit()
  }

  return (
    <button 
      onClick={handlePayment}
      className="btn-primary"
    >
      Pay with PayU
    </button>
  )
}

Payment Session Structure

The payment session data contains:

{
  txnid: string           // Unique transaction ID
  amount: string          // Amount with 2 decimals (e.g., "999.00")
  productinfo: string     // Product/order description
  firstname: string       // Customer first name
  email: string           // Customer email
  phone: string           // Customer phone
  hash: string            // Security hash (SHA-512)
  paymentUrl: string      // PayU checkout URL
  status: string          // Payment status
  form_data: {            // Ready-to-submit form data
    key: string           // Merchant key
    txnid: string
    amount: string
    productinfo: string
    firstname: string
    email: string
    phone: string
    surl: string          // Success redirect URL
    furl: string          // Failure redirect URL
    hash: string
    service_provider: string
  }
}

Webhook Setup

Configure the webhook URL in your PayU dashboard:

https://your-backend.com/hooks/payment/pp_payu_payu

The webhook handler automatically:

• Verifies the response hash for security
• Updates payment status (authorized/failed)
• Triggers order completion workflow

API Reference

Provider ID

pp_payu_payu

Supported Methods

Exported Workflow

You can use the verify payment workflow in your custom code:

import { verifyPayuPaymentWorkflow } from "medusa-payu-payment-plugin/workflows"

// In your API route or subscriber
const { result } = await verifyPayuPaymentWorkflow(container).run({
  input: {
    txnid: "TXN_1234567890_abcd",
  },
})

if (result.success) {
  console.log("Payment status:", result.status)
  console.log("Transaction details:", result.transaction)
}

Environment Variables

Testing

Use PayU test credentials in your test environment:

• Test URL: https://test.payu.in
• Test Cards: PayU Test Cards Documentation

Common Test Card Numbers

Troubleshooting

Hash Mismatch Error

Ensure:

1. You're using the correct Salt version (this plugin uses Salt V1)
2. Amount has exactly 2 decimal places (e.g., "999.00")
3. All mandatory fields match exactly between hash generation and form submission

Webhook Not Received

1. Verify webhook URL is correct in PayU dashboard
2. Ensure your server is publicly accessible
3. Check server logs for incoming webhook requests
4. Verify SSL certificate is valid (required for production)

Payment Session Not Found

Ensure:

1. PayU is enabled as a payment provider for the region
2. Payment collection is initialized before accessing session
3. Provider ID is pp_payu_payu (includes the prefix)

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT © SAM-AEL

See LICENSE for more information.

Links

• GitHub Repository
• npm Package
• PayU Developer Documentation
• MedusaJS Documentation
• Changelog