Dispute lifecycle

Four stages

1. Pre-dispute / RFI — the issuer asks for information before raising a formal chargeback. Funds are not moved. Statuses: rfi_open, rfi_responded, rfi_expired.
2. Dispute received — the formal chargeback. The disputed amount and a per-scheme processing fee are debited immediately. Status: evidence_required.
3. Defense / outcome — the merchant accepts, challenges with compelling evidence, or lets the window expire. Statuses: under_review, won, lost, accepted, expired, canceled, resolved.
4. Arbitration (optional, after a Stage-2 loss) — the merchant escalates the case to the scheme for a binding ruling. A steep filing fee applies. Statuses: arbitration_under_review, arbitration_won, arbitration_lost.

Status names match the values stored on the Dispute entity — what you see in the portal, the API, and the database are the same strings.

Reason codes

The generator emits a representative subset of Visa (10.x, 13.x) and Mastercard (48xx) codes — enough to exercise distinct evidence patterns without becoming a full compliance manual. Each dispute carries the raw scheme code plus a normalised category(fraud, consumer, processing_error, authorization).

4870 is a chip-liability-shift case; scheme documentation classifies it under fraud, but the generator emits it as authorization because the dispute hinges on the authorisation path, not on cardholder fraud. Mind the difference if you join on category.

Response windows

The defense window — how long the merchant has to respond before the dispute auto-expires — is driven by the card brand. The generator stamps respondBy on every dispute based on this table.

RFI windows are half the Stage-1 defense window with a floor of 7 days. The issuer review window after challenge is 55 days — that's when the hourly background job rules on the case.

Evidence

To challenge a dispute, attach evidence files. The flow is two steps, so files go straight to S3-compatible storage (MinIO locally) without passing through the API:

1. POST /v1/disputes/:id/evidence/upload-url with { filename, contentType } — returns a short-lived presigned PUT URL.
2. Client PUTs the file to that URL.
3. POST /v1/disputes/:id/evidence with { storageKey, filename, contentType, kind, note? } — finalises the record and links it to the dispute.

Each evidence record carries a kind: receipt, shipping_proof, communication, refund_policy, service_documentation, or other. The challenge page surfaces a reason-code-specific guide before you upload so you know what the issuer expects.

Outcomes and rulings

From evidence_required you can accept (status moves to accepted) or challenge after attaching evidence (status moves to under_review). Ignoring the dispute lets the response window lapse — the hourly background job flips the status to expired once respondBy is in the past.

For challenged disputes the same hourly job rules after 55 days from the dispute's open time. The current model is ~60% won, ~40% lost — a deliberate simplification that gives the queue movement without being noisy. From a lost outcome the merchant can escalate via POST /v1/disputes/:id/arbitrate; the case moves to arbitration_under_review and an arbitration fee is debited.

Fees

Every dispute carries a scheme-specific processing fee that's debited the moment the chargeback opens. Arbitration adds a second fee on escalation.

Visa's arbitration figure is the combined filing + ruling fee under their post-April-2025 schedule ($500 + $600 = $1,100). Fees are non-refundable even on a win — the funds card on each dispute shows exactly what moves at each status.

Network case IDs

Every dispute carries a networkCaseIdthat mirrors the scheme's case-tracking format, so search-by-network-id works the same way it would in production:

• Visa: VROL-XXXXXXXX (8 hex)
• Mastercard: MC-XXXXXXXXXX (10 digits)
• Amex / Discover / JCB: 12-character alphanumeric