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:

---

Configuration

1. Register in medusa-config.ts

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

2. Environment Variables

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

---

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.