For AI agents: the complete documentation index is at /llms.txt, and the full text of every page is at /llms-full.txt. Most pages are also available as Markdown by adding .md to the URL.
Learn how to automate the reporting and management of disputes
In this guide, you'll learn how to obtain a list of disputes and get the details on a specific dispute case. We also cover how to resolve a dispute by either challenging or accepting it. In our example, we demonstrate a typical scenario that a merchant might go through when receiving a dispute.
For more information on Disputes Management, see our Overview.
Prerequisites
Before starting the steps in this guide, you must do the following:
Our first step is to pull a list of disputes. You must submit the date range you want to query. You can include optional parameters such as the brand of the card involved, the dispute stage, the number of pages to return, the number of results per page, and so on.
The returned list of disputes will include all of the disputes types that are available for your application, such as chargebacks, retrievals, and arbitrations. To understand more about the different types of disputes, see our Overview. You can also filter the list based on the dispute status: Closed, New, or Under Review.
In our example, we don't use any filters as we want to return all the disputes in the timeframe specified.
Sample request
Disputes list response
The response contains all of the disputes that were created from the date specified. This list includes the ID, status, amount, reason, date, and time the dispute was created.
Depending on the use case, the data returned in the disputes list response may be enough information for your application to proceed to the next action (Step 2). Alternatively, we show you in the next step how to pull the full detail of an individual dispute.
Using the unique ID returned in the list, you can obtain the full dispute record to understand more about the disputes that were raised. This will provide you with more detail regarding a single dispute such as a chargeback, retrieval or arbitration.
Sample request
Disputes information response
The information returned in the response provides you with all the details regarding this dispute. This includes the current status of the dispute, the time and date when it was created, and any investigator comments. To see the full list of data that can be returned, see Disputes in the API Explorer.
In the scenario of a chargeback or retrieval case, there are two actions you can take regarding the dispute: accept and take liability for the dispute or challenge it.
Challenge a dispute
A dispute challenge requires some evidence, depending on the case type. This evidence can be in the form of a sales receipt, proof of delivery, or a copy of the terms and conditions. Each evidence document must be submitted as a base64-encoded string.
Sample request
Dispute challenge response
The response of the challenge request contains information on the case, including the status, stage, and the result of the dispute. If successful, the evidence provided is sent to us to review and then sent to the issuer to support the chargeback case. If unsuccessful, detailed information is provided regarding the error.
There are a number of reasons to accept and take liability of a dispute. These reasons include:
If the dispute case is in fact valid.
The amount disputed is minimal and challenging the transaction does not justify the work involved.
To avoid proceeding to arbitration.
To accept liability for a dispute, you just need to provide the unique ID of the case.
Sample request
Accept response
The response contains the status, stage, and the result of the dispute. It also contains information on the result of the action, whether it was successful or not.
By accepting the dispute, you accept the liability of the dispute. The customer then retains the funds, and the case is closed. This also indicates that you do not want to take any further action in the case.
Below is a detailed explanation of some of the dispute fields returned in the API.
entry_mode_code
This is a two-digit code that identifies the method used to accept the cardholder’s payment details.
Code
Card Brand
Description
00
AX
Terminal not used
01
AX
Manual key entry
02
AX
Magnetic stripe read; CVV checking may not be possible; Exact Track 2 contents read but transaction is not eligible for CVV checking
03
AX
Barcode
04
AX
Optical Character Recognition (OCR) read
05
AX
Integrated circuit card read; CVV or iCVV data is reliable
06
AX
Track 1 read
07
AX
Proximity payment using Visa Smart Debit/Credit (VSDC) chip data rules
10, 51, 52, 61, 62, 64, 67, 80, 81
AX
Unknown
90
AX
Magnetic stripe read and exact content of Track 1 or Track 2, CVV check is possible
91
AX
Proximity payment (magnetic stripe on the card was read)
95
AX
Integrated circuit card, CVV or iCVV checking may not be possible
00
DI
Unknown (card not present)
01
DI
Manual key entry
02
DI
Magnetic stripe read
03
DI
Barcode or payment code
04
DI
Optical character reader (OCR)
05
DI
Integrated circuit card reader
07
DI
Electronic commerce (card not present)
08
DI
Card present, magstripe is defective and cannot be read
10
DI
Stored card account (card present)
79, 80
DI
Unknown (card present)
81
DI
Radio frequency identification (RFID) indicator - Magnetic stripe
82
DI
Mobile commerce (card not present)
83
DI
Radio frequency identification (RFID) indicator - Chip
85
DI
Chip fallback (chip-enabled card, processed using the card's magnetic stripe)
90
DI
Voice authorization (card not present)
94
DI
Biometrics (card not present)
00
terminal_capacity_code
The terminal_capacity_code represents the terminal’s:
Capability: How the card information in the disputed transaction was captured
Operating environment: The location of the terminal used in the disputed transaction and whether it was attended or unattended by the card acceptor.
The terminal_capacity_code values and their meaning vary by card brand and are explained in the table below.
Visa
Code
Description
Blank
Unknown, default to 0
0
Unknown
1
No terminal
2
Magnetic stripe reader
3
Optical code
4
OCR reader
5
Chip capable terminal
8
Contactless-read capability
9
Key entry only; no electronic reading capability
Mastercard
Code
Description
Blank
Unknown, default to 9
0
No terminal
1
On card acceptor premises; attended
2
On card acceptor premises; unattended
3
Off card acceptor premises; attended
4
Off card acceptor premises; unattended
5
On cardholder premises; unattended
6
Off cardholder premises; unattended
9
Unknown; data not available
American Express
Code
Description
0
No terminal used or terminal is unknown
1
On card acceptor premises; attended terminal
2
On card acceptor premises; unattended terminal
3
Off card acceptor premises; attended terminal
4
Off card acceptor premises; unattended
5
On cardholder premises; unattended
Testing disputes management
Our Disputes Management solution is available for testing in our free Sandbox environment for registered users of this developer portal. Use our resources below to start testing.
To get a deeper understanding of Disputes Management, we recommend that you use our provided integration references for both API and SDK integrations. For the full detailed API specification, see the API Explorer.
