Spec a refund endpoint that cannot over-refund

Vibe codingHard30 minStripe style

Your task

Your support tool lets agents refund all or part of a customer's charge. The backend is Python with FastAPI and Postgres, and refunds go out through your payment provider's API. Support agents double-click, the tool retries on timeouts, and 2 agents sometimes work the same ticket.

Finance found 3 charges last quarter that were refunded for more than they were worth. An agent will rebuild POST /charges/{id}/refunds.

Write the spec you would hand the agent.

What you know:

  • charges(id, amount_cents, currency, refunded_cents, status), and a new refunds table you may design
  • the provider's refund call takes an idempotency key, and never refunds twice for the same key
  • the provider call takes up to 10 seconds, and sometimes times out after it has succeeded
  • partial refunds are allowed, and a charge may get several

Then, in a few sentences: how did the 3 over-refunds most likely happen?