# Razorpay integration consultant: payments and payouts your team can trust.

> SBD builds Razorpay integrations for teams of 1 to 1,000 people: payments captured and recorded, refunds tracked, and payouts sent through RazorpayX with idempotency keys, verified webhooks and a person approving anything unusual. Workflow automation builds start at $1,000, with the fixed price set after a $500 Automation Audit that is credited to the build.

- Canonical: https://smallbaydigital.com/integrations/tools/razorpay/
- Publisher: SmallBay Digital

## What a Razorpay integration from SBD does

Razorpay handles collection well. The work around it is where teams lose hours: matching captured payments to orders, chasing payments that were authorised but never captured, raising invoices in the accounting system, and sending payouts to vendors, partners or customers one at a time from the dashboard.

We build both directions. Collections: payment and order events that update your order system, raise the invoice in Zoho Books or another ledger, and notify the customer. Payouts: amounts calculated by rule in your own system, held for approval where needed, then sent through RazorpayX with a full record of who approved what.

We have built this. For an industrial manufacturer that sold only through distributors, we built a [QR cashback system](https://smallbaydigital.com/case-studies/customer-loyalty-system/) on Make, Cloudflare, Razorpay and Google Sheets. End users scan a code in the packaging, the cashback is calculated by rule and paid automatically through a payouts API, and every payout is recorded. The client reported sales up 5 to 10% and end-user engagement tripled.

## When a custom integration beats a plugin

Razorpay has plugins for the major ecommerce platforms and its own dashboard for payment links, subscriptions and bulk payouts. For a store taking payments on a standard checkout, the plugin is the right answer.

A custom integration earns its cost when:

- Payouts are triggered by events in your own system, such as a claim, a delivery or a scan, rather than uploaded in a batch.
- Payments must update an order or dispatch system that has no Razorpay plugin.
- Every payout needs rules, limits per recipient and an approval step before money leaves the account.
- Finance needs captured payments, refunds and settlements matched to invoices in the ledger automatically.

## Razorpay API access, keys and payout rules

Razorpay authenticates API calls with HTTP basic auth using a key ID and key secret. The secret is shown once and Razorpay does not store it, so a lost secret means regenerating keys. Razorpay's payouts documentation adds an important detail: the API keys are the same for the Payment Gateway and RazorpayX, so regenerating keys for one affects the other. We record where every key is used before anyone rotates them.

Razorpay's payout best practices, read in October 2026, set out rules we build in from the start. All payout calls must be server to server; calls from a mobile app or website front end will fail. The calling IP address must be allowlisted. Payout requests should carry an X-Payout-Idempotency header so a retried request does not pay twice. Razorpay suggests keeping calls within 5 to 10 transactions per second. And it advises against polling the Fetch Payout API for status, recommending webhooks instead, deduplicated on payout ID and status because a webhook can fire more than once.

On the collection side, check the capture settings early. Payments created through the Orders API can be captured automatically or manually, and payments not captured within the configured window are refunded automatically to the customer. That window runs from a 12 minute minimum to a default maximum of 3 days, and automatic refunds use normal refund speed, which Razorpay gives as 5 to 7 working days. An integration that relies on manual capture must capture on time or explain to customers why their money came back.

## Razorpay webhooks: signatures, retries and duplicates

Razorpay signs each webhook with HMAC SHA-256 using your webhook secret, sent in the X-Razorpay-Signature header. The signature must be checked against the raw request body; Razorpay specifically warns against parsing or casting the body first. Webhook URLs must use port 80 or 443, and Razorpay's IP addresses may need to be allowed through your firewall.

Your endpoint must respond within 5 seconds or the delivery counts as a timeout and is sent again. Failures are retried with exponential backoff for 24 hours from the event, and if a webhook keeps failing for 24 hours it is disabled until someone re-enables it in the dashboard, with a notice to your alert email address. Delivery is at least once, so each event carries an x-razorpay-event-id header for deduplication. Events usually arrive in order but are not guaranteed to, and for business-critical flows Razorpay suggests also checking the payment APIs. We do both: the webhook triggers the work, and a scheduled check confirms nothing was missed.

## Razorpay data gotchas we design around

Razorpay's objects describe money moving; your ledger describes why it moved. Most of the design work in a Razorpay integration is deciding how one maps to the other, and writing that down before any code is written. These are the points we settle in the audit:

- Orders, payments, refunds and settlements are separate objects with separate timing. One settlement to your bank can cover many payments, so reconciliation starts from the settlement and works down to the payments.
- An authorised payment is not money received. Only captured payments should mark an order as paid, and the integration must know which capture mode each flow uses.
- Every order created through the API carries your own reference in its notes or receipt field, so a payment can always be traced to the order that caused it without matching on amount.
- Payout recipients are created once, validated, and stored with their Razorpay IDs. A payout to a recipient whose bank details changed yesterday is held for a person to check.
- A payout that moves to reversed has failed and needs action. Reversals raise an alert and reopen the claim or order that triggered them.
- Test mode and live mode use different keys and different data. Configuration states which is in use, so a test cannot send real money.

## How a Razorpay engagement with SBD works

Every engagement starts with an [Automation Audit](https://smallbaydigital.com/services/audit/) at $500, credited in full to your build. For Razorpay we follow money in and money out: how orders become payments, how payments reach the ledger, how payouts are decided and approved today, and which keys are used where. You get a ranked list of fixes with fixed prices and a blueprint for the first build.

Workflow automation builds start at $1,000, internal tools at $3,000 and multi-module systems at $5,000. We build on Make, n8n, Cloudflare Workers, Supabase or custom code, depending on volume and where approvals happen. Work runs in two-week sprints and is tested in Razorpay test mode first. Payouts and refunds always pass a rule check, and anything outside the rules waits for a named person. Sixty days of hypercare follow go-live, and care plans start at $50 a month. See the [pricing page](https://smallbaydigital.com/pricing/).

The Razorpay and RazorpayX accounts, keys, webhook secrets and workflows are all yours. You receive a key register, a payout rules document your finance team signs off, and a runbook per integration that says what failure looks like and who is alerted.

## At enterprise scale

Larger organisations typically use Razorpay for collections across several products or brands and RazorpayX for payouts to vendors, distributors, partners or customers. Finance owns the money movement, operations owns the triggers, and the integration questions are about approval rules, reconciliation and key control.

- **Payout controls** Payout rules, limits per recipient and approval thresholds are written down and signed off by finance, then enforced in code before any request reaches RazorpayX.
- **Idempotency** Every payout request carries an idempotency key tied to the business event that caused it, so a retry or a duplicate trigger cannot pay twice.
- **Network and key security** Payout calls run only from allowlisted server IPs. Keys live in your secrets manager, with a register of where they are used, because the same keys serve payments and payouts.
- **Reconciliation** Captured payments, refunds and payouts are matched to invoices and ledger entries daily, with exceptions sent to a named person.
- **Webhook reliability** Handlers verify signatures, deduplicate on event ID, and a scheduled job checks for missed events. A disabled webhook raises an alert the same hour.

### Engagements

- **Already on RazorpayX, payouts uploaded by hand.** Someone builds a payout file every week from a spreadsheet. We calculate payouts from the source events, hold exceptions for approval and send the rest through the API with full records, as in our cashback build.
- **Already on Razorpay, payments not reaching the ledger.** Payments are captured but invoices are raised separately. We raise and settle the invoice from the payment event, so the ledger and the dashboard agree each day.
- **Already on Razorpay, unexplained auto-refunds.** Customers report refunds they did not ask for. We review capture settings, fix the capture step in the order flow, and alert when an authorised payment nears its capture window.

## Related

- [Case study: QR cashback with automated payouts](https://smallbaydigital.com/case-studies/customer-loyalty-system/)
- [Razorpay portfolio](https://smallbaydigital.com/portfolio/tools/razorpay/)
- [Zoho Books integration consultant](https://smallbaydigital.com/integrations/tools/zoho-books/)
- [Stripe integration consultant](https://smallbaydigital.com/integrations/tools/stripe/)
- [Make automation](https://smallbaydigital.com/integrations/tools/make/)
- [Integration services](https://smallbaydigital.com/services/integrations/)

## Sources

- Razorpay: Webhooks best practices (timeout, retries, disabling, duplicates, ordering), checked 29 October 2026 <https://razorpay.com/docs/webhooks/best-practices/>
- Razorpay: Validate and test webhooks (X-Razorpay-Signature, HMAC SHA-256, raw body), checked 29 October 2026 <https://razorpay.com/docs/webhooks/validate-test/>
- Razorpay: Webhooks overview (ports, IP allowlisting), checked 29 October 2026 <https://razorpay.com/docs/webhooks/>
- RazorpayX: Payouts best practices (shared keys, idempotency header, allowlisting, TPS, webhooks over polling), checked 29 October 2026 <https://razorpay.com/docs/x/payouts/best-practices/>
- Razorpay: Payment capture settings (automatic and manual capture, auto-refund timeouts), checked 29 October 2026 <https://razorpay.com/docs/payments/payments/capture-settings/>
