A payment bug rarely looks like a bug. It looks like a customer charged twice, an order stuck on “failed” after the money arrived, or a refund total that does not match the gateway. Each one is cheap to test for and expensive to find in production.

This is a checklist of 62 payment gateway test cases in 9 areas. Every case says what to check, what should happen, why it matters and how severe a failure would be. It also says how much of it I have actually automated, because a checklist that blurs “I recommend this” with “I tested this” is worth less than it looks.

Read this first. Everything marked automated comes from one project: an independent Razorpay Test Mode QA project whose demo app I built as the test target. It ran in Test Mode only. No webhook sent by Razorpay itself was observed, and no successful refund was completed against the gateway.

No employer work is described here. Where a case is general, for example currencies with different decimal places, I say so and do not tie it to any project of mine.

1. Why generic checklists miss payment bugs

A typical payment test list is a list of inputs: a valid card, an expired card, a wrong CVV, a declined bank. Those are worth running, and they all test the same moment, the customer pressing Pay.

The expensive failures happen afterwards, between four things that each keep their own record of the payment: the browser, your server, the gateway and your order table. Two independent routes update that record, the browser’s callback and the gateway’s webhook, and either can repeat, arrive late, arrive in the wrong order or never arrive. Almost every serious case below is a way for those records to disagree.

Three habits shaped the list:

  • Assert state, not status codes. A 200 from a webhook handler says little. The order’s status, amount and payment ID afterwards say a lot.
  • Pair every rejection with an acceptance. A handler that rejects everything passes every “bad input is rejected” test. The worked example shows this happening.
  • Test the money arithmetic on its own. Rounding and minor-unit mistakes are invisible in a screenshot of a successful payment.

My earlier article, How to Test a Payment Gateway with Playwright, shows the test code behind several of these cases. This page does not repeat it. It is the wider list, with the reasoning.

2. How to read the checklist

Coverage labels

The last column of every table says which of these a case is:

Automated, runs in CI
A test in the public Razorpay project, in the CI-safe suite, cited by its real ID.
Automated, cannot fail in CI
The test exists, but its assertions only run when order creation succeeds, and the CI placeholder credentials never allow that. Real Test Mode credentials make it run.
Automated, live gateway only
Tagged @razorpay-live. It needs one real captured Test Mode payment, so it is not in CI.
Recommended, not automated
No committed test. Where I ran the case once by hand or in a scratch copy of the app, the row says so and says what happened.
Beyond sandbox
Test Mode cannot prove it. It needs the live gateway, a real bank or real settlement.

Test IDs such as WEB-FIX-001 are tests in the repository, as listed in the coverage matrix on the Evidence page at commit da9e7a2. The PG- IDs are this checklist’s own. Of the 37 repository tests, 33 are cited in the tables. The rest check plumbing such as the health endpoint, page load and unknown routes, or are mentioned only in a note.

Severity

Severity is my own judgement of business impact, not an industry scale. Critical: money is lost or wrongly kept, or an attacker’s input is accepted as true. High: an order or refund ends in the wrong state, or a customer sees an error where money is involved. Medium: confusing or degraded behaviour with limited money impact. Low: hardening, or an information leak with no state change.

Cases at a glance

Number of cases in each area, split by coverage
Area Cases Automated Recommended, not automated Beyond sandbox
Successful payments 5 3 2 0
Declines and failures 5 0 4 1
Signature and webhook validation 12 9 2 1
Duplicates and idempotency 8 3 5 0
Refunds 9 2 6 1
Currency and rounding 6 1 5 0
Timeouts and retries 5 0 4 1
Reconciliation 5 0 4 1
Basic security checks 7 4 3 0
All areas 62 22 35 5

22 of 62 cases are automated, and 35 are recommendations I have not automated. That ratio is the honest shape of this project: a small, deliberately scoped suite, and a longer list of things a payment integration needs.

3. Successful payments

These cases check that the amount, the money and the order agree after a payment that works. The valuable ones ask who decides the amount, and what happens when the browser and the gateway both report success.

Successful payments: 5 cases with expected result, why it matters, severity and my coverage
ID Scenario Expected result Why it matters Severity My coverage
PG-SUC-01 Happy path: the order is created on the server, Checkout is completed and the payment is verified server-side. The order ends paid once, with the payment ID stored and the amount equal to the server's own order amount. The baseline, and the least informative case on this list: nearly every payment bug passes the happy path. Run it to prove the environment works, then move on. High Automated, live gateway only

Tests: SIG-001

SIG-001 verifies one real captured Test Mode payment through the app. The Checkout steps were driven once in a separate Playwright session (Phase 3.3 report) and are not a committed test.

PG-SUC-02 The client sends its own amount or currency when the order is created. The server ignores both and builds the order from its own configuration. If the amount comes from the browser, anyone can pay 1 instead of 500. The payment succeeds, nothing errors and the shop ships. Critical Automated, cannot fail in CI

Tests: ORDER-003, ORDER-001

Both tests assert only when order creation returns 200, which the CI placeholder credentials never produce, so CI cannot fail on this. They run for real with working Test Mode credentials; the Phase 3.3 report records ORDER-003 passing.

PG-SUC-03 The amount shown on the page versus the amount charged. The displayed amount, the order amount and the amount the gateway reports are the same figure in the same currency. Display and charge are computed in different places. A mismatch means the customer approves one price and is charged another, which becomes a dispute, not a bug report. High Automated, live gateway only

Tests: UI-002

UI-002 checks that the page shows the app's fixed amount (500.00 INR). It needs the live Test Mode setup, so it does not run in CI.

PG-SUC-04 The customer refreshes or re-opens the success page after paying. No second order, no second payment record and no second confirmation; the page shows the existing paid order. Refresh and back-button resubmits are normal behaviour. Without a guard they create duplicate orders or repeat fulfilment. Medium Recommended, not automated
PG-SUC-05 The gateway's webhook reaches the server before the browser's verify call, or the other way round. The order ends paid whichever path wins. The second arrival changes nothing, and the customer sees a paid order, not an error. Two independent paths write the same order. If the late one treats already paid as a failure, a successful payment shows an error page and the customer pays again. High Recommended, not automated

In the public project I could only send self-signed webhooks (no webhook from Razorpay itself was ever observed), so the ordering of the two real paths is untested.

Two rows carry the label cannot fail in CI. Their assertions sit inside if (response.status() === 200), and the CI placeholder credentials never produce a 200, so CI passes without checking the amount. I wrote up how I found this in lesson 5 of the earlier article. The rows stay because the behaviour matters. The label says how much my CI protects it.

4. Declines and failures

A decline is easy to test: the gateway says no and the page shows a message. What the order does next is where the bugs are, and it depends on how the gateway models a failed attempt. Read your gateway’s order lifecycle before writing these cases. My own app’s model contradicted the gateway’s documentation, as the earlier article explains.

Declines and failures: 5 cases with expected result, why it matters, severity and my coverage
ID Scenario Expected result Why it matters Severity My coverage
PG-DEC-01 A payment attempt is declined (card, UPI or bank failure) and the customer tries again on the same order. The failed attempt is recorded, the order stays open for another attempt and the customer sees a plain-language message. Razorpay's order documentation has no order-level failed status: an order stays open until a payment is captured. An app that closes the order on the first failure forces a restart and loses sales that would have completed. High Recommended, not automated

A real decline was seen once in Test Mode Checkout (Phase 3.3 report). There is no committed test.

PG-DEC-02 A failed attempt is followed by a successful one for the same order (payment.failed, then payment.captured). The order ends paid. Money has been captured. If the order stays failed, the customer is charged and the shop records no sale: the worst kind of mismatch, found only when the customer complains. Critical Recommended, not automated

This case failed in my scratch copy on 14 October 2026: the app answered 200 to the late payment.captured and left the order failed. The scratch test is not in the repository and I have not changed the public code.

PG-DEC-03 The customer closes Checkout without paying. The order stays created, no payment is recorded and the customer can retry with no stale state. Abandonment is common. Bugs here leave half-open orders, or make the retry reuse state from the abandoned attempt. Medium Recommended, not automated

Close-and-retry was run once by hand in Test Mode Checkout (Phase 3.3 report). The page has no dismiss handler and there is no committed test.

PG-DEC-04 The payment is pending or processing when the customer returns (asynchronous payment methods). The app shows a pending state, marks the order neither paid nor failed, and updates when the final event arrives. Treating pending as failed invites a second payment. Treating it as paid ships goods before the money exists. High Recommended, not automated

I have not tested an asynchronous payment method.

PG-DEC-05 Issuer-side declines: insufficient funds, expired card, wrong CVV, bank downtime, risk blocks. Each maps to a message the customer can act on, with no raw gateway text shown. A generic 'payment failed' drives abandonment. Raw gateway codes confuse customers and help anyone probing the checkout. Medium Beyond sandbox

Test Mode can simulate some failures, but how real issuers and banks respond cannot be proven in a sandbox. I observed one decline.

PG-DEC-02 is the case I would run first on a new integration. It is also the one my own app failed in a scratch check on 14 October 2026: the retry’s payment.captured was acknowledged with a 200 and then ignored, so the order stayed failed while the money was captured.

5. Signature and webhook validation

Signatures are where an integration decides whether to believe a message. Two habits cover most of this area. Verify the exact bytes that arrived, not a rebuilt copy of them. And check the signature before doing anything else with the request, including looking up whether you have seen it before.

Signature and webhook validation: 12 cases with expected result, why it matters, severity and my coverage
ID Scenario Expected result Why it matters Severity My coverage
PG-SIG-01 Payment verification with a valid signature for a real captured payment. Accepted (200, verified: true), with order, payment, amount and status taken from the gateway. Proves the accept path works against the real gateway, not only that bad input is rejected. High Automated, live gateway only

Tests: SIG-001

Needs one real Test Mode payment, so it is excluded from CI.

PG-SIG-02 Payment verification with an invalid signature, including an upper-case or truncated copy of a valid one. Rejected with 401 and the order unchanged. The signature is the only proof that the browser's success message is real. Accepting a near-match lets anyone mark their own order paid. Critical Automated, runs in CI

Tests: SIG-002

SIG-002 covers a wrong signature. The upper-case and truncated variants were run once in my scratch copy and rejected; they are not committed.

PG-SIG-03 A valid signature replayed against a different order ID. Rejected with 401. Proves the signature is bound to the order and payment pair. Without that binding, one cheap paid order could confirm a more expensive one. Critical Automated, runs in CI

Tests: SIG-003

The test computes a genuinely valid signature first, then changes the order ID.

PG-SIG-04 Verification request with a missing field, or a malformed JSON body. 400 with a clear error; never a 500 or a hang. Bad input from a client or a proxy should be a clean refusal. A crash on missing fields is an outage waiting for a retry loop. Medium Automated, runs in CI

Tests: SIG-004, SIG-005, SIG-006, ERR-004

PG-SIG-05 Webhook with a correct signature computed over the exact raw body. Accepted (200), and the order moves from created to paid. This is the case DEF-002 broke: every genuine webhook was rejected while the rejection tests kept passing. See the worked example below. Critical Automated, runs in CI

Tests: WEB-001, WEB-FIX-001

WEB-FIX-001 fails when the DEF-002 fix is reverted (see the Evidence page).

PG-SIG-06 Webhook with a wrong signature. 401, and the order is untouched. Rejection is the security control, but it proves nothing alone: a handler that rejects everything also passes this case. Pair it with the accept path above. Critical Automated, runs in CI

Tests: WEB-002, WEB-FIX-003

PG-SIG-07 Webhook with the signature header missing. 401 naming the missing header. A request that omits the header must not skip verification. A handler that verifies only when a signature is present fails open. High Automated, runs in CI

Tests: WEB-003

PG-SIG-08 Webhook payload changed after signing (one character appended, or the amount edited). 401, and the order stays as it was. Proves the HMAC covers the body, amount included, and not only the headers. A tampered amount that gets through is a free-goods bug. Critical Automated, runs in CI

Tests: WEB-007, WEB-FIX-002

WEB-FIX-002 also asserts the order status is unchanged afterwards.

PG-SIG-09 Webhook signed over bytes that differ from what JSON re-serialisation would produce (pretty-printed body, different key order, escaped characters). Accepted, because the signature is checked against the exact bytes received and never against parsed-and-re-serialised JSON. A handler that verifies JSON.stringify(req.body) passes tests that build their payload with JSON.stringify and rejects real traffic whose formatting differs. It looks fine in staging and refuses genuine webhooks in production. High Recommended, not automated

A gap in my own suite: its webhook tests all build the body with JSON.stringify, so they cannot tell raw-body verification from re-serialised verification.

PG-SIG-10 Webhook with the event ID header missing. 400 naming the missing header. Deduplication depends on that ID. Accepting events without it makes duplicates undetectable. Medium Automated, runs in CI

Tests: WEB-004

PG-SIG-11 Replay of an already-processed event ID with a bad signature. 401, the same as any other badly signed request. If the duplicate check runs before the signature check, anyone who knows or guesses an event ID gets a 200 and learns the ID exists. Verify first, then deduplicate. Low Recommended, not automated

Found in my scratch copy on 14 October 2026: the handler returns 200. Not committed; I have not changed the public code.

PG-SIG-12 The webhook secret is configured per environment: production differs from test and matches the dashboard. Genuine webhooks verify in each environment. A secret copied from the wrong environment rejects every genuine webhook. Nothing errors loudly; events are quietly refused until reconciliation notices. High Beyond sandbox

Needs the real dashboard webhook configuration. No webhook ever arrived from Razorpay in this project, so this was not exercised.

Read these rows as pairs. PG-SIG-05 (accept a genuine webhook) is the partner of PG-SIG-06 to PG-SIG-08 (reject bad ones). Without the first, the other three prove nothing. PG-SIG-09 is where my own suite is weakest: its payloads are all produced by JSON.stringify, which is also what a re-serialising handler would produce, so the suite cannot tell the two implementations apart.

6. Duplicates and idempotency

Treat duplicates and reordering as normal operating conditions. Gateways redeliver, browsers resubmit and people double-click, and Razorpay’s webhook documentation says an endpoint might receive the same event more than once and that events may not arrive in order.

Duplicates and idempotency: 8 cases with expected result, why it matters, severity and my coverage
ID Scenario Expected result Why it matters Severity My coverage
PG-DUP-01 The same webhook event ID is delivered twice. Applied once. The second delivery gets 200 already processed and the order is unchanged. Gateways redeliver when an acknowledgement is slow or lost, and Razorpay's webhook documentation says an endpoint might receive the same event more than once. A non-idempotent handler repeats fulfilment, emails or ledger entries. High Automated, runs in CI

Tests: WEB-005, WEB-FIX-004

The test sends both deliveries itself, one after the other. No redelivery from Razorpay was observed.

PG-DUP-02 Different event IDs for different events. Each is processed independently. Deduplication keyed too coarsely (on order or payment ID) silently drops genuine events, for example the refund that follows the payment. Medium Automated, runs in CI

Tests: WEB-006

PG-DUP-03 Client-side verification is called twice for the same payment. Both calls succeed, the order stays paid with the same payment ID and nothing is duplicated. Browsers retry and users double-submit. The second call must be harmless: not an error and not a second state change. High Automated, live gateway only

Tests: REPLAY-001

Needs the one real captured payment, so it is excluded from CI.

PG-DUP-04 Double-click on Pay, or the create-order request is sent twice. One order, or a defined rule for reusing the open order. Which of two orders the customer ends up paying decides what the reconciliation shows. Duplicate orders turn one purchase into two records that finance must match by hand. High Recommended, not automated

In my app, create-order builds a new order on every call (read in the source; I did not run a double-click test), so this probably exposes a real question.

PG-DUP-05 The verify path and the webhook path both report the same payment. Side effects (confirmation email, fulfilment, ledger entry) happen once in total, not once per path. Event-ID deduplication does not help here: the browser callback has no event ID, and the two paths carry different identifiers. Customers get two emails, or two shipments. High Recommended, not automated
PG-DUP-06 Deduplication state after a restart, a deploy or a second server instance. Already-processed event IDs are still recognised. An in-memory set forgets on deploy and is not shared between instances, so redeliveries after a deploy are applied a second time. High Recommended, not automated

My app stores processed event IDs in SQLite, so they should survive a restart, but no test restarts the server.

PG-DUP-07 Out-of-order events: payment.authorized arrives after payment.captured. A paid order does not move backwards. Razorpay's documentation says events may not arrive in order. A late, older event must not overwrite a more advanced state. High Recommended, not automated

Behaved as intended in my scratch checks on 14 October 2026. The state machine implements it, but no committed test covers it.

PG-DUP-08 Several copies of the same event arrive at the same moment. Applied once, with no error and no second record. Check-then-insert deduplication is correct when requests arrive one after another and can fail when they arrive together, which is how gateway retries often arrive. High Recommended, not automated

WEB-005 sends its two deliveries one after the other, so it cannot expose a race. Not covered.

Event-ID deduplication answers one question: have I seen this exact event before? It does not answer whether two different messages mean the same thing, which is what PG-DUP-05 and PG-DUP-07 ask, and it does not help when copies arrive together (PG-DUP-08).

7. Refunds

Refunds run the payment machinery in reverse and add arithmetic: the order’s refunded total has to be right after one refund, several refunds, repeated events and rejected attempts.

Refunds: 9 cases with expected result, why it matters, severity and my coverage
ID Scenario Expected result Why it matters Severity My coverage
PG-REF-01 Refund request without a payment ID. 400 Missing required field, naming paymentId. A missing ID should be refused by the app, not discovered by a failing gateway call. Low Automated, runs in CI

Tests: REF-001

PG-REF-02 The gateway rejects a refund (unknown payment, ineligible state). A controlled 400 or 404 with a sanitised message, and the server keeps serving other requests. DEF-001: the error handler read error.message, which the gateway SDK does not set, so the handler itself threw and took the process down. One bad refund request was an outage. High Automated, runs in CI

Tests: REF-ERR-001, REF-ERR-002

REF-ERR-002 asserts that an unrelated GET /health still returns 200 afterwards; that liveness check is the regression assertion.

PG-REF-03 Full refund of a paid order. The order moves from paid to refunded, with the amount and refund ID recorded. Refund state is what finance reads. If it does not change, the order looks sold while the money has gone back. High Recommended, not automated

The transition is implemented, and a full-amount refund.created webhook moved a paid order to refunded in my scratch checks. There is no committed test, and no successful refund was completed against Razorpay.

PG-REF-04 Two partial refunds that together equal the order amount. The refunded total is tracked, and the order reaches a fully refunded state when the sum equals the amount. Logic that checks only whether a single refund equals the order amount never fires for partial refunds. The order keeps saying paid after the full amount has gone back. High Recommended, not automated

Failed in my scratch copy on 14 October 2026: two refunds of 25000 on a 50000 order left the order paid. I prototyped a fix there; nothing is applied to the public repository.

PG-REF-05 A refund larger than the remaining balance (for example 30000 twice against a 50000 payment). Rejected before it reaches the gateway, or the gateway's rejection is handled; the recorded refunded total never exceeds the amount captured. Gateways usually enforce the limit, but your own ledger is what support and finance read. A refunded total above the payment is either a loss or a ledger nobody can trust. Critical Recommended, not automated

One excessive refund amount was checked by hand after the DEF-001 fix and returned a controlled 400 (docs/DEFECTS.md). The cumulative case, which is the one that matters, is not tested.

PG-REF-06 The same refund event is delivered twice. Recorded and counted once. A duplicate refund event that adds to a running total shows the customer as refunded twice. High Recommended, not automated
PG-REF-07 Refund against an order that was never paid, has failed, or is already refunded. Refused; only paid can move to refunded. Refunding an order that was never paid sends out money that was never taken. High Recommended, not automated

Implemented in the state machine (paid is the only state that can move to refunded). No committed test exercises the transition.

PG-REF-08 Refund amount edge cases: zero, negative, non-numeric, more than two decimal places, or a value in the wrong unit. 400 with a clear message, and nothing is sent to the gateway. Amounts in minor units invite unit mistakes: a refund of 500 meant as rupees is 5.00. Medium Recommended, not automated
PG-REF-09 A successful refund end to end against the gateway, including the pending-then-processed status. The gateway confirms the refund, a webhook or status lookup updates the order and the customer-visible amount matches. The only way to know the refund path works with real gateway behaviour and timing. High Beyond sandbox

Not demonstrated. The Test Mode account had an account-level restriction that blocked refunds, confirmed outside the app with raw HTTPS calls. The route, its validation and its error handling are tested; a live successful refund is not.

The picture in my own project is lopsided. The rejection path (DEF-001) is tested and the success path is not, because the Test Mode account’s restriction blocked every refund. The partial-refund row records a failure I found in a scratch copy of the app. The earlier article lists it with the other scratch findings (section 7).

8. Currency and rounding

Money-arithmetic bugs are small per order and invisible in a screenshot. They show up weeks later as reconciliation differences nobody can explain. My demo app sells one item at a fixed INR amount, so it has no conversion or rounding logic to test. These are general cases, written from how amounts are usually handled, and they are not attributed to any project of mine.

A gateway that takes amounts in the smallest currency unit (Razorpay’s 50000 for 500.00 INR) turns every price conversion into a place for this bug:

19.99 * 100              // 1998.9999999999998
Math.floor(19.99 * 100)  // 1998, one minor unit short
Math.round(19.99 * 100)  // 1999

Run in Node. Use integer or decimal arithmetic, or a deliberate round. Never truncate a float.

Currency and rounding: 6 cases with expected result, why it matters, severity and my coverage
ID Scenario Expected result Why it matters Severity My coverage
PG-CUR-01 The amount sent to the gateway is in minor units. 500.00 INR is sent as 50000 (paise), and the response and the order record carry the same integer. Sending 500 instead of 50000 charges a hundredth of the price, and nobody notices until revenue falls short. Critical Automated, cannot fail in CI

Tests: ORDER-001, UI-002

ORDER-001 asserts 50000 and INR only when order creation succeeds, so it cannot fail in CI. UI-002 needs the live Test Mode setup. The app has one fixed INR amount, so there is no conversion logic to test.

PG-CUR-02 Currencies with 0 or 3 decimal places in a multi-currency checkout (for example JPY and KWD). Conversion uses each currency's own exponent: 500 JPY is sent as 500, not 50000, and 1.500 KWD as 1500. Multiplying by 100 for every currency overcharges zero-decimal currencies 100 times and undercharges three-decimal ones tenfold. Checks on INR alone never show it. Confirm in the gateway's documentation how each currency is encoded. Critical Recommended, not automated

A general scenario. My demo app is INR-only and has no conversion to test, and I do not attribute this case to any employer project.

PG-CUR-03 Floating-point conversion to minor units (19.99 x 100). 1999, using integer or decimal arithmetic or a deliberate round, never truncation of a float. In JavaScript, 19.99 * 100 is 1998.9999999999998. Truncating gives 1998, one minor unit short. Small per order, large across thousands, and it shows up as unexplained reconciliation differences. High Recommended, not automated

I checked the arithmetic in Node. The demo app uses a fixed integer amount, so it has no conversion to test.

PG-CUR-04 Discounts, tax and fees on a multi-line cart. The sum of the rounded line amounts equals the rounded total under one documented rounding mode, and the gateway receives the same total the invoice shows. Rounding each line, or only the total, gives totals that differ by a minor unit. Receipts, invoices and the gateway then disagree by small amounts that finance has to explain by hand. Medium Recommended, not automated
PG-CUR-05 A webhook or refund in a different currency from the order. Not applied; flagged for review. An amount in the wrong currency compared numerically looks valid. 500 USD is not 500 INR. High Recommended, not automated
PG-CUR-06 A correctly signed event whose amount differs from the order amount. Not accepted as a full payment; flagged. A valid signature proves who sent the event, not that the amount is right. A short payment accepted as complete ships a full order for part of the price. High Recommended, not automated

In the source I read at da9e7a2 (not executed), the webhook handler moves the order on without comparing the event amount to the order amount. The client verify route does compare them.

9. Timeouts and retries

A timeout is the moment your app does not know what happened. These cases ask what it tells the customer then, and what it does with the answer when it finally arrives. The main hazard is a customer who retries because they were told “failed” about a payment that went through.

Timeouts and retries: 5 cases with expected result, why it matters, severity and my coverage
ID Scenario Expected result Why it matters Severity My coverage
PG-TMO-01 Timeout or dropped connection after the gateway captured the payment (browser closed, network cut, slow verify call). The order still ends paid through the webhook or a status lookup, and the customer is told the payment is being confirmed, not that it failed. The costliest timing bug: the customer sees an error, pays again and is charged twice for one order. Critical Recommended, not automated

Not covered by any test in the public project.

PG-TMO-02 The gateway call fails or times out when the order is created. The customer gets a controlled error and can retry; no order is left looking paid and no partial state is stored. Gateway outages happen. The app must fail visibly and recoverably, not leave an order the customer cannot pay. High Recommended, not automated

ORDER-002 checks that a failed order creation returns a sanitised error. It does not simulate a timeout.

PG-TMO-03 The webhook handler responds slowly or with a 5xx. Redelivered events are applied once, and the handler acknowledges quickly and keeps slow work out of the request. Gateways generally treat a slow or failed response as a failed delivery and send it again; check your gateway's policy. The retry then arrives while the first attempt is still running. High Recommended, not automated

Razorpay's real retry schedule was never observed in this project.

PG-TMO-04 Retry storm: dozens of redeliveries of the same events in a burst. Each event is applied once, valid events see no errors and response time stays well inside the gateway's timeout. After an outage a gateway can replay a backlog at once. A handler that is correct one request at a time can still lock the database or time out under the burst, which causes more retries. Medium Recommended, not automated

A small replay burst against your own sandbox, not load testing; see the scope section.

PG-TMO-05 The gateway's own redelivery schedule, ordering and expiry. Matches the gateway's documentation. Handlers are designed around assumptions about retries and order. Wrong assumptions only show against the real service. Medium Beyond sandbox

No webhook sent by Razorpay itself was observed in this project, so none of this was tested against real behaviour.

10. Reconciliation

Everything above tries to keep the order and the gateway in agreement. Reconciliation checks that they actually agree, because some disagreement always gets through: a lost webhook, a rounding difference, an order marked paid in error. These cases need a scheduled job or a report more than a test. The public Razorpay project has no reconciliation job.

Reconciliation: 5 cases with expected result, why it matters, severity and my coverage
ID Scenario Expected result Why it matters Severity My coverage
PG-REC-01 Every order marked paid has a captured payment at the gateway with the same amount and currency. Zero mismatches, or each mismatch listed for follow-up. The one control that catches a missed webhook, a wrong amount accepted earlier, or an order marked paid by mistake. Critical Recommended, not automated

The public project has no reconciliation job.

PG-REC-02 Every captured payment at the gateway maps to an order that is paid (the reverse direction). No captured payment whose order is failed, created or missing. Catches money taken for orders the app thinks failed (see the failed-then-captured case above) and payments with no order at all. Critical Recommended, not automated
PG-REC-03 Refund totals: local refund records versus the gateway's refunds, per payment. Equal for every payment. Refunds are the usual source of drift: partial refunds, retries, and events that arrived twice or not at all. High Recommended, not automated
PG-REC-04 The webhook endpoint is down while a payment completes, then restored. The missed events are recovered by polling or a status lookup, and no order stays created while the gateway shows it captured. A gateway stops redelivering at some point. After that, only your own reconciliation finds the gap. High Recommended, not automated
PG-REC-05 Settlement and payout totals against orders, refunds and fees. The payout equals captured amounts less refunds and fees for the period. Orders, gateway records and the bank statement are three ledgers, and only the third is money. High Beyond sandbox

Test Mode does not exercise settlement or reconciliation, so this cannot be shown in a sandbox.

11. Basic security checks

These are checks you can run against your own app and sandbox by reading what it returns: configuration responses, page source, error bodies and which routes answer. Nothing here needs probing anyone else’s system, and none of it replaces a security review or a penetration test.

Basic security checks: 7 cases with expected result, why it matters, severity and my coverage
ID Scenario Expected result Why it matters Severity My coverage
PG-SEC-01 The public configuration endpoint. Returns only publishable values (key ID, currency, a configured flag) and never the key secret or the webhook secret. A secret in a public response is a full compromise of the gateway account. Critical Automated, runs in CI

Tests: CONFIG-001, CONFIG-002

PG-SEC-02 The checkout page's HTML. Contains no secret keys or webhook secret, and loads the Checkout script from the gateway's own origin. Anyone who views the source copies a secret in it. A look-alike script source is how payment pages get skimmed. High Automated, runs in CI

Tests: UI-003, UI-004

UI-003 checks that a script tag pointing at checkout.razorpay.com exists and that the HTML has no live key or secret strings.

PG-SEC-03 Test and live key modes are not mixed. Test environments show only test keys and a visible Test Mode indicator. A live key in staging moves real money during testing. A test key in production fails every payment. High Automated, runs in CI

Tests: CONFIG-003, UI-005

CONFIG-002 also asserts that the returned key ID is a test key.

PG-SEC-04 Error responses from the payment endpoints. Human-readable, with no keys, URLs, stack traces or SDK internals. Verbose errors show attackers what the server uses, and show customers things they cannot act on. Medium Automated, runs in CI

Tests: ERR-001, ERR-002, REF-ERR-001

PG-SEC-05 Debug or admin routes, for example listing or clearing processed webhook events. Not reachable without authentication in any shared environment. An unauthenticated route that clears the deduplication ledger lets anyone make the next replay count as new. High Recommended, not automated

Found in my scratch copy on 14 October 2026: DELETE /api/webhooks/events cleared the processed event IDs without credentials. Not committed; I have not changed the public code.

PG-SEC-06 How the signature is compared. A constant-time comparison (for example crypto.timingSafeEqual) after a length check. A hardening practice for comparing secrets. The limit matters: I measured no timing difference in my app, so this is a precaution, not a bug I proved. Low Recommended, not automated

Both HMAC checks in my app compare with ===. A hardening idea only.

PG-SEC-07 Ownership of orders and payments: user A reads or verifies user B's order. Refused. Order and payment IDs are not secrets. Without an ownership check, enumerating IDs exposes other customers' orders. High Recommended, not automated

My demo app has no user accounts or authentication, so it cannot exercise this. A general scenario.

12. Worked example: DEF-002

DEF-002 shows why the cases above come in pairs. The full report, with the source excerpts, is on the Evidence page. In short: webhook signature validation could never succeed. It was found on 14 September 2026 during real Test Mode execution, rated High, and fixed the same day. The defect was in the demo app I built as the test target, so it is a bug in my own code and not in Razorpay’s product.

What I saw

A webhook with a provably correct signature returned 401 every time. I computed the HMAC exactly as the handler does, sent the exact raw body once with fetch() and once with curl --data-binary from a byte-identical file, and got the same 401. That ruled out the client and the comparison logic.

Why the tests did not notice

When I reverted the fix in a scratch copy on 15 October 2026, 6 of the 11 webhook tests failed: WEB-001, WEB-005, WEB-006, WEB-007, WEB-FIX-001 and WEB-FIX-004. The 5 that still passed were the rejection-only ones: WEB-002, WEB-003, WEB-004, WEB-FIX-002 and WEB-FIX-003. A handler that rejects everything keeps the rejection-only tests green, which is why the defect could hide.

Root cause and fix

A global express.json() parser was mounted before the webhook route. It consumed and parsed the body, so the route’s own express.raw() received an object instead of a Buffer. Converting that object to a string gives "[object Object]", and the HMAC was computed over that instead of the real payload. The comparison was correct. It was hashing the wrong bytes. The fix was to mount the webhook router first:

// src/app.js (excerpt)
app.use('/api/webhooks', webhooksRouter);

// Middleware
app.use(express.json());

The fixed mount order in the repository at commit da9e7a2.

The impact was bounded. No correctly signed webhook could be accepted, but a forged one could not get through either: the defect failed safe, so it was a functional defect and not a security hole.

What it teaches, and which cases it maps to

  • Accept path first. PG-SIG-05 is the case that would have caught it on day one. PG-SIG-06 to PG-SIG-08 are the rejection cases that kept passing.
  • Isolate the cryptography. Building a valid signature by hand and watching it fail moved suspicion from the HMAC to what the route received.
  • Middleware order is part of the verification design. Anything that touches the body before the check can change the bytes.
  • A neighbouring gap remains. The regression tests build every payload with JSON.stringify. PG-SIG-09 is the case they cannot cover, and I have not added it.

The limits apply here too. Every webhook in these tests is self-signed by the test. A webhook sent by Razorpay itself never reached the app, so DEF-002 was found and fixed against simulated deliveries.

13. What this checklist does not cover

  • PCI DSS scope. How card data is handled, stored or tokenised, and what your compliance obligations are. The cases here assume a hosted checkout and do not assess compliance.
  • Fraud and risk tooling. Velocity rules, scoring services and manual review queues.
  • Live-gateway behaviour. Live keys, real issuing banks and card networks, real webhook delivery and settlement. The rows marked Beyond sandbox are the visible edge of this.
  • 3D Secure and other bank-side flows. Authentication challenges, OTPs and bank redirects. I have not tested them. I saw one decline and one cancel-and-retry in Test Mode Checkout, and nothing else.
  • Load and performance. The retry-storm case is a small replay burst against your own sandbox, not a load test.
  • Chargebacks and disputes, subscriptions and saved cards, wallets, mobile SDKs, tax and invoicing. Each needs its own list.
  • Other gateways. Event names, retry behaviour, amount encoding and status models differ between providers. Check your gateway’s documentation before treating a row as a requirement.

This is a testing checklist. It is not a security assessment, a compliance review or a guarantee about any particular integration.

14. Download the checklist

The same 62 cases are available as a CSV with the same IDs and wording, plus an area column and the repository test IDs. It opens in any spreadsheet.

Download the CSV (payment-gateway-test-cases-checklist.csv)

The tables on this page and the CSV are generated together from one source file, so the IDs, wording and coverage labels cannot differ between them.