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

# Razorpay Checkout Setup

> Configure Razorpay to work with Tirdad Checkout Sessions, including the exact webhook events required.

Before creating your first Checkout Session with Razorpay, you need a connected Razorpay account and the correct webhook events enabled in your Razorpay dashboard.

## Step 1: Connect Razorpay

Follow the [Razorpay Connection Setup guide](https://docs.tirdad.ai/integrations/razorpay/connection-setup.md) to add your API keys and webhook secret. Come back here once the connection is active.

## Step 2: Enable the required webhook events

Go to your Razorpay Dashboard: **Settings → Webhooks → \[your Tirdad endpoint]** and enable these events:

| Event | Required for |
| - | - |
| `payment.captured` | Payment reconciliation |
| `payment.failed` | Payment failure handling |
| `payment_link.paid` | Activating the subscription when payment completes |
| `payment_link.cancelled` | Cleaning up when a customer cancels the payment link |
| `payment_link.expired` | Cleaning up when the payment link expires |
| `token.confirmed` | Confirming a mandate registration (autopay only) |

> [!WARNING]
>
> If `payment_link.paid` is not enabled, Tirdad will never receive payment confirmation and the subscription will stay inactive. Verify these events are enabled before testing.

> [!NOTE]
>
> `token.confirmed` is only needed if you use [Autopay & Mandates](https://docs.tirdad.ai/docs/checkout/autopay-mandates.md). Without it, mandate registrations never complete and the session stays `pending`. It is harmless to enable for payment-link-only setups.

### Webhook URL

Your Tirdad webhook URL follows this format:

```
https://api.tirdad.ai/v1/webhooks/razorpay/<TENANT_ID>/<ENVIRONMENT_ID>
```

Find your `TENANT_ID` and `ENVIRONMENT_ID` in **Settings → General**.

## Step 3: Verify the webhook secret

Tirdad validates the signature on every inbound Razorpay webhook. If the secret doesn't match, events are rejected silently.

Go to **Settings → Connections → Razorpay** in Tirdad and confirm the webhook secret matches what's shown in your Razorpay dashboard for that endpoint.

## Step 4: Test the flow

Use Razorpay test mode before going live.

**Test cards:**

| Network | Card number | CVV | Expiry |
| - | - | - | - |
| Visa | `4386 2894 0766 0153` | Any 3 digits | Any future date |
| Mastercard | `2305 3242 5784 8228` | Any 3 digits | Any future date |

**Test UPI:**

| UPI ID | Simulates |
| - | - |
| `success@razorpay` | Successful payment |
| `failure@razorpay` | Failed payment |

After a test payment, confirm:

* Session status is `completed`
* Subscription status is `active`
* Invoice status is `finalized`
* Your server received the `checkout.session.completed` event

If the session stays `pending` after payment, check the Razorpay webhook delivery log and confirm all five events are enabled on the correct endpoint URL.

## Troubleshooting

| Symptom | Likely cause | Fix |
| - | - | - |
| Session stays `pending` after payment | `payment_link.paid` not enabled | Add it in Razorpay Dashboard → Webhooks |
| Session fails immediately on creation | Razorpay connection inactive | Check status in Settings → Connections |
| Webhook secret mismatch error | Secret out of sync | Re-copy the secret from Razorpay into Tirdad |
| Subscription stays inactive after payment | Wrong tenant or environment ID in webhook URL | Verify the URL in Razorpay matches the format above |

> [card] [Razorpay Connection Setup](https://docs.tirdad.ai/integrations/razorpay/connection-setup.md)
>
> Connect your Razorpay account to Tirdad.

> [card] [Checkout Sessions API](https://docs.tirdad.ai/docs/checkout/checkout-sessions.md)
>
> Create your first session once Razorpay is configured.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.