mufassall

Cheat sheet · Business processes

Refunds and chargebacks

14 min · Intermediate · mufassall.dtwin.uz/en/l/refunds-and-chargebacks/

← Open the lesson

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
Final scene

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_db

Mermaid: 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 disputes

D2

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_db

PlantUML: 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
@enduml

PlantUML: 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
@enduml

Recap

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

MetricStartEnd
Refunds paid twice0/mo0/mo
Refunds above captured0/mo0/mo
Refunds with a wrong status00
Chargebacks lost0%24%
Report lines that differ00

Steps

  1. Case A paid order and a return

    Order ord_5120 was paid by card: 4 500.00, stored as 450000 minor units.

  2. Problem The refund is written over the payment

    The first version simply lowers the captured amount and changes the status.

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

  4. Problem A timeout and a second click

    The provider is slow and the request times out after 10 s.

  5. Fix The refund id is the idempotency key

    The service first saves the refund row rf_2208, then calls the provider with Idempotency-Key: rf_2208.

  6. Problem Two agents refund at the same time

    After the first refund, 300000 is left.

  7. Fix Check and reserve in one statement

    The payment keeps a refunded_minor counter.

  8. Fix The provider answers later

    The provider accepted re_51A as pending.

  9. Problem The customer's bank takes the money back

    Another customer tells their bank the goods never arrived.

  10. Fix Hold the money, answer before the deadline

    The dispute gets its own row and status: needs_response, under_review, then won or lost.

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

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