Create an order server-side: POST /v1/orders with 'amount' in paise (1 INR = 100 paise), 'currency' as 'INR' (or supported foreign currency), and 'receipt' as your internal order reference; authenticate with HTTP Basic using your key_id and key_secret.
Pass the returned 'order_id' to the Razorpay checkout.js or mobile SDK on the client along with 'key' (your public key_id), 'amount', and 'currency'; the SDK handles UPI, netbanking, cards, and wallets.
On successful payment, Razorpay invokes your handler callback with 'razorpay_payment_id', 'razorpay_order_id', and 'razorpay_signature'.
Verify the signature server-side: construct the message as '{razorpay_order_id}|{razorpay_payment_id}', compute HMAC-SHA256 using your key_secret, hex-encode it, and compare to 'razorpay_signature' with a constant-time comparison.
If the signature is valid, capture the payment if your account is not set to auto-capture: POST /v1/payments/{payment_id}/capture with 'amount' and 'currency'.
Subscribe to Razorpay webhooks in the dashboard for 'payment.captured' and 'payment.failed' events as the authoritative source of truth, since client callbacks can be tampered with or interrupted.
Known gotchas
India's RBI mandate means certain card transactions above a threshold require Additional Factor of Authentication (AFA/2FA); Razorpay handles the redirect automatically via the SDK, but your backend must not assume instant capture.
The signature verification step is the only thing preventing a malicious client from passing a fabricated payment_id — skipping it is a critical security vulnerability that allows order fulfillment without actual payment.
Razorpay payments for international cards may require the merchant to enable international payments explicitly in the dashboard; domestic-only accounts will see declines on foreign cards with a specific error code.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp