The WooCommerce order status pending payment and the Razorpay payment status authorized are not the same thing, and treating them as equivalent is where the first chunk of monthly revenue — somewhere in the ₹8,000 to ₹15,000 range on a mid-sized store, give or take, based on what we've seen on a handful of builds this year — goes missing. The finance team always finds it before we do. Usually on a Monday morning, usually with a spreadsheet open and a question that starts "why does Razorpay say…".
The short version: WooCommerce and Razorpay each run their own state machine, and the default plugin assumes they're isomorphic — which they emphatically are not. The gap between them is where the money sits, uncounted, until somebody runs a diff.
Two state machines, pretending to be one
Razorpay's payment object moves through created → authorized → captured → refunded, with failed as a terminal branch. Those are the five states that matter at the payment level (there are more at the order and settlement level, which is where this story goes sideways later). The WooCommerce order, on the other hand, moves through pending, failed, on-hold, processing, completed, cancelled, refunded. Seven states, and the mapping to Razorpay's five is not clean in either direction.
The default Razorpay WooCommerce plugin — the one most stores install from the WordPress repo and never touch again — collapses this. It listens for payment.captured, flips the WooCommerce order to processing, and considers the job done. Which is fine, right up to the point where it isn't.
Consider what processing actually means in WooCommerce's head: payment received, stock reduced, awaiting fulfilment. Now consider what captured means in Razorpay's head: the authorised amount — or some portion of it — has been moved from the customer's instrument to your Razorpay balance, pending settlement. Those are not the same claim. One is about fulfilment readiness. The other is about money movement, partial or otherwise, pre-settlement, pre-reversal, pre-any-of-the-things-that-can-still-go-wrong-in-the-next-72-hours.
We wrote about the webhook race condition before — the ordering problem is covered elsewhere, so we won't rehash it here. This post is about the state-shape problem, which is different and arguably worse because it doesn't look like a bug. It looks like everything worked.
Where the mismatch becomes money: the partial-capture path, and three others
Take the partial-capture case first. An order for ₹4,680 comes in. The issuing bank — one of the mid-tier private banks — has a per-transaction card limit set by the customer that nobody on the merchant side knows about. Razorpay authorises the full ₹4,680. The capture call, which the plugin fires on checkout completion, succeeds for ₹2,340 and that is it. Partial capture. Clean partial capture, with a proper response payload. The webhook fires. The plugin reads payment.captured, sees a captured event, flips the order to processing, sends the fulfilment email.
The warehouse ships ₹4,680 worth of goods. Razorpay settles ₹2,340 two days later. Tally, reconciling against the invoice total that WooCommerce generated, books ₹4,680 in revenue against a ₹2,340 settlement line. The gap sits on the books for weeks before anyone notices, and it usually only comes up because the quarterly GST workings don't tie out.
The reason the plugin gets it wrong is small and specific. The Razorpay webhook payload for payment.captured contains three amount fields: amount (the authorised amount, in paise), amount_captured (what actually moved), and amount_refunded (what, if anything, has already been reversed). The default plugin reads amount. It should read amount_captured, and it should compare that against the WooCommerce order total, and if the two don't match it should park the order in on-hold and raise a flag — not flip it to processing.
Partial capture is the one above. The other three paths we've seen enough times to recognise on sight:
- Authorised but never captured. Customer completes checkout, Razorpay authorises, the capture call fails or times out, no retry. WooCommerce sits at
pending payment. Razorpay sits atauthorized. The auth expires in five days — on most card networks, give or take — and the funds release back to the customer. If anyone chased the order in the meantime and the customer paid again through a different channel, you've now got a ghost order in WooCommerce that reconciles to nothing. - Captured, then auto-refunded by Razorpay for KYC or risk reasons. This fires a
payment.refundedevent, which the plugin usually does handle — but only if the webhook is configured, which on about a third of the handovers we inherit, it isn't. (The merchant enabled webhooks in test mode, flipped to live, and never re-registered the live-mode endpoint. Common.) - Settlement reversal 48–72 hours after capture. This is the ugly one and we'll come back to it.
- Multi-capture on a single authorisation. Rare in a standard WooCommerce flow, but we've seen it on subscription-adjacent stores where someone bolted on custom capture-on-ship logic. If two captures hit the same authorisation, the plugin processes the first and ignores the second, because the order is already in
processingand the state-machine logic doesn't re-enter.
What we changed after a quarterly audit flagged the gap
On one of our longer-standing clients — a D2C skincare brand in the ₹2–3 crore annual range — we ran a reconciliation audit at the end of a quarter. Pulled the Razorpay settlement CSV, pulled the WooCommerce orders table, ran a diff. Roughly nineteen orders came out mismatched, totalling somewhere north of ₹60,000. Not catastrophic in GMV terms, but it was money that had been invoiced, shipped, and never settled — and nobody had caught it for three months.
The query we now run on every store looks roughly like this (pseudo-SQL, because the real one has a few more joins for GST line items and a date-range filter):
SELECT
p.ID AS order_id,
p.post_status AS wc_status,
pm_total.meta_value AS wc_order_total,
pm_rzp.meta_value AS razorpay_payment_id,
s.amount_settled AS rzp_settled_amount,
s.amount_captured AS rzp_captured_amount
FROM wp_posts p
JOIN wp_postmeta pm_total
ON pm_total.post_id = p.ID
AND pm_total.meta_key = '_order_total'
LEFT JOIN wp_postmeta pm_rzp
ON pm_rzp.post_id = p.ID
AND pm_rzp.meta_key = '_transaction_id'
LEFT JOIN razorpay_settlement_csv s
ON s.payment_id = pm_rzp.meta_value
WHERE p.post_type = 'shop_order'
AND p.post_status IN ('wc-processing', 'wc-completed')
AND (
s.amount_captured IS NULL
OR CAST(pm_total.meta_value AS DECIMAL(10,2))
<> (s.amount_captured / 100)
);
The razorpay_settlement_csv table is just the settlement export loaded into a scratch MySQL table — we don't try to join against the Razorpay API live, it's too slow and the rate limits bite. The CSV comes down from the Razorpay dashboard, we drop it in, run the query, look at the rows that fall out.
Rows that fall out usually land in three piles. Partial captures (the ₹2,340-of-₹4,680 case). Captures with no corresponding settlement line, which usually means a reversal we didn't catch. And occasionally, settlement lines with no matching WooCommerce order, which usually means a manual payment link somebody on the ops team created outside the normal checkout flow and forgot to tell anyone about. That last one isn't really a plugin bug but it shows up in the same diff, so we leave it in.
What we changed on the plugin side after that audit:
- We now read
amount_capturedfrom the webhook payload, notamount. If it doesn't match the order total, the order goes toon-holdwith a note, notprocessing. - We added a nightly cron that pulls the last 48 hours of Razorpay payments via the API and reconciles state against the WooCommerce order table. Anything that drifted silently gets flagged into an admin notice.
- We stopped trusting the
payment.capturedevent as a terminal signal. It isn't. It's a mid-state signal that happens to be the last one the default plugin listens for.
What we didn't fix — and this is the uncomfortable bit — is the settlement reversal case. If Razorpay captures ₹4,680 on Monday, settles it on Wednesday, and then on Thursday reverses it because the risk team put a hold on that merchant category or the acquiring bank flagged a chargeback-adjacent pattern, WooCommerce never finds out. The Razorpay plugin subscribes to payment.* events. The reversal fires under settlement.*, and as far as we can tell from the current webhook event list, there isn't a clean settlement.reversed event you can subscribe to that gives you back the originating payment_id in a form the plugin can map. (We may be wrong about this — the webhook catalogue has shifted at least twice since 2022 and we last audited it properly maybe eight months ago. If someone's got a cleaner subscription that we've missed, we'd genuinely like to know.)
So for the settlement-reversal case, we don't have a programmatic fix. What we have is a Friday-afternoon ritual: pull the week's settlement CSV, diff it against the previous week's, flag anything where a payment_id that appeared as settled last week shows up as reversed this week, and manually mark the corresponding WooCommerce order back to on-hold with a note for the finance team. It's ugly. Takes twenty minutes if nothing's gone wrong, an hour if something has. We've been meaning to automate it for about four months now and it keeps slipping down the backlog because the manual version works and the failure rate is low enough — maybe two or three orders a quarter on the client where we track it most carefully — that nobody feels the pain hard enough to prioritise it.
If you've solved the settlement-reversal webhook subscription cleanly, or if Razorpay has shipped a settlement.processed event with the payment-level breakdown that we've missed, write to us. Until then, Fridays are for CSVs.