PayU (India)

What you need

PayU Dashboard (onboarding.payu.in) → Developer in the left menu → API Keys tab:

• merchant_key: PayU's "Key" field
• merchant_salt: the "Salt-32 bit" value (Salt v1, not v2). Kept secret; it never reaches the browser.

In your panel choose Settings → Payments → Add method → PayU and enter both.

Test environment: switch on Test Mode in the dashboard's menu bar; the Developer page then shows the test key/salt. Enter those and tick sandbox (test) mode in the panel; the form is posted to test.payu.in/_payment. Going live, enter the live key/salt and untick the box (secure.payu.in/_payment).

The return URLs (surl and furl) are attached to every payment automatically; nothing has to be configured on PayU's side. Their shape:

https://<your-panel-domain>/payments/payu/callback

Optional: in PayU Dashboard → Webhooks you can register the same URL for the "Successful Payment / Failed Payment" events as a server-to-server notification. The body has the same fields and signature as the browser return; the panel verifies both the same way and never credits one mihpayid twice.

Flow

1. The customer enters an amount and a phone number and picks PayU. (The phone is a mandatory PayU field.)
2. The panel builds a hidden form with key, txnid (our payment reference), amount, productinfo, firstname, email, phone, surl, furl and a SHA-512 hash computed on the server; the customer's browser POSTs it to PayU and PayU's hosted payment page opens. Card/UPI details never touch your server.
3. When the payment finishes, PayU POSTs the customer's browser to surl/furl (both the same callback) with status, mihpayid, txnid, amount and a reverse hash.
4. The panel recomputes the reverse hash with its own salt (salt|status||||||udf5…udf1|email|firstname|productinfo|amount|txnid|key, prefixed with additional_charges| when PayU added a convenience fee). If the hash does not match, the key is not ours, or txnid is not our payment, the return is discarded, nothing is credited.
5. With a valid hash and status = success the balance is credited and the customer lands on "Add funds" with a success banner. On failure the payment is recorded as failed with PayU's error_Message in its memo.

A second return for the same mihpayid and status is ignored; balance is never credited twice.

Statuses

• success → completed, balance credited.
• pending → shows as pending in the panel; nothing is credited. If PayU later reports success (webhook or a late browser return) it is credited then; otherwise complete it by hand from Admin → Payments. When unmappedstatus is usercancelled/bounced/dropped it counts as failed, not pending.
• failure → failed.

Currencies

This driver works in INR only; a method in another currency cannot start a payment. PayU's multi-currency feature (transactionCurrency) needs a separate agreement and is not part of this driver.

Limits

PayU accepts 25 characters for txnid, 20 for firstname on the test environment and 100 for productinfo. The panel reduces the name and product text to ASCII and trims them; if a reference exceeds 25 characters the payment fails before it starts.

Common problems

• "Hash mismatch" / PayU page does not open: key and salt belong to different environments (test/live), or Salt v2 was entered. Use Salt v1 and make sure the sandbox tick matches the environment.
• "invalid signature" on return: the salt in the panel is not the one PayU signed with (wrong value, Salt v2, or test/live mixed). The payment stays "waiting" and nothing is credited; fix the salt and ask the customer to retry, or complete it by hand once you see it in the PayU Dashboard.
• Payment succeeded but no balance: the result arrives through the customer's browser; if they closed the page the panel never saw it. Register the webhook in the PayU Dashboard (URL above) so PayU reports the result server-to-server as well; until then, complete the payment from Admin → Payments after checking the mihpayid in the PayU Dashboard.
• It asks for a phone: PayU requires the phone field; a customer cannot pay with this method without entering a number.