Payu

@sam-ael/medusa-plugin-payu

A production-focused PayU India payment provider plugin for Medusa v2 featuring redirect checkout flow, callback handling, and fraud-aware verification.

Medusa Website | Medusa Repository

Features

• Redirect-Based Checkout: Integrates seamlessly into Medusa payment sessions to route customers to the official PayU checkout portal.
• Secure Hash Verification: Automated generation of checkout hashes and reverse-hash verification for response validation.
• Robust Webhook Integration: Processes real-time transaction updates from PayU to handle capture and payment events.
• Timing-Attack Protection: Employs constant-time string comparison for webhook payload hash validation.
• Replay Protection: Prevents duplicate transaction/webhook submissions via an in-memory key deduplication store.
• Discrepancy Guards: Compares paid amounts against expected payment session amounts to flag underpayment attempts.

Prerequisites

• Node.js v18 or greater
• A Medusa v2 backend
• A PayU India merchant account with a Merchant Key and Merchant Salt

Installation

Run the following command to install the plugin in your Medusa project:

yarn add @sam-ael/medusa-plugin-payu

Configuration

1. Register in medusa-config.ts

Add the PayU provider under the payment module options in medusa-config.ts:

1const modules = [
2  // ... other modules
3  {
4    resolve: "@medusajs/medusa/payment",
5    options: {
6      providers: [
7        {
8          resolve: "@sam-ael/medusa-plugin-payu/providers/payu",
9          id: "payu",
10          options: {
11            merchantKey: process.env.PAYU_MERCHANT_KEY,
12            merchantSalt: process.env.PAYU_MERCHANT_SALT,
13            environment: process.env.PAYU_ENVIRONMENT || "test", // "test" or "production"
14          },
15        },
16      ],
17    },
18  },
19]

2. Environment Variables

Define the required credentials and options in your .env file:

1PAYU_MERCHANT_KEY=your_merchant_key
2PAYU_MERCHANT_SALT=your_merchant_salt
3PAYU_ENVIRONMENT=test
4
5STOREFRONT_URL=http://localhost:8000
6PAYU_REDIRECT_URL=/order/confirmed
7PAYU_REDIRECT_FAILURE_URL=/checkout
8PAYU_API_TIMEOUT_MS=30000

Webhooks

This plugin exposes an inbound webhook endpoint to handle asynchronous payment updates sent by PayU.

Webhook Validation

1. Hash Verification: Generates a SHA-512 comparison hash using your PAYU_MERCHANT_SALT and incoming payload variables. It uses crypto.timingSafeEqual to check validity.
2. Amount Discrepancy Check: Validates that the amount reported in the webhook matches the expected transaction amount (stored in udf4). If underpaid, it sets the payment status to requires_more.
3. Replay Guard: Dedupes requests matching the key pattern ${txnid}:${status}:${mihpayid}:${amount} within a 10-minute window.

Test the Plugin

1. Set your backend to use test mode (PAYU_ENVIRONMENT=test).
2. Implement a checkout page on your storefront that resolves a payment session using the payu provider ID.
3. Initiate checkout; you should be redirected to the PayU Sandbox page.
4. Complete the test transaction using the test card details provided on PayU's developer documentation.
5. PayU will redirect the client back to your storefront, and call the /hooks/payment/payu_payu webhook to complete/authorize the order payment in Medusa.