razorpay-integration-guardrails

31 India-specific rules for Razorpay APIs — for AI coding tools

Three rule types in one package:

• 18 guardrails — stops AI from generating wrong patterns (wrong code → support tickets)
• 8 workflow recipes — complete API + webhook sequences for common use cases (one-time payment, subscriptions, refunds, Route, UPI, NACH, payment links)
• 5 product selectors — helps AI pick the right product for the developer's use case

Covers the most common integration mistakes that create support tickets — server-side verification, UPI PENDING state, AFA flows, NACH compliance, API key security, and more.

Install in 30 seconds

Node.js / npm:

npx razorpay-integration-guardrails install

Any language (Go, Python, Ruby, PHP, etc.) — no Node.js required:

curl -fsSL https://raw.githubusercontent.com/razorpay/integration-guardrails/main/install.sh | bash

Both scripts do the exact same thing — the shell version exists so developers on non-JS stacks don't need Node.js installed just to set up guardrails. Requires curl and jq.

Auto-detects your AI tool and installs to the right location:

• Cursor → .cursor/rules/razorpay-integration-guardrails.mdc
• Claude Code → .claude/razorpay-integration-guardrails.md
• GitHub Copilot → .github/copilot-instructions.md

What it fixes

| # | Rule | What it prevents | |---|------|-----------------| | RZP-001 | Verify payments server-side via webhook | Fraudulent orders marked as paid | | RZP-002 | Create order before payment | Amount tampering, capture failures | | RZP-003 | Capture with order_id + payment_id | Double-capture, wrong payment capture | | RZP-004 | Raw body for webhook signature | Signature validation always failing | | RZP-005 | UPI AutoPay AFA for >₹15K | Silent subscription failures | | RZP-006 | NACH 24h pre-debit notification | RBI/NPCI compliance violations | | RZP-007 | Handle UPI PENDING state | False payment failures, angry users | | RZP-008 | UPI Intent on mobile, QR on desktop | Poor UPI UX on wrong device | | RZP-009 | key_secret never in frontend | API key exposure, security incidents | | RZP-010 | Test vs live key separation | Real charges in dev, silent test failures in prod | | RZP-011 | Rotate on exposure | Prolonged key compromise | | RZP-012 | Official checkout.js CDN only | Stale SDK, missed security patches | | RZP-013 | Amount in paise (×100) | ₹500 charged as ₹5 | | RZP-014 | payment.failed handler required | Users stuck with no feedback | | RZP-015 | Handle subscription.halted | Users keep access despite failed billing | | RZP-016 | interval + period, not billing_cycle_anchor | Subscription schedule errors | | RZP-017 | Check Route enablement | Runtime 400 errors in production | | RZP-018 | Transfer after payment.captured only | Transfers from uncaptured payments |

Manual install

Cursor — add to .cursor/rules/razorpay-integration-guardrails.mdc:

See skills/index.json for the full rule set

Claude Code — reference in your CLAUDE.md:

@.claude/razorpay-integration-guardrails.md

GitHub Copilot — add to .github/copilot-instructions.md:

# Razorpay
Follow the rules in razorpay-integration-guardrails when generating Razorpay integration code.

Skills catalog

This package is auto-discoverable at:

https://razorpay.com/.well-known/skills/index.json

AI tools that support skills auto-discovery will pick up Razorpay guardrails automatically when a developer works on a Razorpay integration.

Contributing

Rule validation is critical — each rule is reviewed by Razorpay senior API engineers against real support ticket data.

See CONTRIBUTING.md for the rule authoring guide.

Built by Neha Singhal · Project Synapse P5.1 · Razorpay Developer UX & AI