Razorpay

REST API at api.razorpay.com/v1/. The standard payment flow: create an Order (POST /v1/orders with amount, currency, receipt), collect payment via checkout (hosted page or embedded), capture the payment (POST /v1/payments/{id}/capture — Razorpay uses a two-step model). Refunds: POST /v1/payments/{id}/refund. Subscriptions: create plans, then subscriptions linking customers to plans. Invoices for one-time or recurring billing. The API mirrors Stripe's resource-oriented design with some India-specific additions (UPI payment links, virtual accounts for bank transfers). Pagination uses skip/count parameters. Webhooks deliver events for payments, orders, subscriptions, and settlements. QR code generation for UPI payments. Settlement reporting provides reconciliation data. The API design is clean and well-organized.

API errors return JSON with error.code, error.description, error.source, error.step, and error.reason — the most detailed error format among payment gateways. Payment failures include bank-level error reasons (insufficient funds, card declined, authentication failed). Rate limits: per-API-key with generous defaults. The two-step payment model (authorize → capture) means agents must explicitly capture payments — uncaptured payments auto-refund after a configurable period. UPI payment status requires polling or webhooks — UPI payments are async (user approves on their phone). Webhook delivery retries with exponential backoff. Settlement timing varies by payment method (UPI settles faster than cards). For agents, the detailed error taxonomy is valuable for implementing user-friendly error messages and retry logic.

Razorpay is India's leading payment gateway, and its API covers the full spectrum of Indian payment methods: UPI (real-time bank transfers), net banking, credit/debit cards, wallets (Paytm, PhonePe, etc.), EMI, and international payments. For agents building payment flows for the Indian market, Razorpay is essential — no other single gateway covers the breadth of Indian payment instruments. The REST API handles orders, payments, refunds, settlements, subscriptions, invoices, and payouts. Route enables marketplace-style payment splitting. RazorpayX provides business banking APIs (payouts, fund accounts, virtual accounts). Webhooks notify on payment events. For agents outside India, Razorpay's value is limited — it's optimized for INR transactions. The Stripe-like API design makes it familiar to developers experienced with modern payment APIs.

API authentication uses key_id and key_secret via HTTP Basic Auth. Test mode and live mode have separate key pairs — test keys start with rzp_test_, live keys with rzp_live_. No fine-grained API key scoping. Webhook payloads are signed with a webhook secret for verification. OAuth is available for marketplace/platform integrations where Razorpay accounts are connected programmatically. For agents, the key_id/key_secret pair is straightforward — generate in dashboard, use via Basic Auth. The test/live key separation prevents accidental production transactions. Route (marketplace) uses OAuth for connected account access. No IP restrictions on API keys. Key rotation requires creating new keys in the dashboard.

Documentation at razorpay.com/docs is comprehensive, covering API reference, integration guides, and payment method-specific documentation. The documentation explains Indian payment method mechanics (UPI flow, net banking redirect, wallet payment lifecycle), which is essential context for agents unfamiliar with the Indian payment ecosystem. SDKs for Node.js, Python, PHP, Ruby, Java, Go, and .NET are official and maintained. The test mode documentation includes test card numbers, UPI IDs, and net banking credentials for all major banks. Dashboard provides API logs and webhook debugging. The documentation's strength: it contextualizes API operations within Indian payment regulations and practices. For agents building India-focused payment flows, the payment method guides are essential reading alongside the API reference.