A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Razorpay API is how an app or AI agent works with a Razorpay account: creating an order, capturing a payment, refunding a customer, running recurring subscriptions, or sending a bank payout through RazorpayX. Access is granted through an API key that is account-level and carries no per-endpoint scopes, so any valid key can reach every API the account is enabled for. A state change emits an event that Razorpay can deliver to a registered endpoint.
How an app or AI agent connects to Razorpay determines what it can reach. There is a route for making calls, a route for receiving events, and a hosted server that exposes Razorpay tools to agents, and each is governed by the key behind it.
The REST API takes JSON request bodies, returns JSON, and pages through lists with a count-and-skip window, at https://api.razorpay.com/v1. A call authenticates with an API key over HTTP Basic auth, sending the key id as the username and the key secret as the password. Every key belongs to one mode, either test or live.
Razorpay POSTs an event payload to an HTTPS endpoint configured in the Dashboard or via the API. The receiver verifies the X-Razorpay-Signature header, an HMAC SHA256 of the raw request body keyed with the webhook secret, to confirm the request came from Razorpay. Events cover payments, orders, refunds, settlements, invoices, subscriptions, payment links, and payouts.
Razorpay publishes an official Model Context Protocol server that exposes Razorpay tools to AI agents and LLM clients. A hosted remote server runs at https://mcp.razorpay.com/mcp with no local setup and authenticates with a merchant token (the base64 of key id and key secret); a self-hosted build runs locally with the key id and key secret. Tools cover orders, payments, payment links, refunds, QR codes, settlements, payouts, and saved tokens.
Every first-party call authenticates with an API key over HTTP Basic auth: the key id is the username and the key secret is the password. A key pair is account-level and carries no per-endpoint scopes, so any valid key can call any API the account is enabled for. The key secret is shown only once, when the key is generated, and must never be exposed in client code.
Razorpay offers OAuth 2.0 for partners and platforms that act on merchants' accounts they don't own. A merchant authorizes the application, which receives an access token tied to that merchant's account. This is for partner integrations, not for a single business calling its own account.
The Razorpay API is split into areas an agent can act on, like orders, payments, refunds, customers, recurring billing, payment links, settlements, and bank payouts. Each area has its own methods, and writes in some areas move real money or send funds out of the account.
Methods for creating and retrieving orders, the record a payment is collected against.
Methods for capturing and retrieving payments.
Methods for refunding payments and retrieving refunds.
Methods for creating and retrieving customers.
Methods for recurring billing through plans and subscriptions.
Methods for creating and managing hosted payment links.
Methods for creating, issuing, and managing invoices.
Methods for retrieving settlements, the transfers of collected funds to a bank account.
RazorpayX methods for sending money out to contacts and their bank accounts.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
OrdersMethods for creating and retrieving orders, the record a payment is collected against.4 | ||||||
| POST | /v1/orders | Create an order, the record a payment is collected and verified against. | write | — | Current | |
Razorpay keys are account-level with no per-endpoint scopes; any valid key can call this. Acts onorder Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/orders/:id | Fetch the details of an order by its id. | read | — | Current | |
Read-only; no per-endpoint scope. Acts onorder Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/orders | Fetch all orders, filterable by time and payment state. | read | — | Current | |
Read-only; default page size 10, maximum 100. Acts onorder Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/orders/:id/payments | Fetch all payments made against an order. | read | — | Current | |
Read-only. Acts onpayment Permission (capability)None required VersionAvailable since the API’s base version Webhook event order.paidRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
PaymentsMethods for capturing and retrieving payments.4 | ||||||
| POST | /v1/payments/:id/capture | Capture an authorized payment to collect the funds. | write | — | Current | |
Collects money; an uncaptured authorized payment is voided if not captured in time. Acts onpayment Permission (capability)None required VersionAvailable since the API’s base version Webhook event payment.capturedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/payments/:id | Fetch the details of a payment by its id. | read | — | Current | |
Read-only; card, EMI, and offer details can be returned with an expand parameter. Acts onpayment Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/payments | Fetch all payments, filterable by time and order. | read | — | Current | |
Read-only; default page size 10, maximum 100. Acts onpayment Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /v1/payments/:id | Update the notes attached to a payment. | write | — | Current | |
Edits the notes object only, not amount or status. Acts onpayment Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
RefundsMethods for refunding payments and retrieving refunds.4 | ||||||
| POST | /v1/payments/:id/refunds | Refund a payment, in full or in part. | write | — | Current | |
Returns real money; supports a speed of normal or optimum (instant). Acts onrefund Permission (capability)None required VersionAvailable since the API’s base version Webhook event refund.createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/refunds/:id | Fetch the details of a refund by its id. | read | — | Current | |
Read-only. Acts onrefund Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/refunds | Fetch all refunds created in the account. | read | — | Current | |
Read-only; default page size 10, maximum 100. Acts onrefund Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /v1/refunds/:id | Update the notes attached to a refund. | write | — | Current | |
Edits the notes object only. Acts onrefund Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
CustomersMethods for creating and retrieving customers.3 | ||||||
| POST | /v1/customers | Create a customer to store contact details and saved tokens. | write | — | Current | |
A core write; a customer holds email, phone, and saved payment methods. Acts oncustomer Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/customers/:id | Fetch the details of a customer by its id. | read | — | Current | |
Read-only; returns the customer's contact details. Acts oncustomer Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /v1/customers/:id | Edit a customer's name, email, or contact details. | write | — | Current | |
A core write to a customer record. Acts oncustomer Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Subscriptions & PlansMethods for recurring billing through plans and subscriptions.5 | ||||||
| POST | /v1/plans | Create a plan defining the amount and interval for recurring billing. | write | — | Current | |
A plan is the template a subscription bills against. Acts onplan Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/plans | Fetch all plans created in the account. | read | — | Current | |
Read-only. Acts onplan Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/subscriptions | Create a subscription on a plan for recurring billing. | write | — | Current | |
Starts recurring billing once the customer authorizes the mandate. Acts onsubscription Permission (capability)None required VersionAvailable since the API’s base version Webhook event subscription.activatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/subscriptions/:id | Fetch the details of a subscription by its id. | read | — | Current | |
Read-only. Acts onsubscription Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/subscriptions/:id/cancel | Cancel a subscription, immediately or at the end of the cycle. | write | — | Current | |
Ends recurring billing for the customer. Acts onsubscription Permission (capability)None required VersionAvailable since the API’s base version Webhook event subscription.cancelledRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Payment LinksMethods for creating and managing hosted payment links.3 | ||||||
| POST | /v1/payment_links | Create a hosted payment link a customer can pay through. | write | — | Current | |
Creates a real payable link; can notify the customer by SMS or email. Acts onpayment_link Permission (capability)None required VersionAvailable since the API’s base version Webhook event payment_link.paidRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/payment_links | Fetch all payment links created in the account. | read | — | Current | |
Read-only. Acts onpayment_link Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/payment_links/:id/cancel | Cancel a payment link so it can no longer be paid. | write | — | Current | |
Only works on a link that has not yet been paid. Acts onpayment_link Permission (capability)None required VersionAvailable since the API’s base version Webhook event payment_link.cancelledRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
InvoicesMethods for creating, issuing, and managing invoices.4 | ||||||
| POST | /v1/invoices | Create a draft invoice for a customer. | write | — | Current | |
Starts in draft until issued. Acts oninvoice Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/invoices/:id/issue | Issue a draft invoice so it becomes payable and is sent to the customer. | write | — | Current | |
Moves the invoice from draft to issued and notifies the customer. Acts oninvoice Permission (capability)None required VersionAvailable since the API’s base version Webhook event invoice.paidRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/invoices | Fetch all invoices created in the account. | read | — | Current | |
Read-only; default page size 10, maximum 100. Acts oninvoice Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/invoices/:id/cancel | Cancel an issued invoice so it can no longer be paid. | write | — | Current | |
A cancelled invoice cannot be reverted. Acts oninvoice Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
SettlementsMethods for retrieving settlements, the transfers of collected funds to a bank account.3 | ||||||
| GET | /v1/settlements | Fetch all settlements, the transfers of collected funds to a bank account. | read | — | Current | |
Read-only; reveals settled amounts and dates. Acts onsettlement Permission (capability)None required VersionAvailable since the API’s base version Webhook event settlement.processedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/settlements/:id | Fetch the details of a settlement by its id. | read | — | Current | |
Read-only. Acts onsettlement Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/settlements/recon/details | Fetch settlement reconciliation details for a given day or range. | read | — | Current | |
Read-only; maps settled amounts back to the underlying transactions. Acts onsettlement Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Payouts (RazorpayX)RazorpayX methods for sending money out to contacts and their bank accounts.6 | ||||||
| POST | /v1/contacts | Create a contact, the person or business a RazorpayX payout is sent to. | write | — | Current | |
RazorpayX feature; a contact holds a payee's name and details. Acts oncontact Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/fund_accounts | Create a fund account, the bank account or VPA a contact is paid into. | write | — | Current | |
RazorpayX feature; a fund account links a bank account or UPI VPA to a contact. Acts onfund_account Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/payouts | Create a payout to send money to a contact's fund account. | write | — | Current | |
Sends real money out of the RazorpayX business account; an Idempotency-Key header is mandatory. Acts onpayout Permission (capability)None required VersionAvailable since the API’s base version Webhook event payout.processedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/payouts/:id | Fetch the details of a payout by its id. | read | — | Current | |
Read-only; RazorpayX feature. Acts onpayout Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/payouts | Fetch all payouts made from a RazorpayX account. | read | — | Current | |
Read-only; RazorpayX feature. Acts onpayout Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/payouts/:id/cancel | Cancel a payout that is still in the queued state. | write | — | Current | |
Only works on a payout in the queued state, not one already processing. Acts onpayout Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Razorpay can notify an app when something happens in an account, like a payment being captured or a payout being processed. It POSTs an event payload describing what changed, so an integration learns about activity without polling.
| Event | What it signals | Triggered by |
|---|---|---|
payment.captured | A payment was captured and the funds are collected. An integration fulfills the order on this event. | /v1/payments/:id/capture |
order.paid | An order was fully paid, fired when the payment associated with the order is captured. | /v1/orders/:id/payments |
refund.created | A refund was created against a payment. | /v1/payments/:id/refunds |
subscription.activated | A subscription became active after the customer authorized the mandate, and recurring billing has begun. | /v1/subscriptions |
subscription.cancelled | A subscription was cancelled, so recurring billing has stopped. | /v1/subscriptions/:id/cancel |
payment_link.paid | A payment link was paid in full by the customer. | /v1/payment_links |
payment_link.cancelled | A payment link was cancelled and can no longer be paid. | /v1/payment_links/:id/cancel |
invoice.paid | An invoice was paid in full by the customer. | /v1/invoices/:id/issue |
settlement.processed | A settlement was processed and the collected funds were transferred to the linked bank account. | /v1/settlements |
payout.processed | A RazorpayX payout was processed and the money was sent to the contact's fund account. | /v1/payouts |
Razorpay limits how fast an app can call, returning a rate-limit response when requests arrive too quickly, and pages long lists with a count-and-skip window.
Razorpay meters requests by rate, not by a per-method cost or point weighting. The reference does not publish a fixed numeric ceiling; going over returns HTTP 429 with a RATE_LIMIT_EXCEEDED code, and the documentation directs integrations to watch for 429 and retry with an exponential or stepped backoff plus randomization to avoid a thundering-herd of retries. RazorpayX payouts add their own controls, including a mandatory idempotency key and IP allowlisting.
A list endpoint uses a count-and-skip window: count sets the page size, default 10 and maximum 100, and skip sets how many records to step past. Lists can also be filtered by a from and to time range. Results are returned newest first.
A list endpoint returns at most 100 records per page, the maximum value of count. An identifier is 14 characters, alphanumeric and case-sensitive. The notes object on a resource holds up to 15 key-value pairs, each value up to 256 characters.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | BAD_REQUEST_ERROR | The request was bad: a parameter is missing or invalid, an unsupported value was sent, or the key is wrong. This class also covers authentication and authorization problems. | Read the description, field, and reason in the error body, fix the request, and resend. The request is not retryable as-is. |
| 429 | RATE_LIMIT_EXCEEDED | Requests arrived faster than the allowed rate within the time window. | Back off and retry with exponential backoff and jitter, and smooth the request rate. |
| 502 | GATEWAY_ERROR | The request could not be completed due to an error at the payment gateway or a downstream bank. | Confirm the final payment state before retrying, since the downstream system may have acted, and retry idempotently. |
| 500 | SERVER_ERROR | An error on Razorpay's side while processing the request, which can be transient. | Retry with the same idempotency key and request body following the recommended 5XX retry schedule, and contact support if it persists. |
Razorpay carries one URL version, and describes its changes as backward-compatible, so an integration is not pinned to a dated release the way some payment APIs are.
Razorpay carries a single URL version, v1, and describes its API changes as backward-compatible, so an integration is not pinned to a dated release per request. New resources and fields are added under the same version. Authentication is an account-level API key over HTTP Basic auth.
Razorpay shipped an official Model Context Protocol server, exposing Razorpay tools to AI agents and LLM clients through a hosted remote endpoint and a self-hosted build.
RazorpayX made an idempotency key mandatory on all payout requests, so a retried payout cannot be duplicated.
Stay on v1; changes are described as backward-compatible.
Razorpay API reference ↗Bollard AI sits between a team's AI agents and Razorpay. A Razorpay key is account-level and reaches everything, so Bollard restores the missing per-agent boundary: grant each agent exactly the actions it needs, resource by resource, and check and log every call.