PayU

You are integrating PayU India as the payment gateway for a [Django / Next.js / Node / etc.] application. PayU is India-focused — the merchant account must be a registered Indian entity with PAN, GST (where applicable), and an Indian current account. Settlement is in INR. PayU also operates in Turkey (Iyzico) and Southeast Asia (Red Dot Payment), but the SDKs and APIs below are PayU India.

## Setup
1. Install the official server-side SDK — never roll your own hash generator:
   - Node: `npm install payu-sdk-node`
   - Python: `pip install payu-sdk-python`
   - PHP: `composer require payu/payu-sdk-php`
2. Store credentials in environment variables — never in client code:
   - `PAYU_KEY` (merchant key — the publishable identifier)
   - `PAYU_SALT` (private — server-only, NEVER ship to the browser)
   - Note your environment: `https://test.payu.in` (sandbox) vs `https://secure.payu.in` (live).
3. Validate on startup that both env vars exist and that test vs live keys match the current environment.

## Recommended Integration: PayU Hosted Checkout (lowest PCI scope)
PayU Hosted Checkout renders the payment page on PayU's domain — your server never touches card data, keeping you at SAQ-A PCI scope.

```python
import hashlib

txnid = f'order_{internal_id}'
fields = {
    'key': PAYU_KEY,
    'txnid': txnid,
    'amount': '500.00',                # rupees, two decimals — NOT paise
    'productinfo': 'Plan-Pro',          # no pipe characters
    'firstname': customer_first_name,
    'email': customer_email,
    'udf1': '', 'udf2': '', 'udf3': '', 'udf4': '', 'udf5': ''
}
hash_string = '|'.join([
    fields['key'], fields['txnid'], fields['amount'], fields['productinfo'],
    fields['firstname'], fields['email'],
    fields['udf1'], fields['udf2'], fields['udf3'], fields['udf4'], fields['udf5'],
    '', '', '', '', '',                 # five empty udf6–udf10 placeholders
    PAYU_SALT
])
fields['hash'] = hashlib.sha512(hash_string.encode()).hexdigest()
# POST `fields` as form data to https://secure.payu.in/_payment
```

The customer is redirected to PayU; on completion they land back on your `surl` (success URL) or `furl` (failure URL). Both URLs receive a POST with the response hash.

## Response Hash Verification (Critical)
Verify EVERY response — both the browser-redirect POST AND the S2S webhook — using the reverse-order hash. Never mark an order paid without a passing hash check.

```python
def verify_payu_response(post_data):
    expected = '|'.join([
        PAYU_SALT, post_data['status'],
        '', '', '', '', '', '',         # six empty placeholders (udf10 down through udf6)
        post_data['udf5'], post_data['udf4'], post_data['udf3'],
        post_data['udf2'], post_data['udf1'],
        post_data['email'], post_data['firstname'], post_data['productinfo'],
        post_data['amount'], post_data['txnid'], post_data['key']
    ])
    expected_hash = hashlib.sha512(expected.encode()).hexdigest()
    return hmac.compare_digest(expected_hash, post_data['hash'])
```

## S2S Webhook (Source of Truth)
Never rely on the browser redirect alone — networks drop, customers close tabs, mobile back-buttons fire. Configure an S2S webhook URL in Dashboard → Settings → Webhooks and treat it as authoritative.

1. Configure an HTTPS webhook URL (PayU rejects HTTP).
2. Subscribe to: payment success, payment failure, refund processed, chargeback created.
3. The webhook POST body uses the same parameters as the response redirect, including a `hash` field — verify it with the same reverse-order SHA-512.
4. Idempotency: dedupe on `txnid` against a processed-events table before fulfilling.
5. Respond 200 within 5 seconds; do fulfillment work asynchronously.

## Security Best Practices
- Use PayU Hosted Checkout (not Merchant Hosted Custom) unless you have SAQ-D PCI compliance — Hosted keeps you at SAQ-A.
- Per RBI Card-on-File rules, never store raw PAN — PayU returns network tokens for recurring/refunds; use those.
- The SALT belongs server-only; never expose it in client JS, mobile bundles, public repos, or client-side hash computation.
- Use HTTPS for both `surl`/`furl` and webhook URLs; PayU rejects HTTP endpoints in production.
- Use a unique `txnid` per attempt — never reuse on retry; PayU rejects duplicates and the response hash will mismatch.
- Send amount in rupees with two decimals (`'500.00'`) — NOT paise. (This differs from Razorpay, which uses paise.)

## Subscriptions / Recurring (Standing Instructions)
For subscription billing, use the Standing Instructions API model (Plans + Subscriptions) with CC/DC, UPI AutoPay, or e-NACH mandates:

1. Create a Plan via the Plans API (amount, billing cycle, free trial).
2. Create a Subscription against the Plan; the first charge is authorized via a Hosted Checkout flow with the `si` (standing instruction) flag.
3. Subsequent charges are auto-debited per the mandate; PayU posts a webhook for each.
4. Mirror Plan + Subscription state transitions in your DB driven by webhooks — don't query PayU on every render.

## Testing
- Sandbox base URL: `https://test.payu.in/_payment`
- Test cards (sandbox): `5123 4567 8901 2346` (Mastercard success), `4012 0010 3714 1112` (Visa success). CVV `123`, expiry any future. OTP `123456`.
- Test UPI VPA: `success@payu` (captured), `failure@payu` (failed).
- Test netbanking: pick any bank → choose 'success' or 'failure' on the mock bank page.
- Always test: successful payment, failed payment, 3DS challenge, S2S webhook delivery, refund, dispute creation webhook, and a settled-then-refunded flow.

## Common Gotchas
- **Amounts are in rupees, NOT paise** (unlike Razorpay). A ₹500 charge is `amount: '500.00'`.
- **Hash mismatch is the #1 integration failure** — use the official SDK, never compute the hash in the browser, and watch the empty udf6–udf10 pipe placeholders.
- **The S2S webhook is the source of truth** — the browser redirect can drop. Always implement and verify the webhook before going live.
- **GST (18%) applies to the platform fee, NOT the transaction amount** — invoice and reconcile accordingly.
- **International card and EMI processing require separate setup + AMC fees** that are not on the public pricing page — get them in writing before signing.
- **Documentation split**: bookmark docs.payu.in as the only authoritative source — older content on devguide.payu.in and developer.payumoney.com may show different parameter names.