Reading disputes and fraud alerts

What's new

Two read endpoints expose the risk side of a game's payments. GET /v1/disputes lists chargebacks opened against the game, and GET /v1/fraud_alerts lists the issuer fraud alerts reported against its payments. Both were only visible in the dashboard before.

The two share a filter set — limit, offset, start_at, end_at, and a comma-separated payment_id — and each adds its own: disputes filter by status and reason_category, fraud alerts by fraud_type and source.

A dispute carries the disputed amount in the payment's currency plus amount_usd and amount_eur booked at the time it was recorded, the processor's raw reason string alongside a canonical reason_category, and a fees array. Each fee is flagged with reported_by_processor — true once a settlement report has landed, false while the figure is still an Aghanim estimate — so the two never appear together and cannot be double-counted.

A fraud alert carries the processor's fraud_reason and fraud_reason_code next to a normalized fraud_type, and the three_ds_flow the payment went through (none, challenge, or frictionless).

Impact

Chargeback and fraud reporting can now be pulled on a schedule and reconciled against your own order records without going through the dashboard. Both endpoints return arrays, so page through them with limit and offset.

Changes

Resource	Change
get_disputes	New endpoint. Lists chargebacks, filterable by time range, payment_id, status, and reason_category
get_fraud_alerts	New endpoint. Lists issuer fraud alerts, filterable by time range, payment_id, fraud_type, and source
Components	Added the DisputeRead, DisputeFeeRead, and FraudAlertRead schemas, the DisputeStatus enum (pending, accepted, resolved, won, lost, expired, canceled), the DisputeReasonCategory enum (general, canceled_recurring, credit_not_issued, duplicate, fraudulent, incorrect_amount, not_as_described, product_service_not_received), and the PaymentFraudType enum (card_lost, card_stolen, unauthorized_card_use, counterfeit_card, fraudulent_application, not_received, other)

Upgrade

• No action required. Both endpoints are additive and nothing existing changed.
• Treat reason_category on a dispute and fraud_type on an alert as nullable — they stay null when the case was never resolved to a canonical category.
• When summing dispute costs, read fees as-is rather than adding estimates to reported figures. Check reported_by_processor if you need to know whether a fee is final.

Need help?
Contact our integration team at [email protected]