Chargeback Management

Dispute lifecycle, evidence collection, chargeback rate control per operator.

Phase 4

Spec

Why It Matters

A chargeback is a forced reversal of funds initiated by the cardholder's issuing bank, bypassing both the platform and the PSP. In iGaming, chargeback rate is one of the key risk metrics: a PSP can terminate the contract if the rate exceeds card network thresholds. On a B2B platform, one operator with bad player behavior puts payment access at risk for everyone.

PSP account termination

Visa and Mastercard enforce chargeback thresholds on PSPs, not on merchants. If our chargeback rate exceeds 1% (Visa) or 1.5% (Mastercard) of monthly transaction volume, the PSP faces fines and may terminate our account to protect their own standing.

Financial loss per dispute

Each chargeback costs more than the disputed amount: the original transaction is reversed, plus a dispute fee ($15–$100 depending on PSP), plus any Visa/MC scheme fees. In iGaming, the original funds may have already been wagered -- recovering them requires clear evidence.

Fraud pattern in iGaming

A common pattern: player deposits, wagers, withdraws winnings, then files a chargeback on the original deposit claiming it was unauthorized. Without proper evidence collection at transaction time, these disputes are very hard to win.

Multi-tenant exposure

On a B2B platform, chargebacks from one operator affect the shared PSP account. High chargeback rates from a single operator can jeopardize payment access for all other operators on the platform.

Chargeback Lifecycle

The evidence submission deadline is hard. The PSP sets a window (usually 7–21 days). If evidence is not submitted in time, the dispute is automatically lost regardless of its strength. The system must generate alerts 72 hours before the deadline.

Cardholder files a dispute

The cardholder contacts their bank (issuer) claiming the transaction was unauthorized or the goods/services were not delivered. The issuer initiates a chargeback against the PSP. We learn about this via a PSP webhook (chargebackCreated) or PSP dispute API polling.

Platform receives notification

Happens in real time

A chargeback_webhook_handler creates a record in the chargebacks table with status OPEN. The original transaction is flagged. Player balance may be placed on hold if the amount was already credited (platform policy decision). Ops team is notified immediately via alert.

Evidence collection window

Typically 7–21 days from notification

Platform automatically assembles the evidence package: transaction record with IP and device fingerprint, KYC verification status and documents, game session logs (timestamps, bets placed, winnings), login history around the transaction time, any prior successful withdrawals by this player (strong counter-evidence).

Evidence submission to PSP

Must be done before PSP deadline

Ops submits the assembled evidence package via PSP dispute API (or manually via PSP dashboard if the PSP doesn't provide an API). Chargeback status transitions to EVIDENCE_SUBMITTED. The PSP forwards the evidence to the card network (Visa/MC) for arbitration.

Card network arbitration

30–75 days

The card network reviews evidence from both sides (issuer's claim vs merchant's evidence). Decision takes 30–75 days. Neither platform nor PSP can influence this phase -- it's purely in the card network's hands.

Won -- funds returned

Card network rules in our favor. Chargeback status → WON. The disputed amount is credited back to our PSP account. If the player balance was placed on hold, it is released. A won_chargeback event is logged against the transaction.

Lost -- funds are gone

Card network rules in favor of the cardholder. Chargeback status → LOST. The disputed amount is permanently reversed. Platform must decide: absorb the loss, recover from operator (per contract), or flag the player account. A lost_chargeback event is logged and the ops team is alerted.

Data Model

The chargebacks table lives alongside transactions. One chargeback record per transaction (1:1 relationship -- theoretically you can receive multiple disputes on one transaction but in practice this is an edge case requiring manual review).

Column	Type	Description
`id`	uuid PK	Unique chargeback record ID
`transaction_id`	uuid FK	Reference to the original transaction in transactions table
`operator_id`	uuid FK	Which operator this chargeback belongs to (multi-tenant)
`psp_id`	uuid FK	Which PSP reported the chargeback
`psp_dispute_id`	text	PSP-side dispute/case ID for API calls
`amount`	numeric	Disputed amount in original transaction currency
`currency`	char(3)	ISO 4217 currency code
`reason_code`	text	Visa/MC reason code (e.g. 10.4 -- Fraud, 13.1 -- Merchandise not received)
`status`	text	OPEN \| EVIDENCE_SUBMITTED \| WON \| LOST \| EXPIRED
`evidence_package`	jsonb	Assembled evidence: transaction data, KYC refs, game logs, IP, device
`evidence_deadline`	timestamptz	Hard deadline for submitting evidence to PSP -- set from PSP notification
`balance_held`	boolean	Whether player balance was placed on hold when chargeback was opened
`resolved_at`	timestamptz	Timestamp when WON or LOST decision was received
`created_at`	timestamptz	When the chargeback record was created in our system

Evidence Collection

Evidence is collected automatically when the chargeback is opened via queries to adjacent services. Ops should not manually hunt for logs -- the system assembles the evidence package and stores it in evidence_package (JSONB). Ops only reviews and confirms before submission to the PSP.

Transaction record

Critical

Transaction ID, amount, currency, timestamp
IP address at time of payment
Device fingerprint and user-agent
Billing address provided by cardholder

KYC verification

Critical

KYC level at time of transaction (verified / unverified)
Verified identity documents (ID/passport)
Selfie match result and timestamp
Verified email and phone number

Player activity logs

Strong

Login events before and after the disputed deposit
Game session records: games played, bets, wins, timestamps
Prior successful withdrawals by the same player (strongest counter-evidence)
Any prior deposits using the same card without dispute

Terms & consent records

Supporting

Timestamp and IP of terms of service acceptance
Responsible gambling acknowledgements
Account creation record and verification email

Thresholds & Alerts

Chargeback rate is calculated as a percentage of transaction count, not amount. PSPs may have their own thresholds lower than card network thresholds -- check the contract. This rate is tracked separately per operator on the platform.

Visa

Visa Dispute Monitoring Program (VDMP)

> 0.65% of monthly txns

Early warning -- PSP contacts merchant. No fine yet but monitoring begins.

Visa

Visa Fraud Monitoring Program (VFMP)

> 1.0% of monthly txns

PSP faces monthly fines ($50 per dispute). Risk of account termination after 4 months.

Mastercard

Excessive Chargeback Program (ECP)

> 1.5% of monthly txns

Fines begin immediately. PSP may terminate the merchant account without notice.

System alert rules

New chargeback opened

Immediate alert to ops. Player balance hold check triggered.

Evidence deadline in 72h

Alert if evidence_package not yet submitted. Escalates to manager.

Operator rate > 0.5%

Weekly threshold check per operator. Alert sent to operator account manager.

Dispute status changed

PSP dispute API polling detects WON/LOST. Balance hold released or written off accordingly.

PSP Dispute API Integration

Each PSP provides its own mechanism for dispute handling -- some via webhook + API, some only through a dashboard. The IDisputeProvider interface abstracts this difference analogously to IPaymentProvider.

Method	Description	Note
`onChargebackReceived(payload)`	Called by webhook handler when PSP notifies of a new dispute. Creates chargeback record, triggers evidence assembly.	Must respond 200 within 3s to PSP
`submitEvidence(disputeId, pkg)`	Submits the assembled evidence package to the PSP dispute API. Updates status to EVIDENCE_SUBMITTED.	Idempotent -- safe to retry
`pollDisputeStatus(disputeId)`	Polls the PSP for the current dispute outcome. Called by background job every 6 hours for open disputes.	Fallback when PSP has no outcome webhook
`onDisputeResolved(payload)`	Called when PSP sends WON/LOST outcome webhook. Transitions chargeback to terminal state, releases or writes off balance hold.	Triggers financial settlement update

Multi-Tenant Rules

Operator isolation

Each chargeback is tagged with operator_id. Chargeback rate metrics are calculated per-operator and never aggregated across operators in reports -- each operator sees only their own exposure.

Liability attribution

Platform contract with each operator defines who bears the cost of lost chargebacks. Typical model: operator absorbs losses for disputes on their players; platform absorbs only if the root cause was a platform infrastructure failure.

Operator suspension trigger

If an operator's rolling 30-day chargeback rate exceeds 0.8%, the platform can automatically pause deposit processing for that operator's brand_id until the rate normalizes. This protects the platform's shared PSP account.