Razorpay online payment and refund operation lifecycle runbook

Razorpay online payment and refund operation lifecycle runbook explains the production operating flow after Razorpay is configured: how staff collect online checkout payments, create and share payment links, wait for signed webhook finalization, process refunds, review settlements, handle disputes, and keep mobile payment actions backend-confirmed.

What this page is for

Who should use it

Owner, finance admin, front desk, sales, platform admin, support

Where to find it

Commerce checkout, invoice detail, payment links, refunds, disputes, settlements, Razorpay Dashboard

Before you start

Razorpay online payment and refund operation lifecycle runbook is required after the gateway setup runbook and before staff are trained to use Razorpay checkout, payment links, refunds, settlements, or disputes in production.
Razorpay checkout collection starts from a finalized SquareOS invoice or checkout preview and records selected gatewayAccountId, paymentMethodId, invoice id, amountMinor, currency, order/payment intent id, idempotency key, customer, staff actor, and disabled reason when checkout is not allowed.
Razorpay payment-link collection starts from a finalized invoice or payable balance and records paymentLinkId, provider payment_link id, short URL, amountMinor, expiry, send/copy channel, recipient, staff actor, and one backend-created link before staff shares it.
Razorpay webhook finalization accepts only verified x-razorpay-signature callbacks for payment.captured, payment.authorized, payment.failed, payment_link.paid, payment_link.cancelled, payment_link.expired, or invoice.paid before changing payment, invoice, allocation, subscription activation, or payment-link state.
Duplicate or unmatched Razorpay callbacks must remain webhook evidence with duplicate or no-local-record status and must not create duplicate payments, duplicate allocations, duplicate subscription activation, or manual success.
Razorpay refund operation starts from a settled SquareOS payment and records refund policy, refundable amount, staff approver, reason, original provider payment id, Razorpay refund id when online, SquareOS refund id, credit note, payment status, audit row, and finance sign-off.
Razorpay refund, settlement, and dispute follow-up must not be described as automatic payment webhook finalization unless the current backend handler updates those records; today refunds are created through the refund API path and settlements/disputes are reconciled through explicit gateway sync/review actions.
Razorpay settlement review records gateway account, settlement id or batch, settlement date, gross amount, fees, refunds, disputes, net amount, bank credit, sync action id, mismatch reason, and finance close status.
Razorpay dispute review records dispute id, payment id, invoice/person, reason, amount, respond-by date, evidence owner, submitted evidence, provider status, access decision, refund/void decision, and audit trail before staff changes service access.
Razorpay operation secret handling forbids exposing Key Secret, webhook secret, raw x-razorpay-signature, raw webhook payload, checkout order payload, payment link URL in logs without redaction, refund payload, settlement bank details, dispute evidence with private data, or KYC screenshots in mobile, support, analytics, crash logs, or public docs.

Daily workflow

For checkout, start from Commerce checkout, Invoice detail, POS focused sale, upgrade invoice, or another backend-created payable invoice. Confirm the invoice is finalized, balance is payable, customer is correct, amount and currency match the screen, Razorpay gateway is active, supports checkout is enabled, webhook status is verified or accepted for test, and no duplicate pending online payment already exists.
Create the checkout/order/payment intent through the backend only. The evidence row should include tenant, gym, invoice id, customer/person id, selected gatewayAccountId, paymentMethodId, amountMinor, currency, order/payment intent id, idempotency key or request id, staff actor, and disabled reason if the action is blocked.
When the customer completes Razorpay checkout, do not mark success from the browser return, customer screenshot, payment id typed by staff, or cached state. The paid state is final only after the backend receives and verifies x-razorpay-signature and reconciles payment.captured, order.paid, payment.authorized, or payment.failed according to the event.
For payment links, start from a finalized invoice, upgrade invoice, renewal due, trial conversion offer, pending balance, or sales handoff that the backend says is payable. Create the payment link from SquareOS so the provider payment_link id, short URL, amountMinor, expiry, invoice id, customer, staff actor, and send/copy channel are stored before the link is shared.
Payment links can be sent over backend-approved channels such as SMS, WhatsApp, email, or copied by staff only after the backend returns an active paymentLinkId and URL. Staff must not edit amount, recipient, invoice mapping, expiry, or provider id after creation from a local/mobile draft.
When Razorpay sends payment_link.paid or invoice.paid, SquareOS must match the provider payment_link id, create or update one payment, allocate to the invoice once, reduce balance, mark the payment link succeeded, activate paid subscriptions when the invoice is fully paid, write a payment state transition, and keep duplicate callbacks idempotent.
If Razorpay sends payment_link.cancelled or payment_link.expired, SquareOS should mark the payment link failed/expired and keep the invoice payable through a replacement link or another payment method. Staff should not reuse expired URLs or promise payment was collected.
For duplicate callbacks, compare provider event id, provider payment id, payment_link id, raw payload, and existing processed webhook event. A duplicate or unmatched webhook is evidence for support, not permission to create a manual payment or second allocation.
For online refunds, start from a settled SquareOS payment with status SUCCEEDED or RECORDED and a linked invoice. Confirm refund policy, refundable amount, original provider payment id, finance approver, staff role, reason, and whether the gateway account supports refunds before submitting.
Create the refund through the SquareOS/Razorpay path. Record Razorpay refund id, SquareOS refund id, credit note id, payment status after refund, refund amount, reason, staff actor, audit row, and finance sign-off. If provider status is still processing, label it processing rather than completed until a supported status check or finance proof confirms completion.
Settlement review is a finance close process. Run the explicit gateway settlement sync/review action, then compare settlement id or batch, settlement date, gross amount, fees, refunds, disputes, net amount, bank credit, and mismatch reason against the Razorpay dashboard before closing the day.
Dispute review is a finance/support process. Run the explicit gateway dispute sync/review action, then record dispute id, payment id, invoice/person, reason, amount, respond-by date, evidence owner, submitted evidence, provider state, access decision, refund/void decision, and audit row before changing service access.
Keep the official source references in the extraction row: Razorpay payments webhook events, payment-link creation and webhook docs, webhook setup/signature validation docs, refunds API docs, refund idempotency/status docs, and the SquareOS payment/refund/dispute/settlement code evidence used for the tenant.

Watch out

Do not call browser return, Razorpay dashboard screenshot, customer screenshot, UPI app success screen, or manually typed provider id a SquareOS payment until the backend has reconciled a verified callback or certified status refresh.
Do not share a Razorpay payment link that was not created by SquareOS for the exact invoice/person/amount. External dashboard links can break invoice allocation, subscription activation, audit trail, and mobile attribution.
Do not promise refunds as completed when SquareOS has only created a refund request. Finance should distinguish requested, provider processing, processed, failed, and manually reviewed states.
Do not describe settlement and dispute rows as automatically finalized by normal payment webhooks unless the backend handler for that event updates those records in the current release. Use explicit sync/review evidence.
Do not expose payment link URLs in logs or analytics without redaction. They can let the wrong person view or pay a customer invoice when leaked.
Do not let member or staff mobile mutate gateway setup, provider ids, refunds, settlements, disputes, or invoice paid state locally. Mobile can initiate backend-approved payment collection and show backend-confirmed status only.

Use the left menu to open related pages in Start Here.
Use Ask Docs for questions that are already covered in this public documentation.