CommunityCoding & Developmentgithub.com

payments-code-review

Reviews Java or Kotlin payment code (Spring Boot, Kafka, JPA) for bugs that lose or duplicate money - double charges from missing idempotency keys, amounts in double/float, lost events from dual writes, non-idempotent consumers, self-approval, missing timeouts, card data in logs. Runs a bundled scanner, verifies each finding in the code, then walks a manual checklist. Use when reviewing a pull request or service that creates, moves, approves, books or reconciles payments, transfers, refunds, ledgers or balances.

What is payments-code-review?

payments-code-review is a Claude Code agent skill that reviews Java or Kotlin payment code (Spring Boot, Kafka, JPA) for bugs that lose or duplicate money - double charges from missing idempotency keys, amounts in double/float, lost events from dual writes, non-idempotent consumers, self-approval, missing timeouts, card data in logs. Runs a bundled scanner, verifies each finding in the code, then walks a manual checklist. Use when reviewing a pull request or service that creates, moves, approves, books or reconciles payments, transfers, refunds, ledgers or balances.

Works with~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Vidhidesai12/payments-review-skill/tree/main/payments-code-review

Installed? Explore more Coding & Development skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Documentation

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

  1. 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).

  2. 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 processing
    

    Needs 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.

  3. Verify every finding by reading the code. For each lead, open the file and confirm it:

    • A double named amount that 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.
  4. 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.

  5. 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-Key header, 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.

Related Skills