Disputes reconciliation

Last updated: April 29, 2022

You have two options for reporting on the financial implications of disputes and reconciling chargebacks with your payments:

Disputes report via the Hub. This gives you a record of all dispute-related events.
Payments report via our Reconciliation API. This gives you a record of events that have financial implications for your balance, including dispute events.

In both reports, you'll find our dispute indicator codes, which help you match up the financial activity on your account with the progress of dispute cases.

Tip

The best way to track the progress of a dispute case is to use the payment ID (prefixed with pay_) of the payment to which the dispute applies. The payment ID stays the same across the Hub, Reconciliation API, and webhooks.

Note

Sometimes, you may receive two disputes against the same payment. These will show as two separate ADJM records for the same payment ID, with a different time for each.

Differences between disputes and payments reports

You will see different data for the same dispute case depending on which report you use. The disputes report records all dispute-related status changes. The payments report only records actions that have a financial impact on your account.

For example, if you lose a dispute, this will be reported in the disputes report with an RPDL indicator. But, because the disputed amount was already taken from your account when the dispute was first raised (ADJM), this will not be reported in the Reconciliation API payments report.

To generate a disputes report, and view any you've previously created, log in to the Hub, go to Reports, and the find the Disputes section. Click New report to create a new disputes report.

These reports list all of the disputes that occurred during the selected period, with various columns providing more information about each event.

Here’s a simplified example of what two separate dispute cases might look like in your Hub disputes report if you sort the data by payment ID.

Information

Learn what the dispute indicator codes mean below.

Dispute ID	Dispute indicator code	Payment ID
`id_1`	`ADJM`	`pay_code_a`
`id_2`	`RPDR`	`pay_code_a`
`id_3`	`RPDW`	`pay_code_a`
...	...	...
`id_4`	`ADJM`	`pay_code_b`
`id_5`	`RPDR`	`pay_code_b`

So for the first payment (pay_code_a), you can see the dispute case associated with it has been won (RPDW).

For the second (pay_code_b), the dispute associated with it is currently in progress (RPDR) – the scheme is now reviewing the evidence you submitted.

Use our Reconciliation API’s payments endpoint to generate a payments report. These reports record any charge or credit to your account, including those related to disputes.

As with the Hub's disputes reports, look up the payment ID of the disputed payment you’re interested in to find out more about it.

Here's a simplified example of two separate payments in a report, one of which has a dispute raised against it.

The action type column tells you what action was taken (where there are duplicates, it means there were multiple financial implications caused by that same action), and the breakdown type tells you more about the financial implication.

Information

Learn what the dispute indicator codes mean below.

Action ID	Action type	Payment ID	Breakdown type
`act_code_1`	Authorization	`pay_code_x`	Scheme fee
`act_code_2`	Capture	`pay_code_x`	Captured
...	...	...	...
`act_code_3`	Authorization	`pay_code_y`	Scheme fee
`act_code_4`	Capture	`pay_code_y`	Captured
`act_code_4`	Capture	`pay_code_y`	Scheme fee
`act_code_5`	Chargeback	`pay_code_y`	Chargeback (`ADJM`)
`act_code_5`	Chargeback	`pay_code_y`	Scheme fee

Looking at the action type and breakdown type columns for the second payment (pay_code_y), you can see a dispute has been raised against it.

The ‘Chargeback’ action type appears twice because the payments report covers any action that has a financial impact on your account. So, in this case, first the disputed amount was debited from your account, and then you were charged a scheme fee for that same dispute.

The table below lists all the dispute indicator codes you’ll see in both the disputes reports from the Hub and the payments reports from the Reconciliation API.

Each code is associated with a different dispute status, allowing you to track the progress of live disputes as the cases progress.

Tip

If you want to be notified every time a dispute’s status updates, you can subscribe to the associated webhook.

Indicator code	API status	Description	Webhook
`RTVL`	Our API does not currently return retrieval requests.	You’ve received a request for more information (also known as a retrieval request). A dispute may be raised if you do not respond.	payment_retrieval
`ADJM`	`evidence_required`	You’ve received a dispute and you need to submit evidence if you want to defend against it.	dispute_evidence_required
`AUTO`	`resolved`	You've already refunded the customer, so we automatically submitted the relevant evidence and resolved the dispute for you.	dispute_resolved
`CBRV`	`canceled`	The issuer has canceled the dispute. You have been refunded the disputed amount.	dispute_canceled
`RPDR`	`evidence_under_review`	You’ve submitted your evidence and the issuer is now reviewing it. You have been charged a dispute fee.	n/a
`RPDW`	`won`	You have won the dispute. You have been refunded the disputed amount.	dispute_won
`RPDL`	`lost`	You have lost the dispute. You have been charged a dispute fee, if applicable.	dispute_lost
`ARBR`	`arbitration_under_review`	You have escalated your case to arbitration with the issuer and/or scheme.	n/a
`ARBW`	`arbitration_won`	The scheme has decided the case in your favour. You have been refunded the disputed amount.	n/a
`ARBL`	`arbitration_lost`	The scheme has decided the case in the issuer’s favour. You have been charged an arbitration fee.	n/a

Disputes reconciliation

Tip

Note

Differences between disputes and payments reports

Creating a disputes report

Disputes report example

Information

Creating a payments report

Payments report example

Information

Dispute indicator codes

Tip