Payments code review
Find the bugs that cost real money in payment code, and explain each one in terms of money: who is charged twice, which booking is lost, who can approve their own transfer.
Workflow
-
Scope it. Find the code that creates, moves, approves, books or reconciles money: controllers, services, listeners, entities, migrations. Note the stack (Spring Boot, Kafka, JPA, Kotlin).
-
Run the scanner from this skill's folder against the project or the changed files:
python scripts/scan.py <path-to-code> # markdown table python scripts/scan.py <path-to-code> --format json # for further processingNeeds Python 3.10+, nothing else. It skips test sources unless you pass
--include-tests. It reads source text with heuristics, so its output is a list of leads. -
Verify every finding by reading the code. For each lead, open the file and confirm it:
- A
doublenamedamountthat is really a percentage or a ratio is not PAY001. - A consumer or approval method is fine if the duplicate or four-eyes check lives deeper than the scanner follows (three calls). Follow it and say where it is.
- Drop false positives, and say in one line why, so the reader can trust the rest.
- A
-
Walk the manual checklist in references/checklist.md. It explains each scanner rule with a bad and a good example, and lists what no scanner can see: races on balances, idempotency key scope, retry plus timeout semantics, state machines, reconciliation, money in transit, audit, and data protection. Only go as deep as the code under review needs.
-
Write the report in the format below. Lead with the highest money impact.
Report format
## Payments review: <service or PR>
**Verdict:** <one sentence: safe to merge / fix before merge / needs redesign>
| # | Severity | Where | Problem | Money impact |
|---|---|---|---|---|
| 1 | High | `TransferController.java:24` | No idempotency key on POST /transfers | A client retry after a timeout creates a second transfer |
### 1. <title>
**Why it matters:** <what goes wrong, concretely, with an example amount>
**Fix:** <smallest correct change, with a short code snippet>
### Checked and fine
- <things verified as correct, with where; keeps the review honest>
### Not covered
- <what you could not check, e.g. database constraints not in this repo>
Rules for the review
- Severity is about money. High = money can be lost, duplicated or moved by the wrong person. Medium = it can happen under failure or load. Low = hygiene.
- Quote the line, with
file:line, for every finding. Never report a scanner lead you did not confirm. - Prefer the smallest safe fix, for example a unique constraint plus an
Idempotency-Keyheader, not a rewrite. When the right fix is structural (a transactional outbox), say so plainly. - Don't claim compliance. This review is not a PCI DSS or SOX audit; say so if asked.
- Check the database too. Many of these guarantees belong in constraints (
UNIQUE,CHECK, triggers). Look at migrations (Flyway, Liquibase) when they are in the repository.