Cheat sheet · Business processes
Refunds and chargebacks
The problem
A shop gives money back in two ways: it refunds on its own, in full or in part, or the cardholder's bank takes the money back through a chargeback. Both look like "minus some amount", and both break in the same places: an edited payment row, a click sent twice, two agents refunding at once, a status that only arrives later by webhook, and a dispute deadline nobody watched.
What you learn
- Why a refund is its own record and its own ledger entry, and the original payment is never edited
- How an idempotency key and a conditional update stop a refund from being paid twice or above what was captured
- Refund statuses that finish asynchronously: pending, succeeded, failed, and webhooks that arrive twice or out of order
- The chargeback lifecycle: dispute opened, funds held, evidence before the deadline, won or lost, and the daily match against the provider's report
Diagram as code
The lesson's final design as text: paste it into Jira, GitLab, GitHub, Notion or your docs, where Mermaid renders by itself. There are D2 and PlantUML (Confluence, IntelliJ) versions too.
Mermaid: flowchart
flowchart LR
n_support(["Support agent"])
n_api["Refund service"]
n_db[("Payments DB")]
n_provider>"Card provider"]
n_support2(["Second agent"])
n_issuer>"Card issuer"]
n_recon("Daily match")
n_support -->|"call"| n_api
n_api --> n_db
n_api -->|"call"| n_provider
n_support2 -->|"call"| n_api
n_provider -.->|"async"| n_api
n_issuer -->|"async"| n_provider
n_recon --> n_provider
n_recon --> n_dbMermaid: request sequence
sequenceDiagram
participant n_api as Refund service
participant n_db as Payments DB
participant n_provider as Card provider
participant n_issuer as Card issuer
participant n_recon as Daily match
Note over n_api,n_db: A paid order and a return
n_api->>n_db: SELECT id, status, captured_minor FROM payments WHERE id = 'pay_7731'#59;
n_db-->>n_api: pay_7731 #124; captured #124; 450000
Note over n_api,n_db: The refund is written over the payment
n_api->>n_db: UPDATE payments
Note over n_api,n_db: A refund is a new record and a new entry
n_api->>n_db: BEGIN#59;
Note over n_api,n_provider: A timeout and a second click
n_api->>n_provider: 14:02:10.0 POST /v1/refunds payment=pay_7731 amount=150000
Note over n_api,n_provider: The refund id is the idempotency key
n_api->>n_provider: POST /v1/refunds HTTP/1.1
n_provider-->>n_api: HTTP/1.1 200 OK
Note over n_api,n_db: Two agents refund at the same time
n_api->>n_db: captured 450000, already refunded 150000, left 300000
Note over n_api,n_db: Check and reserve in one statement
n_api->>n_db: UPDATE payments
n_db-->>n_api: agent A: UPDATE 1 refunded_minor = 350000
Note over n_provider,n_api: The provider answers later
n_provider->>n_api: POST /webhooks/provider HTTP/1.1
n_api-->>n_provider: HTTP/1.1 200 OK (stored, applied in 40 ms)
Note over n_issuer,n_provider: The customer's bank takes the money back
n_issuer->>n_provider: dispute.created dp_3307
Note over n_api,n_db: Hold the money, answer before the deadline
n_api->>n_db: BEGIN#59; -- dispute.created dp_3307
Note over n_recon,n_db: Match against the provider's report every day
n_recon->>n_db: 06:00 provider report 2026-11-18: 412 refunds, 9 disputesD2
direction: right
n_support: "Support agent" {
shape: rectangle
}
n_api: "Refund service" {
shape: rectangle
}
n_db: "Payments DB" {
shape: cylinder
}
n_provider: "Card provider" {
shape: cloud
}
n_support2: "Second agent" {
shape: rectangle
}
n_issuer: "Card issuer" {
shape: cloud
}
n_recon: "Daily match" {
shape: rectangle
style.multiple: true
}
n_support -> n_api: "call"
n_api -> n_db
n_api -> n_provider: "call"
n_support2 -> n_api: "call"
n_provider -> n_api: "async" {
style.stroke-dash: 3
}
n_issuer -> n_provider: "async"
n_recon -> n_provider
n_recon -> n_dbPlantUML: request sequence
@startuml
participant "Refund service" as n_api
database "Payments DB" as n_db
boundary "Card provider" as n_provider
boundary "Card issuer" as n_issuer
participant "Daily match" as n_recon
note over n_api, n_db : A paid order and a return
n_api -> n_db : SELECT id, status, captured_minor FROM payments WHERE id = 'pay_7731';
n_db --> n_api : pay_7731 | captured | 450000
note over n_api, n_db : The refund is written over the payment
n_api -> n_db : UPDATE payments
note over n_api, n_db : A refund is a new record and a new entry
n_api -> n_db : BEGIN;
note over n_api, n_provider : A timeout and a second click
n_api -> n_provider : [duplicate] 14:02:10.0 POST /v1/refunds payment=pay_7731 amount=150000
note over n_api, n_provider : The refund id is the idempotency key
n_api -> n_provider : POST /v1/refunds HTTP/1.1
n_provider --> n_api : HTTP/1.1 200 OK
note over n_api, n_db : Two agents refund at the same time
n_api -> n_db : captured 450000, already refunded 150000, left 300000
note over n_api, n_db : Check and reserve in one statement
n_api -> n_db : UPDATE payments
n_db --> n_api : agent A: UPDATE 1 refunded_minor = 350000
note over n_provider, n_api : The provider answers later
n_provider ->> n_api : POST /webhooks/provider HTTP/1.1
n_api -->> n_provider : HTTP/1.1 200 OK (stored, applied in 40 ms)
note over n_issuer, n_provider : The customer's bank takes the money back
n_issuer ->> n_provider : dispute.created dp_3307
note over n_api, n_db : Hold the money, answer before the deadline
n_api -> n_db : BEGIN; -- dispute.created dp_3307
note over n_recon, n_db : Match against the provider's report every day
n_recon -> n_db : 06:00 provider report 2026-11-18: 412 refunds, 9 disputes
@endumlPlantUML: components
@startuml
left to right direction
agent "Support agent" as n_support
component "Refund service" as n_api
database "Payments DB" as n_db
cloud "Card provider" as n_provider
agent "Second agent" as n_support2
cloud "Card issuer" as n_issuer
collections "Daily match" as n_recon
n_support --> n_api : call
n_api --> n_db
n_api --> n_provider : call
n_support2 --> n_api : call
n_provider ..> n_api : async
n_issuer --> n_provider : async
n_recon --> n_provider
n_recon --> n_db
@endumlRecap
Six rules for giving money back.
1) A refund is a new row and a new ledger entry; the payment that happened is never edited. 2) The refund row's id is the idempotency key for every call to the provider. 3) Check the limit and reserve the amount in one conditional update or under a row lock: pending plus succeeded must never exceed captured. 4) Refunds finish asynchronously; take the final status from signed webhooks, only forward, and ask the provider about the ones that stay pending. 5) A chargeback has a deadline: hold the money, answer with evidence in time, and do not refund a disputed payment. 6) Match refunds and disputes against the provider's report every day.
Numbers: at the start and at the end
| Metric | Start | End |
|---|---|---|
| Refunds paid twice | 0/mo | 0/mo |
| Refunds above captured | 0/mo | 0/mo |
| Refunds with a wrong status | 0 | 0 |
| Chargebacks lost | 0% | 24% |
| Report lines that differ | 0 | 0 |
Steps
- Case A paid order and a return
Order
ord_5120was paid by card: 4 500.00, stored as450000minor units. - Problem The refund is written over the payment
The first version simply lowers the captured amount and changes the status.
- Fix A refund is a new record and a new entry
A refund gets its own row with its own id, amount, reason and status, and a ledger entry with opposite postings that points at it.
- Problem A timeout and a second click
The provider is slow and the request times out after 10 s.
- Fix The refund id is the idempotency key
The service first saves the refund row
rf_2208, then calls the provider withIdempotency-Key: rf_2208. - Problem Two agents refund at the same time
After the first refund, 300000 is left.
- Fix Check and reserve in one statement
The payment keeps a
refunded_minorcounter. - Fix The provider answers later
The provider accepted
re_51Aaspending. - Problem The customer's bank takes the money back
Another customer tells their bank the goods never arrived.
- Fix Hold the money, answer before the deadline
The dispute gets its own row and status:
needs_response,under_review, thenwonorlost. - Fix Match against the provider's report every day
Each morning a job loads the provider's report of refunds and disputes and matches every line by the provider's id.
- Recap Recap
Six rules for giving money back.
Terms
- Partial refund
- Giving back part of a captured amount. The original payment is not edited: it is a separate row and a separate ledger entry, and all refunds together must not exceed what was captured.
- Chargeback
- A payment taken back by the cardholder's bank after a dispute. The money leaves the merchant at once; it can only be won back with evidence before the deadline.
- Evidence deadline
- The last moment a merchant can answer a chargeback. After it the dispute is lost by default.
- Refund reservation
- The refund amount is added to the payment's refunded counter before the provider is called, in one conditional update together with the limit check. If the refund fails, the amount is released.