# Razorpay





[Razorpay](https://razorpay.com) is a payment gateway for India. Connect your Razorpay account once, and the agent can add one-time payments, subscriptions and paywalls to any app in your workspace. Payments go straight to your Razorpay account.

<Callout type="info">
  Razorpay is available for India only, and payments are in INR.
</Callout>

## Connecting Razorpay [#connecting-razorpay]

<Steps>
  <Step>
    Open **Settings → Integrations** and find **Razorpay**.
  </Step>

  <Step>
    Click **Connect**, log in to Razorpay and approve Ideavo's access.
  </Step>

  <Step>
    Return to Ideavo. The row shows your account ID and **(test mode)**.
  </Step>
</Steps>

You can also connect from the chat: when the agent needs Razorpay and it isn't connected yet, it shows a **Connect** button.

Only the workspace owner can connect, renew or disconnect Razorpay. The connection is shared by every project in the workspace.

<Callout type="warn">
  Ideavo always connects in **test mode**, where no real money moves. Ideavo
  never requests or stores live credentials. To accept real payments, you set
  your own live keys on your host, as described in [Going Live](#going-live).
</Callout>

## Renewing Access [#renewing-access]

Ideavo's access to your Razorpay account lasts about 90 days. In the last 10 days, **Settings → Integrations** shows the expiry date and a **Renew now** link.

<DocImage src="features/integrations/razorpay-renewal" alt="Settings → Integrations showing Razorpay's expiry date and the Renew now link" width="1792" height="1048" />

<Steps>
  <Step>
    Click **Renew now**. Ideavo gets fresh access without you logging in again.
  </Step>

  <Step>
    Ask the agent to update the Razorpay access token in each app that uses
    it.
  </Step>

  <Step>
    If a deployed app still runs on test credentials, redeploy it so the new
    token reaches your host.
  </Step>
</Steps>

If access has been revoked from your Razorpay Dashboard, renewing disconnects Razorpay, and you connect it again.

## Adding Payments to Your App [#adding-payments-to-your-app]

Ask in the chat, for example "add a ₹499 Pro plan". Here's what happens:

<Steps>
  <Step>
    **The agent checks your app.** Payments need a server, a database and
    sign-in. If any are missing, it tells you what to add first.
  </Step>

  <Step>
    **It asks a few questions,** such as what you sell and for how much,
    one-time or subscription, and what paid users get.
  </Step>

  <Step>
    **It builds the payment flow** and writes the test credentials to your
    project's `.env`.
  </Step>

  <Step>
    **You test it** with a test payment, then register the webhook.
  </Step>
</Steps>

Your app ends up with:

| Part              | What it does                                                                |
| ----------------- | --------------------------------------------------------------------------- |
| **Checkout**      | Opens Razorpay's payment window from your Buy button.                       |
| **Payment check** | Your server confirms every payment with Razorpay before unlocking anything. |
| **Access checks** | Paid pages and APIs stay locked for users who haven't paid.                 |
| **Plan page**     | Shows the plans, the user's current plan and their payment history.         |
| **Webhook**       | Receives payment events from Razorpay, covered [below](#webhooks).          |

Prices are set on your server, not in the browser, so a tampered amount or a faked payment is rejected.

## Testing Payments [#testing-payments]

Test mode works like the real thing, but no money moves. Every test payment shows up in the Razorpay Dashboard under **Payments**, with **Test Mode** switched on.

<Cards>
  <Card title="<span className=&#x22;flex items-center gap-1&#x22;>Test cards <ArrowUpRight className=&#x22;size-3.5&#x22; /></span>" icon="<CreditCard />" href="https://razorpay.com/docs/payments/payments/test-card-details/" description="Card numbers for successful payments, declines and other errors." />

  <Card title="<span className=&#x22;flex items-center gap-1&#x22;>Test UPI IDs <ArrowUpRight className=&#x22;size-3.5&#x22; /></span>" icon="<Smartphone />" href="https://razorpay.com/docs/payments/payments/test-upi-details/" description="UPI IDs that always succeed or always fail." />
</Cards>

<Tabs items="[&#x22;UPI&#x22;, &#x22;Card&#x22;]">
  <Tab value="UPI">
    Choose UPI at checkout and enter `success@razorpay` for a successful
    payment, or `failure@razorpay` for a failed one.
  </Tab>

  <Tab value="Card">
    Enter `4100 2800 0000 1007` with any future expiry date and any CVV. On the
    mock bank page, enter an OTP of 4 to 10 digits to succeed, or fewer than 4
    to fail.
  </Tab>
</Tabs>

What to check:

* A successful payment unlocks what the user paid for.
* A failed payment leaves it locked, and the user can try again.
* Closing the payment window returns to the Buy button.
* Paid pages and their APIs stay locked for users who haven't paid.

## Webhooks [#webhooks]

A webhook is how Razorpay tells your app about a payment directly, server to server. Your app stays correct even if the buyer closes the tab before the payment is confirmed, and subscription renewals are recorded without the buyer coming back.

The agent always builds the webhook endpoint in your app. You connect it in the Razorpay Dashboard, because Ideavo can't do that for you.

<Callout type="warn" title="Webhooks live in two places">
  Razorpay uses one page to **create** webhooks and a different page to **see
  the events** they received. Creating a webhook never shows its events.

  | To                         | Open                                                                                                     |
  | -------------------------- | -------------------------------------------------------------------------------------------------------- |
  | Create or edit a webhook   | [Account & Settings → Webhooks](https://dashboard.razorpay.com/app/website-app-settings/webhooks)        |
  | See the events it received | [Developers → Webhooks](https://dashboard.razorpay.com/app/developers/webhooks), then select the webhook |
</Callout>

### Create the Webhook [#create-the-webhook]

<Steps>
  <Step>
    Open [Add New Webhook](https://dashboard.razorpay.com/app/website-app-settings/webhooks?action=add-new-webhook)
    and switch to **Test Mode**. When asked for an OTP in test mode, enter
    `754081`.
  </Step>

  <Step>
    Enter a public HTTPS URL: your deployed or preview URL plus the handler
    path the agent gave you, for example `/api/webhooks/razorpay`. Razorpay
    rejects `localhost`.
  </Step>

  <Step>
    Select only the events the agent listed. If your app has subscriptions,
    include the subscription events.
  </Step>

  <Step>
    Choose a secret, and set the same value as `RAZORPAY_WEBHOOK_SECRET` in the
    [Secrets](/docs/features/secrets) tab and on your host.
  </Step>
</Steps>

### See the Events [#see-the-events]

<Steps>
  <Step>
    Open [Developers → Webhooks](https://dashboard.razorpay.com/app/developers/webhooks),
    in the same mode as your payment.
  </Step>

  <Step>
    Click your webhook to see each event Razorpay sent and your app's response.
  </Step>
</Steps>

The list is empty until a payment happens after the webhook was created. Razorpay never sends events from before that.

### Checklist [#checklist]

* **The webhook exists.** It's listed under Account & Settings → Webhooks, in the right mode (Test or Live), and enabled.
* **The secrets match.** The secret in the Dashboard and `RAZORPAY_WEBHOOK_SECRET` in your app are exactly the same. If they differ, every event is rejected with a 400.
* **Only the events your app handles are enabled.** Extra events are just noise.
* **Subscription events are enabled** if your app sells subscriptions, or renewals and cancellations never reach it.
* **The signature is verified.** The endpoint checks every event's signature before accepting it. Never remove that check, or anyone could fake a payment.

### How Events Are Handled [#how-events-are-handled]

<Cards className="grid-cols-1 sm:grid-cols-3">
  <Card title="Verified" icon="<ShieldCheck />" description="Every event's signature is checked with your webhook secret. Anything that fails is rejected." />

  <Card title="Idempotent" icon="<Webhook />" description="Razorpay can send an event more than once or out of order. Repeats change nothing, and statuses only move forward." />

  <Card title="Scoped" icon="<IndianRupee />" description="Only events for payments your app created are acted on. Everything else is acknowledged and ignored." />
</Cards>

The endpoint answers within 5 seconds. If it fails, Razorpay retries for 24 hours, then disables the webhook and emails you.

## Security [#security]

* `RAZORPAY_ACCESS_TOKEN` and `RAZORPAY_KEY_SECRET` stay on the server. Only the key ID reaches the browser.
* Never paste Razorpay credentials into the chat.
* Each payment is confirmed by fetching it from Razorpay, never by trusting the browser.

## Going Live [#going-live]

Live payments use your own API keys, which you generate and set on your host. The agent never handles them, and the same code works with test and live credentials.

### Get Your Live Keys [#get-your-live-keys]

<Steps>
  <Step>
    Complete Razorpay's [account activation (KYC)](https://razorpay.com/docs/payments/set-up/),
    so live payments are enabled. Check the
    [documents your business type needs](https://razorpay.com/docs/payments/business-types-kyc-documents/)
    first.
  </Step>

  <Step>
    Switch the Dashboard to **Live Mode**: open your profile menu in the top
    right and choose **Enable Live Mode**, or turn off the **Test** toggle at
    the top centre.
  </Step>

  <Step>
    Open **Account & Settings → API Keys → Generate Key**. Copy the secret
    right away: it's shown only once. See Razorpay's
    [API keys guide](https://razorpay.com/docs/payments/dashboard/account-settings/api-keys/).
  </Step>
</Steps>

<DocImage src="features/integrations/razorpay-mode-toggle" alt="Razorpay Dashboard with the Test toggle at the top and Enable Live Mode highlighted in the profile menu" width="1600" height="496" light="false" />

### Set Up Live Mode [#set-up-live-mode]

Test and live are separate in Razorpay, so repeat these in **Live Mode**:

* **Webhook:** in Live Mode, add a webhook the same way, with your production URL, the same events and a new secret. Live Mode asks for a real OTP instead of `754081`.
* **Subscription plans:** if you sell subscriptions, create the same plans. Live plan IDs differ from test ones.

### Update Your Host [#update-your-host]

Set these on Vercel or Railway, then redeploy there. The public key ID is built into the app, so it needs a new build.

| Variable                                                | Live value                           |
| ------------------------------------------------------- | ------------------------------------ |
| `RAZORPAY_KEY_ID`                                       | Your live key ID (`rzp_live_…`)      |
| `NEXT_PUBLIC_RAZORPAY_KEY_ID` or `VITE_RAZORPAY_KEY_ID` | The same live key ID                 |
| `RAZORPAY_KEY_SECRET`                                   | Your live key secret (new)           |
| `RAZORPAY_WEBHOOK_SECRET`                               | The live webhook's secret            |
| `RAZORPAY_PLAN_ID_…`                                    | The live plan IDs, for subscriptions |
| `RAZORPAY_ACCESS_TOKEN`, `RAZORPAY_ACCOUNT_ID`          | Delete both                          |

<Callout type="error">
  Every deploy from Ideavo sends your test credentials again and replaces the
  live ones on your host. A mix of test and live values makes payments fail.
  Set the Razorpay variables again after every deploy from Ideavo. See
  [Production Environment](/docs/features/production-environment).
</Callout>

### FAQ [#faq]

<Accordions>
  <Accordion title="Can I use Stripe or another provider?">
    Yes. Ask the agent for the provider you want. It follows that provider's
    official documentation, and you add its credentials in the Secrets tab.
    Razorpay is the one Ideavo connects natively.
  </Accordion>

  <Accordion title="Why does Ideavo only connect in test mode?">
    So you can build and test without moving real money, and so Ideavo never
    holds credentials that can charge your customers. Live keys stay with you.
  </Accordion>

  <Accordion title="What happens if Razorpay access expires?">
    Apps using the test credentials stop working until you renew in Settings
    and refresh the credentials. Live keys don't expire.
  </Accordion>

  <Accordion title="What happens when I disconnect Razorpay?">
    Ideavo revokes its access to your account. Apps using the test credentials
    stop working. Live keys on your host are unaffected.
  </Accordion>

  <Accordion title="Why isn't my webhook receiving events?">
    Check that the webhook is in the same mode as the payment (Test or Live),
    that its URL is public and current, and that the events are selected.
    Events from before the webhook was created are never sent.
  </Accordion>
</Accordions>
