> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fluxrate.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Razorpay

> Accept UPI, cards, net banking, and wallets for Indian customers. Generate payment links automatically on every finalized invoice.

Razorpay is Fluxrate's native payment gateway for Indian businesses. When connected, Fluxrate creates a **Razorpay Payment Link** for every finalized invoice. Customers receive a link to pay via UPI, debit/credit cards, net banking, or popular wallets all in INR.

## Prerequisites

* A [Razorpay account](https://dashboard.razorpay.com/signup) (live or test mode)
* A Razorpay **Key ID** (`rzp_live_...` or `rzp_test_...`)
* A Razorpay **Key Secret**
* A Razorpay **Webhook Secret** (set when creating the webhook endpoint)

## Setup

### Step 1 - Get your Razorpay API Keys

1. Go to [Razorpay Dashboard > Settings > API Keys](https://dashboard.razorpay.com/app/keys).
2. Click **Generate Key** (or use an existing key pair).
3. Copy the **Key ID** (`rzp_live_...`) and **Key Secret**.

<Warning>
  The Key Secret is shown only once at generation time. If lost, you must generate a new key pair. Fluxrate stores both values encrypted.
</Warning>

### Step 2 - Connect in Fluxrate

1. Open **Dashboard > Integrations**.
2. Click **Connect** next to Razorpay.
3. Fill in the form:

| Field               | Value                                                              |
| ------------------- | ------------------------------------------------------------------ |
| **Connection Name** | A friendly label, e.g. `Production Razorpay`                       |
| **Key ID**          | Your Razorpay Key ID (`rzp_live_...`)                              |
| **Key Secret**      | Your Razorpay Key Secret                                           |
| **Webhook Secret**  | Leave blank for now — you'll add this after setting up the webhook |

4. Click **Create Connection**. Fluxrate generates a unique **Webhook URL** for your integration.

### Step 3 - Configure the Webhook in Razorpay

1. Go to [Razorpay Dashboard → Account Settings → Webhooks](https://dashboard.razorpay.com/app/webhooks).
2. Click **Add New Webhook**.
3. Paste the **Webhook URL** from Fluxrate:
   ```text theme={null}
   https://api.fluxrate.co/api/v1/webhooks/razorpay/tenant_{your_org_id}/{env_id}
   ```
4. Set a **Secret** this is your webhook secret. Copy it now.
5. Under **Active Events**, enable:
   * `payment.captured`
   * `payment.failed`
   * `order.paid`
   * `refund.created`
   * `payment_link.paid`
6. Click **Create Webhook**.

### Step 4 - Save the Webhook Secret

1. Back in Fluxrate, go to **Dashboard → Integrations → Manage** (Razorpay).
2. Paste the webhook secret you set in Razorpay.
3. Click **Save Changes**.

Your Razorpay integration is now fully configured.

## How Payments Work

```mermaid theme={null}
sequenceDiagram
    participant Fluxrate
    participant Razorpay
    participant Customer

    Fluxrate->>Razorpay: Create Payment Link (invoice_id in notes)
    Razorpay-->>Fluxrate: payment_link.short_url
    Fluxrate->>Customer: Invoice email with payment link
    Customer->>Razorpay: Pays via UPI / card / netbanking
    Razorpay->>Fluxrate: POST /webhooks/razorpay/... (payment.captured)
    Fluxrate->>Fluxrate: Verify X-Razorpay-Signature header (HMAC-SHA256)
    Fluxrate->>Fluxrate: Mark invoice as PAID
```

Fluxrate passes `invoice_id` and `customer_id` in the Razorpay Payment Link **notes** field. When Razorpay fires a webhook on successful payment, Fluxrate reads these values to identify and update the invoice.

## Webhook Payload Handling

Razorpay webhook payloads use a nested `payload` structure. Fluxrate reads from multiple possible locations:

| Field                 | Source in payload                                                                           | Purpose                            |
| --------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------- |
| `invoice_id`          | `payload.payment.entity.notes.invoice_id` or `payload.payment_link.entity.notes.invoice_id` | Links event to a Fluxrate invoice  |
| `customer_id`         | `payload.payment.entity.notes.customer_id`                                                  | Links event to a Fluxrate customer |
| `amount`              | `payload.payment.entity.amount` ÷ 100                                                       | Amount in INR (paise → rupees)     |
| `currency`            | `payload.payment.entity.currency` (uppercased)                                              | Currency code, e.g. `INR`          |
| `provider_payment_id` | `payload.payment.entity.id`                                                                 | Razorpay payment ID (`pay_...`)    |

Events that trigger invoice payment in Fluxrate:

* `payment.captured`
* `order.paid`
* `payment_link.paid`

## Signature Verification

Fluxrate verifies every Razorpay webhook using **HMAC-SHA256**:

```python theme={null}
expected = hmac.new(webhook_secret.encode(), raw_body, hashlib.sha256).hexdigest()
assert hmac.compare_digest(expected, razorpay_signature)
```

The signature is read from the `X-Razorpay-Signature` request header. Requests that fail verification are rejected with `400 Bad Request`.

## Managing the Integration

| Action                | How                                                     |
| --------------------- | ------------------------------------------------------- |
| Rotate API keys       | Manage → enter new Key ID and Key Secret → Save Changes |
| Rotate webhook secret | Manage → enter new webhook secret → Save Changes        |
| Temporarily disable   | Manage → toggle `is_active` off → Save Changes          |
| Remove entirely       | Dashboard → Integrations → ··· → Disconnect             |

## Troubleshooting

<AccordionGroup>
  <Accordion title="Webhook signature verification failed">
    Fluxrate uses `X-Razorpay-Signature` and your stored webhook secret to verify requests via HMAC-SHA256. Ensure the webhook secret in Fluxrate exactly matches the secret you set in the Razorpay Dashboard. Regenerating the secret in Razorpay requires updating it in Fluxrate too.
  </Accordion>

  <Accordion title="Invoice not marked as paid after payment">
    Confirm that the Payment Link was created with `notes.invoice_id` populated. Check **Dashboard > Integrations > Webhook Events** in Fluxrate to verify the event was received and that `event_type` is `payment.captured` or `payment_link.paid`.
  </Accordion>

  <Accordion title="Amount appears incorrect on the invoice">
    Razorpay amounts are in the **smallest currency unit** (paise for INR). Fluxrate divides by 100 to convert to rupees. If the amounts differ, verify that the Payment Link was created with the correct invoice total.
  </Accordion>

  <Accordion title="Only Indian Rupee (INR) supported?">
    Razorpay primarily processes INR. Multi-currency support on Razorpay is limited to specific international payment methods. If your customers are outside India, consider using the Stripe integration instead.
  </Accordion>
</AccordionGroup>