# Razorpay Payments Setup (India + International)

LarShield pricing uses **Razorpay** for one-time plan purchases:

- **INR** checkout for Indian customers (UPI, cards, netbanking, wallets)
- **USD** checkout for international customers (international cards)
- A **platform fee** is added on top of the plan price at checkout

## 1. What the customer pays

| Line item | Calculation |
|---|---|
| Service price | Plan price from `subscription_tiers` |
| Platform fee | `PLATFORM_FEE_PERCENT` (default **2%**) of the service price |
| GST | `PLATFORM_FEE_GST_PERCENT` (default **18%**) of the platform fee, **INR only** |
| Total | Service + platform fee + GST |

Example (Quick Scan, INR):

```
Service price        Rs.499.00
Platform fee (2%)    Rs.  9.98
GST (18%)            Rs.  1.80
Total payable        Rs.510.78
```

USD checkouts add the 2% platform fee only (no Indian GST).

All amounts are recalculated server-side in minor units (paise/cents).
The browser never sends an amount.

## 2. Create the Razorpay account

1. Sign up at <https://dashboard.razorpay.com/signup>.
2. Complete KYC (business PAN, bank account) to move from Test to Live.
3. **Enable international payments**: Dashboard -> Account & Settings -> Payment methods -> International payments -> Request activation.
4. **Enable UPI / wallets / netbanking** under Payment methods if they are not already on.

## 3. Get the API keys

Dashboard -> Account & Settings -> API Keys -> Generate Key.

You get:

```
Key ID       rzp_test_xxxxxxxxxxxx   (or rzp_live_...)
Key Secret   xxxxxxxxxxxxxxxxxxxxxxxx
```

Store the **Key ID** and **Key Secret** only on the server (HF Secrets). The Key ID is sent to the browser as part of the order response; the Secret is never exposed.

## 4. Configure the webhook

Dashboard -> Account & Settings -> Webhooks -> Add New Webhook.

- **URL**: `https://<your-space>.hf.space/api/billing/webhook`
- **Secret**: choose a strong random string, save it as `RAZORPAY_WEBHOOK_SECRET`
- **Active events**:
  - `payment.captured`
  - `order.paid`
  - `payment.failed`

The webhook is the safety net: if the customer closes the tab after paying, the webhook still activates the plan. Fulfilment is idempotent (same payment is never credited twice).

## 5. Environment variables

Set these in **Hugging Face Space -> Settings -> Secrets** (or in `.env` locally):

```env
RAZORPAY_KEY_ID=rzp_test_xxxxxxxxxxxx
RAZORPAY_KEY_SECRET=xxxxxxxxxxxxxxxxxxxxxxxx
RAZORPAY_WEBHOOK_SECRET=whsec_your_random_secret

PLATFORM_FEE_PERCENT=2
PLATFORM_FEE_GST_PERCENT=18
USD_TO_INR_RATE=88
```

Then **Factory Rebuild** the Space.

## 6. How the flow works

```
Pricing card "Get Started"
        |
        v
POST /api/billing/quote          -> service + fee + GST + total (displayed in modal)
        |
        v
POST /api/billing/create-order   -> Razorpay order created, pending Payment row saved
        |
        v
Razorpay Checkout (UPI / card / netbanking / wallet / international card)
        |
        v
handler -> POST /api/billing/verify-payment
             - HMAC SHA256 signature check
             - amount + currency + order id confirmed with Razorpay
             - organization tier upgraded
             - +3 scan credits added
             - audit log written
        |
        v
Success modal and page reload

Fallback: Razorpay webhook (payment.captured / order.paid)
          performs the same activation if the browser never returns.
```

## 7. Test cards

Razorpay test mode:

| Method | Details |
|---|---|
| Card (success) | `4111 1111 1111 1111`, any future expiry, CVV `123` |
| Card (failure) | `5104 0600 0000 0008` |
| UPI (success) | `success@razorpay` |
| UPI (failure) | `failure@razorpay` |

Test mode does not move real money.

## 8. What gets written to the database

`payments` row:

| Column | Meaning |
|---|---|
| `amount` | Total charged (service + fee + GST), minor units |
| `base_amount` | Service price, minor units |
| `platform_fee` | Platform fee, minor units |
| `tax_amount` | GST, minor units |
| `currency` | `INR` or `USD` |
| `razorpay_order_id` | Razorpay order id |
| `razorpay_payment_id` | Razorpay payment id (unique - idempotency) |
| `status` | `created` -> `successful` / `failed` |
| `tier_id` | `quick` / `advanced` / `deep` |

On success the app also:

- sets `organizations.subscription_tier` to the purchased tier
- adds `+3` to `organization_scan_quotas` for that scan type
- writes an `audit_logs` entry

## 9. Admin controls

Super Admin -> Dashboard -> **Dynamic Billing Control** edits USD and INR prices.
The API is `PUT /api/billing/tiers/<tier_id>` and accepts:

```json
{
  "monthly_price": 499,
  "yearly_price": 4990,
  "monthly_price_inr": 49900,
  "yearly_price_inr": 499000
}
```

All values are minor units.

## 10. Troubleshooting

| Symptom | Cause / fix |
|---|---|
| `Payment gateway is not configured yet` | `RAZORPAY_KEY_ID` / `RAZORPAY_KEY_SECRET` missing in Space Secrets, or Space not rebuilt |
| `Could not start the payment` | Invalid keys, or the Razorpay account is not activated for that currency |
| International cards fail | International payments not enabled in Razorpay Dashboard |
| Payment succeeds but plan not upgraded | Webhook URL/secret wrong, or `verify-payment` never reached. Open Razorpay Dashboard -> Payments, copy `pay_...` id, then contact support; the audit log will show whether fulfilment ran |
| `Invalid payment signature` | Wrong `RAZORPAY_KEY_SECRET` for the key id used to create the order |
| Old INR price shown | Update the tier in Super Admin -> Dynamic Billing Control |