Razorpay

You are integrating Razorpay as the payment gateway for a [Django / Next.js / Node / etc.] application. Razorpay is India-native — the merchant account must be registered in India, Malaysia (Curlec), or Singapore (Curlec), and default settlement is in INR/MYR/SGD.

## Setup
1. Install the SDK:
   - Python: `pip install razorpay`
   - Node: `npm install razorpay`
   - PHP: `composer require razorpay/razorpay`
2. Store credentials in environment variables — never hardcode:
   - `RAZORPAY_KEY_ID` (publishable, starts with `rzp_test_` or `rzp_live_`)
   - `RAZORPAY_KEY_SECRET` (private — server-only)
   - `RAZORPAY_WEBHOOK_SECRET` (set separately in Dashboard → Settings → Webhooks)
3. Validate on startup that all three exist and that test vs live keys match the current environment.

## Recommended Integration: Orders API + Checkout
Always create an Order server-side first — never trust the client to set the amount. Then open Razorpay Checkout with the order_id.

```python
import razorpay
client = razorpay.Client(auth=(KEY_ID, KEY_SECRET))

order = client.order.create({
    'amount': 50000,           # in paise — ₹500 = 50000
    'currency': 'INR',
    'receipt': f'order_{internal_id}',
    'notes': {'internal_id': str(internal_id)}
})
# Pass order['id'] to the client; the client opens Checkout with it.
```

On the client, open Checkout with the returned order_id and handler that POSTs the razorpay_payment_id, razorpay_order_id, and razorpay_signature back to your server for verification.

## Signature Verification (Critical)
After payment, the client sends three fields back. Verify them server-side before marking the order paid:

```python
try:
    client.utility.verify_payment_signature({
        'razorpay_order_id': order_id,
        'razorpay_payment_id': payment_id,
        'razorpay_signature': signature
    })
    # Mark order paid
except razorpay.errors.SignatureVerificationError:
    # Reject — do not fulfill
    return HttpResponse(status=400)
```

## Webhook Handling
Never rely solely on the client-side redirect. Subscribe to webhooks for authoritative state.

1. In Dashboard → Settings → Webhooks, subscribe to at minimum: `payment.captured`, `payment.failed`, `order.paid`, `refund.processed`, `payment.dispute.created`, and (if using subscriptions) `subscription.charged`, `subscription.activated`, `subscription.halted`.
2. Verify signature against the **raw request body** — do NOT parse-then-reserialize (float precision will break HMAC):

```python
import hmac, hashlib

def razorpay_webhook(request):
    raw_body = request.body                                # bytes — do not decode/reparse
    received_sig = request.META.get('HTTP_X_RAZORPAY_SIGNATURE', '')
    expected = hmac.new(
        settings.RAZORPAY_WEBHOOK_SECRET.encode(),
        raw_body,
        hashlib.sha256
    ).hexdigest()
    if not hmac.compare_digest(expected, received_sig):
        return HttpResponse(status=400)
    event = json.loads(raw_body)
    # Idempotency: check event['id'] against a processed-events table before fulfilling.
    return HttpResponse(status=200)
```

3. Respond 200 within 5 seconds; process fulfillment asynchronously.

## Security Best Practices
- Use Razorpay Checkout (hosted) so raw card data never touches your server — keeps you at SAQ-A PCI scope.
- Per RBI Card-on-File rules, never store raw PAN — use Razorpay network tokens (`token_id` from customer object) for any recurring/retry.
- Always use HTTPS; Razorpay rejects HTTP endpoints.
- For subscriptions, prefer UPI AutoPay over card e-mandates for higher success rates and RBI-compliant 24-hour pre-debit notifications.
- Use idempotency keys on Order creation to prevent duplicate orders on client retries.

## Testing
- Test cards: `4111 1111 1111 1111` (success), `5104 0600 0000 0008` (success, Mastercard), CVV any, expiry any future. OTP: `1111` or `123456`.
- Test UPI: `success@razorpay` (captured), `failure@razorpay` (failed).
- Test netbanking: pick any bank → select 'success' or 'failure' on the mock bank page.
- Always test: successful payment, failed payment, 3DS challenge, refund, dispute creation webhook, and a settled-then-refunded flow.

## Common Gotchas
- Amounts are in **paise** (1 INR = 100 paise). A ₹500 charge is `amount: 50000`.
- GST (18%) applies to the platform fee, NOT the transaction amount. Invoice accordingly.
- International card settlements are T+7, not T+2 — plan cash flow.
- Webhook signature verification is against raw bytes; never `json.parse → json.stringify` before checking.
- Subscriptions charge model: you create a Plan, then a Subscription against it; the first charge is authorized via Checkout and subsequent charges are autopaid. State transitions are webhook-driven.
- Refunds do not return the gateway fee — price this into your refund policy.