Razorpay Integration for Websites and Apps

Description

Integration Razorpay integration: orders, webhooks, refunds and reconciliation

A Razorpay integration creates an order on your server, opens Razorpay's checkout, verifies the signature it returns, and then relies on signed webhooks to mark orders paid, failed or refunded. WavX builds the server side of that flow, with duplicate-safe webhook handling and a daily match against settlements. This guide is written from Razorpay's documentation as read on 2 October 2026.

Discuss an integration Last updated 2 October 2026

What the integration does

Razorpay is an Indian payment gateway: it collects money from a customer by UPI, card, netbanking, wallet or EMI and settles it to your bank account. An integration connects that to your own software, so that an order in your system becomes a payment at Razorpay, and the result of the payment comes back and changes the order.

The hard part is the path back: knowing, on your server, that a payment really succeeded, exactly once, even when the customer's phone loses signal at the wrong moment. The earlier WavX post on how to integrate Razorpay covers the checkout side; this page covers the whole loop, including refunds and settlement.

Data that flows each way

Event or object

Direction

What your system does with it

Order ( POST /v1/orders : amount, currency, receipt)

Your server to Razorpay

Stores the returned order id against your own order before checkout opens

Checkout result ( razorpay_payment_id , razorpay_order_id , razorpay_signature )

Razorpay to browser to your server

Verifies the signature; treats it as a hint, not as proof on its own

payment.authorized , payment.captured , payment.failed

Razorpay to your server (webhook)

Moves the order to paid or failed; releases stock on failure

order.paid

Confirms the order as a whole is paid; payload carries order and payment

Refund request ( POST /v1/payments/{payment_id}/refund )

Records a pending refund against the order

refund.created , refund.processed , refund.failed

Updates refund status; alerts staff when a refund fails

Settlement records

Razorpay to your server (API or report)

Matches each captured payment to money received in the bank

The main flow, step by step

Razorpay's Standard Checkout guide lists six steps. In practice they run like this:

Create the order on your server. Call the Orders API with the amount in the smallest currency unit (₹499 is sent as 49900 ), the currency, and your own reference in receipt (up to 40 characters). Razorpay returns an order id with status created .

Open checkout in the browser or app with that order id. The amount comes from the order, so it cannot be edited in the browser.

Receive the result. On success, checkout hands back a payment id, the order id and a signature.

Store those fields and verify the signature on your server. The signature is an HMAC SHA256 of order_id|razorpay_payment_id using your key secret. If your computed value does not match, reject it.

Confirm the payment status. Razorpay's docs treat this as a separate step: check that the payment is captured , by webhook or by API.

Act on the webhook. Mark the order paid when payment.captured or order.paid arrives, whether or not step 3 ever reached you.

Refunds reverse the loop: your server asks for a full or partial refund of a captured payment, and the outcome arrives later as a refund event.

Limits and rules Razorpay documents

Rule

What the documentation says

Authentication

Basic auth with a key id and key secret; separate keys for test mode and live mode

Order notes

Up to 15 key-value pairs, 256 characters each

Capture window

A payment left in the authorised state must be captured within 3 days of creation, or it is refunded automatically

Late authorisation

When a bank does not report a result at once, Razorpay keeps polling for 3 days

Webhook endpoints

Up to 30 URLs; ports 80 and 443 only

Webhook acknowledgement

A 2XX response within 5 seconds; anything else counts as a failure

Webhook retries

Exponential back-off for 24 hours; if failures continue for 24 hours the webhook is disabled and an alert email is sent

Webhook duplicates and order

The same event can arrive more than once, and events may arrive out of sequence; the x-razorpay-event-id header is unique per event

Webhook signature

X-Razorpay-Signature , an HMAC SHA256 of the raw request body with your webhook secret; the body must not be parsed first

Refunds

Only on captured payments; normal speed is 5 to 7 working days; a refund can fail when the payment is more than six months old

Rate limits

No number is published; the API returns HTTP 429 when throttled and the docs ask for retries with back-off

Settlement

T+2 working days for domestic payments, counted from the date of capture

Test mode mirrors live mode: test keys, test payments and test webhooks with the same payload shape, so the whole loop can be exercised before any money moves.

Common failure modes

Paid at the bank, unpaid in your system. The order was marked paid only from the browser callback, and the customer closed the tab. The fix is the webhook plus a scheduled status check.

Double fulfilment. A retried webhook is processed twice. Store the event id and skip any id you have seen.

Signature check fails on every webhook. The framework parsed the JSON before the check. The signature is computed over the raw bytes.

A disabled webhook nobody noticed. After a day of failed deliveries Razorpay switches the webhook off. The alert email needs to go to an address someone reads.

Refund shown as done when it is pending. A refund request is accepted first and processed later; the status to show the customer comes from the refund events.

Events out of order. payment.failed for a first attempt can arrive after payment.captured for a second. Order state should only move forward.

The vocabulary here (endpoint, signature, retry) is explained in what is a webhook .

Fees

As of October 2026, Razorpay's pricing page (marked last updated May 2026) lists:

Item

Published figure

Platform fee, domestic payment methods

2% per successful transaction

Corporate and business credit cards

2.15%

International cards

Up to 3% per successful transaction

GST on the platform fee

Setup fee and annual maintenance charge

₹0

Refund processing fee

Subscriptions are priced separately on the same page. These are Razorpay's charges, not WavX's, and they are deducted before settlement.

What WavX builds around it

For a client who needs Razorpay connected to a website, app or internal system, WavX builds:

Server-side order creation tied to your order model, so every payment has an order behind it.

Signature verification for both the checkout result and incoming webhooks.

A webhook receiver that acknowledges within the 5-second window, queues the work, and ignores duplicates by event id.

A scheduled reconciliation job that compares your orders with Razorpay's payments and settlements and lists the mismatches for a person to review.

Full and partial refunds from your admin panel, with status that follows the refund events.

A log of every request and event, so "I paid but did not get my order" can be answered from records.

Recurring billing is a separate build; see UPI Autopay integration . The wider service is described under payment gateway integration .

WavX does not publish a price for a single integration; it is quoted after scoping. For planning, the software cost estimator carries third-party integrations as a ₹60,000 feature line on top of the base build. Its output is a planning range, not a quote.

When a plugin or payment link is enough

You may not need custom work at all:

Your store runs on a standard platform. Razorpay publishes plugins for Shopify, WooCommerce, Wix, Magento, BigCommerce, OpenCart and others. Install the plugin and the checkout works.

You take a few payments a week. Razorpay Payment Links are created in the dashboard and shared by SMS or email, with no website or code.

You have not chosen a gateway yet. Read how to take payments online in India first, and compare providers before paying for an integration with any one of them.

Custom integration earns its cost when payment has to change something in your own system: stock, an ERP entry, a subscription, a ledger, or a refund rule that the plugin cannot express.

Frequently asked questions

How long does a Razorpay integration take?

It depends on what surrounds the payment: one checkout on one site is small, while refunds, partial payments, subscriptions and accounting sync each add work. We quote after scoping. Razorpay's own account activation and KYC run on Razorpay's timeline, so start that first.

Is the checkout callback enough to mark an order as paid?

No. The callback runs in the customer's browser, and the customer can close the tab before it completes. Razorpay's integration steps ask you to verify the signature on your server and then confirm the payment status, and its webhooks exist so your server hears about the payment even when the browser does not report back.

What does Razorpay charge?

As of October 2026 Razorpay's pricing page lists a platform fee of 2% per successful transaction on domestic payment methods, plus 18% GST on that fee, with no setup fee and no annual maintenance charge. International cards are listed at up to 3%. Check the pricing page before you budget, because the figures change.

Can you add Razorpay to software another team built?

Yes, if we can get the source code and a test-mode key. We read the existing order and payment code first, because a payment flow added on top of an order model that cannot represent a pending or partly refunded order will misreport.

Do I need a developer if I use Shopify or WooCommerce?

Usually not for the payment itself. Razorpay publishes plugins for both, and the plugin handles checkout. A developer is needed when the payment has to drive something the plugin does not cover, such as an ERP entry, a custom refund rule or a subscription.

Sources

Razorpay pricing · read 2 October 2026

Razorpay docs: Standard Checkout integration steps · read 2 October 2026

Razorpay docs: Create an order API · read 2 October 2026

Razorpay docs: Set up webhooks for payments · read 2 October 2026

Razorpay docs: Webhook best practices · read 2 October 2026

Razorpay docs: Validate and test webhooks · read 2 October 2026

Razorpay docs: Payment webhook events · read 2 October 2026

Razorpay docs: Refund webhook events · read 2 October 2026

Razorpay docs: Create a normal refund API · read 2 October 2026

Razorpay docs: Payment capture settings · read 2 October 2026

Razorpay docs: Settlements · read 2 October 2026

Razorpay docs: Understand the APIs (authentication, errors, rate limiting) · read 2 October 2026

Razorpay docs: E-commerce plugins · read 2 October 2026

Razorpay docs: API keys (test and live mode) · read 2 October 2026

Razorpay docs: Payment Links · read 2 October 2026

Related

UPI Autopay integration for recurring payments

Payment gateway integration

What is a webhook?

Build your own software — your way, your pricing.

WavX Solutions is here to create your own software in a fully custom way, built exactly how you work — with a pricing model that fits your business. Connect now and let's build it.

Contact Now helpwavx@gmail.com