PayU

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

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

Configuration

1. Environment Variables

Add to your Copy to clipboard.env file:

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

# Redirect URLs
STOREFRONT_URL=http://localhost:8000
PAYU_REDIRECT_URL=/order/confirmed
PAYU_REDIRECT_FAILURE_URL=/checkout?payment_status=failed

2. MedusaJS Config

Add to your Copy to clipboardmedusa-config.ts:

1234567891011121314151617181920
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 Copy to clipboardpayu 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

Required Customer Data

When creating a payment session, the following customer data is required:

• Email - Customer email address
• Name - Customer first name
• Phone - Uses fallback chain: customer phone → billing address phone (from context) → shipping address phone
• Cart ID & Customer ID - Passed as UDF fields (udf1/udf2) for traceability (optional but recommended)

The phone number fallback uses MedusaJS's Copy to clipboardPaymentProviderContext which provides the customer and billing address data. If the billing address phone is not available, pass the shipping address phone when initiating payment.

It is also highly recommended to pass Copy to clipboardcart_id and Copy to clipboardcustomer_id so they persist through to the webhook even if the session is lost.

1234567
// When creating payment session, include in data:
{
  shipping_address_phone: cart.shipping_address?.phone,
  cart_id: cart.id,        // Mapped to udf1
  customer_id: customer.id, // Mapped to udf2
  country_code: "in"       // For URL construction
}

React/Next.js Example

1234567891011121314151617181920
"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

Payment Session Structure

The payment session data contains:

1234567891011121314151617181920
{
  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

Webhook Setup

PayU webhooks (S2S callbacks) ensure reliable payment status updates even when browser redirects fail.

1. Configure Webhook URL in PayU Dashboard

1. Log in to PayU Dashboard
2. Go to Settings → Webhooks (or Developer Settings → Webhooks)
3. Click Create Webhook or Add Webhook URL
4. Enter your webhook URL:

1
https://your-backend.com/hooks/payment/payu_payu

1. Select events to subscribe:
   • Copy to clipboardpayment.success - Payment completed successfully
   • Copy to clipboardpayment.failed - Payment failed
   • Copy to clipboardpayment.pending - Payment is pending (optional)
2. Save the configuration

2. Webhook Security

The plugin automatically handles security:

• Hash Verification: Every webhook is verified using SHA-512 reverse hash
• Formula: Copy to clipboardsha512(SALT|status||||||udf5|udf4|udf3|udf2|udf1|email|firstname|productinfo|amount|txnid|key)
• Tampered webhooks are rejected and logged for investigation

The webhook also logs Copy to clipboardcart_id (from udf1) and Copy to clipboardcustomer_id (from udf2) for easier debugging and reconciliation.

3. Content Type Support

PayU sends webhooks as URL-encoded form data:

• Copy to clipboardapplication/x-www-form-urlencoded
• Copy to clipboardmultipart/form-data

MedusaJS handles both content types automatically.

4. What Happens on Webhook

Status Action Result Copy to clipboardsuccess Copy to clipboardauthorized Payment session authorized, cart completed, order created Copy to clipboardfailure/Copy to clipboardfailed Copy to clipboardfailed Payment session marked as failed Other Copy to clipboardnot_supported Logged for debugging, no action taken

API Reference

Provider ID

1
pp_payu_payu

Supported Methods

Method Description Copy to clipboardinitiatePayment Creates payment session with hash and form data Copy to clipboardauthorizePayment Verifies payment status with PayU API Copy to clipboardcapturePayment Marks payment as captured (auto-capture enabled) Copy to clipboardrefundPayment Initiates full or partial refund Copy to clipboardcancelPayment Cancels pending payment Copy to clipboardgetWebhookActionAndData Handles PayU webhook callbacks

Exported Workflow

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

12345678910111213
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

Variable Description Required Copy to clipboardPAYU_MERCHANT_KEY PayU Merchant Key Yes Copy to clipboardPAYU_MERCHANT_SALT PayU Merchant Salt (Salt V1) Yes Copy to clipboardPAYU_ENVIRONMENT Copy to clipboardtest or Copy to clipboardproduction No (default: Copy to clipboardtest) Copy to clipboardSTOREFRONT_URL Your storefront base URL (e.g., Copy to clipboardhttp://localhost:8000) Yes Copy to clipboardPAYU_REDIRECT_URL Success redirect path (e.g., Copy to clipboard/order/confirmed) Yes Copy to clipboardPAYU_REDIRECT_FAILURE_URL Failure redirect path (e.g., Copy to clipboard/checkout?payment_status=failed) Yes

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

Card Type Number CVV Expiry Visa 4012001038443335 123 Any future date Mastercard 5123456789012346 123 Any future date

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., Copy to clipboard"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 Copy to clipboardpp_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 (Copy to clipboardgit checkout -b feature/amazing-feature)
3. Commit your changes (Copy to clipboardgit commit -m 'Add amazing feature')
4. Push to the branch (Copy to clipboardgit 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