You can use the Disputes API to automate the dispute handling process so that you can respond to disputes or chargebacks as soon as they are initiated. The Disputes API lets you retrieve defense reasons, supply and delete defense documents, and accept or defend disputes.
For an overview of the process and to learn more about how the API works, see the Disputes API overview.
Possible errors
If a Disputes API request fails, the response contains success: false and an errorMessage with more information about the error. The following table shows which error messages can be returned, and for which API request you can get the error.
| Error message | Accept dispute | Defend dispute | Supply defense document | Delete defense document |
|---|---|---|---|---|
| Dispute expired. |  |
|
|
|
| Dispute is not defendable. | |
|
|
|
| Error retrieving dispute. | |
|
|
|
Invalid disputePspReference provided. |
|
|
|
|
| Accept dispute failed. | |
|||
| Defend dispute failed. | |
|||
| Dispute already defended. | |
|||
| Dispute defense period has ended. | |
|||
| No defense reason code specified. | |
|||
| No defense documents supplied. | |
|||
| No content of defense document specified. | |
|||
| No content type of defense document specified. | |
|||
| No defense document type of defense document specified. | |
|||
| Failed to store defense documents. | |
|||
| Failed to validate defense documents. | |
|||
| No document found to delete. | |
|||
| Unable to delete. | |
Retrieving defense reasons and documents
When you make a /retrieveApplicableDefenseReasons request for a specific dispute, the defenseReasons object in the response contains:
- The defense reason codes that are specified by the scheme regulations, and if the defense material for that reason code has already been supplied. Use these codes to find more information about the dispute, for example why it was raised.
- The corresponding defense document type codes for each defense reason code, if those document types are required, and if the documents are already supplied. Use these codes to understand which documents you can or have to provide to defend the dispute.
For example, the response could look like this:
Defense reason codes
The defenseReasons object in the /retrieveApplicableDefenseReasons response contains all the applicable defense reason codes. Per reason code, it contains the applicable defense document type codes, and if the defense requirements are already satisfied.
| Defense reason code | Description | Schemes |
|---|---|---|
AccountTakeover |
The transaction resulted from an account takeover. | Mastercard |
AdditionalInformation |
You can supply additional information. | Elo, Discover, Mastercard, Visa |
AirlineFlightProvided |
The cardholder has or could have used the provided airline ticket. | Mastercard |
AirlineRFIresponse |
The response to a Request for Information (RFI) for airlines. | Discover, Mastercard |
AirlineCompellingEvidence |
You can supply evidence to support the dispute. | Mastercard |
ATMtransaction |
The transaction was an ATM transaction. | Visa |
AuthorisedTransaction |
The issuer authorised the transaction amount, or an amount greater than the transaction amount. | Discover, Mastercard, Visa |
AutomaticRFIresponse |
The automatic response to a Request for Information (RFI). | American Express, Elo, Discover, Mastercard, Visa |
CancellationOrReturns |
The cardholder never returned the merchandise or did not accept the cancellation. | Mastercard |
CancellationTermsFailed |
The cardholder failed to meet the cancellation terms of the contract. | Discover, Mastercard |
CardNotPresentRFIresponse |
The response to a Request for Information (RFI) for a Card Not Present (CNP) transaction. | American Express, Elo, Discover, Mastercard, Visa |
CardPresentFraud |
Card present fraud. | Visa |
CardPresentRFIresponse |
The response to a Request for Information (RFI) for a transaction where the card is present. | Discover, Mastercard |
CardholderNotReplied |
The cardholder was notified but did not reply. | Discover, Visa |
CardholderParticipated |
The cardholder participated in the transaction. | Discover, Visa |
CardholderRenewedMembership |
The cardholder renewed membership after cancellation. | Discover, Visa |
CardNotOnExceptionFile |
The account number was not listed on the exception file. | Visa |
CarRentalRFIresponse |
The response to a Request for Information (RFI) for car rentals. | Discover, Mastercard |
ChargebackRemedied |
The chargeback was remedied, evidence provided in documents. | Mastercard |
ChipLiabilityShift |
The transaction falls under the Chip Liability Shift and occurred on a non-EMV chip card. | Mastercard, Visa |
CompellingEvidence |
You can supply evidence to support the dispute. | Mastercard |
CorrectedMcc |
The Merchant Category Code (MCC) was incorrect in the first presentment. With the correct MCC, authorization is not required. | Mastercard |
CorrectedMerchantDetails |
The merchant location or description was incorrect in the first presentment. With the corrected details, authorization is not required. | Mastercard |
CorrectTransactionAmount |
The Transaction Identification Document (TID) shows that the amount was processed correctly. | Discover, Mastercard |
CorrectTransactionAmountSms |
The Transaction Identification Document (TID) shows that the amount was processed correctly. | Mastercard |
CorrectTransactionCurrency |
The correct transaction currency was provided. | Mastercard |
CorrectTransactionDate |
The correct transaction date was provided. | Mastercard |
CreditOrCancellationPolicyProperlyDisclosed |
You can document that the credit or cancellation policy was properly disclosed to the cardholder at the point of interaction. | Discover, Mastercard, Visa |
CVC2ValidationProgram |
The CVC 2 Validation Program (US region only) applies to this transaction. | Mastercard |
DeficiencyCorrected |
The deficiency was corrected. | Mastercard |
DisputedSurcharge |
The cardholder disputed only a part of the transaction amount, and the issuer must prorate the surcharge amount. | Mastercard |
DisputedSurchargeIncorrectProratedCalculation |
The issuer incorrectly calculated the surcharge amount. | Mastercard |
DuplicateChargeback |
Duplicate chargeback. | American Express, Discover, Mastercard, Visa |
EmergencyPaymentAuthorizationService |
The transactions was authorized through the Emergency Payment Authorization Service. | Visa |
EMVLiabilityShift |
There was an EMV liability shift. | Visa |
FaceToFace |
There is no conflicting information in the authorization and clearing messages. | Mastercard |
FaceToFaceConflictingMessages |
There is conflicting information in the authorization and clearing messages. | Mastercard |
GoodsNotReturned |
The cardholder did not return the goods to you. | Discover, Mastercard, Visa |
GoodsOrServicesProvided |
The goods or services were delivered, or there was a delay in delivery. | American Express, Elo, Discover, Mastercard |
GoodsRepairedOrReplaced |
The goods were repaired or replaced. | Elo, Discover, Mastercard, Visa |
GoodsWereAsDescribed |
The goods were delivered as described. | American Express, Elo, Discover, Mastercard, Visa |
IdentifiedAddendum |
The addendum transaction is the cardholder's responsibility. | Mastercard |
IllegibleDocumentationReceived |
The provided documentation cannot be read, and it cannot be established that the chargeback is valid. | Mastercard |
IncorrectTransactionDate |
The transaction was authorized, but was processed with an incorrect transaction date. | Mastercard |
IncreasedTransactionAmount |
The increased debit to the account is valid. | Discover, Mastercard |
InvalidARD |
The Acquirer Reference Data (ARD) on the chargeback is not valid; documentation was provided or not required. | Mastercard |
InvalidCancellationCode |
The cancellation code was not valid. | Visa |
InvalidChargeback |
The issuers chargeback was not valid, for example non-supporting documentation. | Mastercard, Visa |
InvalidReasonCodeForMCC |
The reason code is not valid for the Merchant Category Code (MCC). | Mastercard, Visa |
LiabilityShiftFullUCAF |
There was a global liability shift. | Mastercard, Visa |
LiabilityShiftMerchantUCAF |
There was a merchant-only liability shift. | Mastercard, Visa |
MerchandiseNotCounterfeit |
The merchandise was not counterfeit. | Discover, Visa |
MerchandiseReceived |
The shopper received the merchandise. | American Express, Discover, Visa |
MissingInformation |
Provide missing information, or provide information that can be read. | Mastercard |
MultipleAuthorisations |
Multiple authorizations were obtained for this transaction, or the authorization amount was greater than or equal to the captured amount. | Mastercard |
NoARDprovidedInMessageText |
The issuer did not provide the Acquirer Reference Data (ARD) of the second transaction. | Mastercard |
NoAuthorisationRequiredManualImprint |
The card data was captured through a manual imprint. | Mastercard |
NoAuthorisationRequiredNotX2X |
The service code on the card was not X2X. | Mastercard |
NoAuthorisationRequiredOffline |
The transaction was processed on an offline point-of-sale (POS) device, and authorization was not required. | Mastercard |
NonReceiptOfRequiredDocuments |
The issuer did not provide the required documents. This reason can only be used 9 to 45 days after you received the notification of chargeback. | Mastercard |
NoShowTransaction |
The transaction was the result of Guaranteed Reservation Service. | Mastercard |
NotCancelled |
The cardholder did not cancel the transaction. | Discover, Visa |
NotNotified |
You or the acquirer were not notified of the cancellation of membership. | Discover, Visa |
NotRecurring |
The transaction was not a recurring transaction. | Discover, Mastercard, Visa |
NotPaidByOtherMeans |
Additional information. | Visa |
NotReportedToSafe |
The issuer did not properly report the transaction to SAFE. | Mastercard |
PartialAuthorisation |
The captured amount was partially authorized. The amount that was charged back is greater than the amount that was not authorized. | Mastercard |
PaymentByOtherMeans |
You can provide an explanation that supports the validity of the transaction charged. | Discover, Mastercard |
PayPassTransaction |
The transaction was a PayPass transaction below chargeback protection amount. | Mastercard |
PINTransaction |
The PIN was entered for the transaction. | Discover, Mastercard, Visa |
PosDeviceFailure |
The transaction was under the bottom limit and there was a POS failure at the time of purchase. | Mastercard |
PresentmentWithinTimeLimit |
The transaction was presented within the given time limit. | Visa |
PreviousTransactionNotChargebacked |
The previous transaction was not charged back. | Visa |
PreviousTransactionNotChargebackedARNprovided |
The previous transaction was not charged back, and an Acquirer Reference Number (ARN) is present to match. | Visa |
ProofOfCardPresenceAndSignatureWithTerminalReceipt |
The card was present and a signed terminal receipt is available. | Discover, Mastercard |
ProofOfCardPresenceAndSignatureWithoutTerminalReceipt |
The card was present and documentation is available to prove this. | Discover, Mastercard |
ProofOfCardPresenceAndSignatureChipNoPIN |
The card was present and chip was used. | Mastercard |
ProofOfCardPresenceAndSignatureLossTheftOrDamage |
The card was present and a signed terminal receipt is available. The transaction involves loss, theft, or damage. You should provide the receipt that contains the items that were additionally billed. | Mastercard |
ProofOfCardPresenceAndSignatureNotMasterCardWorldWideNetwork |
The card was present and a signature exists for a transaction that was not processed via the MasterCard Worldwide Network. | Mastercard |
PurchaseProperlyPosted |
The issuer claimed that the transaction was not for an installment billing, and the transaction was properly identified as an installment transaction in the authorization request. | Discover, Mastercard, Visa |
QPSTransaction |
The transaction was a properly identified QPS transaction of an amount equal to or less than the chargeback protection amount. | Mastercard |
RecurringTransactionsCompellingEvidence |
The transaction was a non face-to-face recurring transaction. | Mastercard, Visa |
RecurringTransactionsCompellingMerchantEvidence |
The transaction was a non face-to-face recurring transaction, of which you have compelling evidence. | Mastercard, Visa |
RetrievalRequestFulfilled |
The retrieval request has been fulfilled. | Discover |
SaleTermsNotMisrepresented |
The terms of sale were not misrepresented. | Discover |
ScanningError |
The provided documentation is incomplete or is about a wrong transaction probably due to a scanning error. | Mastercard |
ServicesProvided |
You have provided services. | Visa |
ServicesProvidedAfterCancellation |
You have provided services after the cancellation data used by the cardholder. | Elo, Discover, Mastercard |
ShippedToAVS |
Address Verification Service (AVS). | Mastercard |
ShippedToAVSAdditionalInformation |
Address Verification Service (AVS) additional information. | Discover, Mastercard |
SupplyDefenseMaterial |
You can supply defense material to defend the chargeback. | American Express, Elo, Discover, Mastercard, Visa |
SuspiciousTransaction |
The issuer was advised that the transaction was suspicious. | Mastercard |
TechnicalFallback |
The transaction was the result of a technical fallback. | Mastercard |
TelecomFailure |
The transaction was under the bottom limit, and there was a telecom failure at the time of purchase. | Mastercard |
Telex |
The acquirer proves that the card acceptor received authorization for the transaction amount or greater as a result of a telex to the issuer. | Mastercard |
TimeshareTransactionCancellationPeriodExpired |
The transaction was not cancelled within 14 calendar days of the contract date or receipt date of the contract or related documents. | Visa |
TransactionNotPOS |
The transaction was not an in-person payment. | Discover, Mastercard |
TransactionAuthorisedOnline |
The transaction was authorized online. | Visa |
TwoDifferentMagStripeTelCalls |
Proof that the time of call for each Magnetic-Stripe Telephone call differs. | Visa |
TwoDifferentTIDs |
Two different Transaction Identification Documents (TIDs) with the same card number are present. | Discover, Visa |
TwoDifferentTIDsATM |
Two different Transaction Identification Documents (TIDs) with the same card number are present (ATM). | Mastercard |
TwoDifferentTIDsPOS |
Two different Transaction Identification Documents (TIDs) with the same card number are present (POS). | Mastercard |
TwoPINTransactions |
A PIN was present for one or both transactions. | Mastercard |
TwoPriorFraudChargebacks |
There were two or more previous fraud-related chargebacks. | Mastercard |
UnreasonableAmount |
The cardholder agreed to an amount range as reasonable, and the transaction amount did not exceed this amount range. | Mastercard |
Defense document type codes
You can use defense document type codes to understand which documents you can or have to provide to defend a dispute with a specific defense reason code.
The defenseReasons object in the /retrieveApplicableDefenseReasons response contains the applicable document type codes in the defenseDocumentTypeCode field. The response also indicates if those document types are required or optional, and if the documents are already available.
When you defend the dispute, you can only use the defense document type codes that are returned for the defense reason code.
You can add a generalized defense document type. Contact our Support Team to enable this document type. When enabled, you can supply a generic defense document for all schemes and set the defenseDocumentTypeCode to AlternativeDefenseMaterial.
| defenseDocumentTypeCode | Description | Schemes | |
|---|---|---|---|
AcquirerRFItransactionDetails |
Automatically gathered transaction details. | Visa, Mastercard, Elo | |
AddendumDocumentation |
Documentation showing that transaction is an addendum to a previous transaction. | Mastercard | |
AdditionalTransactions |
Additional transactions connected with the disputed flight. | Mastercard | |
AlternativeDefenseMaterial |
Defense material. | Visa, Mastercard, Discover, Elo, American Express | |
ARDnotProvided |
Proof that Acquirer Reference Data (ARD) was not provided. | Mastercard | |
ATMSupportingDocuments |
See Appendix A of Chargebacks – Mastercard Europe ATM Transactions. | Mastercard | |
AuthorisationLog |
Authorization log or documentation showing that the authorization took place. | Mastercard | |
AuthorisedTransaction |
Proof that the transaction was authorized. | Visa, Mastercard | |
CancellationNeverAccepted |
Rebuttal stating that the cancellation was never accepted. | Mastercard | |
CardholderIdentification |
Identification documentation showing a link to the cardholder. | Mastercard | |
CardholderNotReplied |
Documentation showing that the cardholder was notified but did not reply. | Visa | |
CardholderRenewedMembership |
Documentation showing that the cardholder renewed their membership after cancellation. | Visa | |
CardPresent |
Proof that the card was present during the transaction and there is a cardholder signature. | Visa, Mastercard | |
ChargebackRemedied |
Documentation showing that the chargeback was remedied. Other defenses are not applicable. | Mastercard | |
ChipLiabilityNotApplicable |
Proof that chip liability was not applicable. | Mastercard | |
ChipLiabilityShift |
Proof that the transaction was authorized. | Visa, Mastercard | |
CompellingEvidence |
Compelling evidence to defend the dispute. | Visa, Mastercard | |
CorrectedMcc |
Correct MCC. | Mastercard | |
CorrectedMerchantDetails |
Correct card acceptor location or description. | Mastercard | |
CorrectTransactionCurrency |
Documentation proving the correct currency was provided. | Mastercard | |
DateMerchandiseShipped |
Date when the merchandise was shipped. | Visa, American Express | |
DefenseMaterial |
Defense material that remedies the chargeback. | Visa, Mastercard, Discover, Elo, American Express | |
DisclosureAtPointOfInteraction |
Rebuttal or proof that proper disclosure was given to the cardholder at the point of interaction. | Visa, Mastercard, Discover | |
DuplicateChargeback |
First chargeback reference number and date of original chargeback. | Visa, Mastercard, Discover, American Express | |
EvidenceOfCardholderParticipation |
Compelling evidence that the cardholder participated in the transaction. | Visa | |
FlightManifest |
Flight manifest showing the cardholder's name. | Mastercard | |
FlightTicket |
Flight ticket or boarding pass showing the cardholder's name. | Mastercard | |
FlightTicketAtBillingAddress |
Proof of receipt of the flight ticket at the cardholder's billing address. | Mastercard | |
FlightTicketUsed |
Documentation proving that the airline tickets were used by the cardholder. | Mastercard, Elo | |
FligthTookPlace |
Documentation proving that the airline rendered the service. | Mastercard, Elo | |
FormalAffidavitOfFailure |
Formal affidavit of telecommunication failure or POS device failure. | Mastercard | |
FrequentFlyer |
Credits of frequent flyer miles for the flight showing connection to the cardholder. | Mastercard | |
GoodsNotReturned |
Statement that you did not receive the goods back from the shopper. | Visa, Mastercard, Discover, Elo | |
GoodsRepairedOrReplaced |
Written rebuttal documenting that the goods were repaired or replaced. | Visa, Mastercard, Discover, Elo | |
GoodsWereAsDescribed |
Proof showing that the goods were delivered as described. | Visa, Mastercard, Discover, Elo, American Express | |
IncorrectTransactionDate |
Correct transaction date and incorrect transaction date. | Mastercard | |
IncreasedTransactionAmount |
Documentation to support that the cardholder is responsible for the disputed amount. | Mastercard | |
InvalidCancellationCode |
Documentation to explain the invalid cancellation code. | Visa | |
InvalidChargeback |
Documentation to support that the chargeback is remedied or not valid. | Visa, Mastercard, Discover | |
IssuerAuthorisedTransaction |
Proof that the issuer authorized the transaction. | Mastercard | |
LiabilityShiftFullUCAF |
Mastercard SecureCode SL2 (Global Liability Shift) | Mastercard | |
LiabilityShiftMerchantUCAF |
Mastercard SecureCode SL1 (Global Liability Shift) | Mastercard | |
MerchandiseDescription |
A description of the merchandise or services. | Visa, Mastercard, Discover, Elo, American Express | |
MerchandiseNeverReturned |
Rebuttal stating that the merchandise was never returned. | Visa | |
MerchandiseNotCounterfeit |
Documentation to support your claim that the merchandise was not counterfeit. | Visa | |
MerchantProofOfRecurringTransaction |
Proof that the transaction is a recurring transaction with no previous chargeback. | Visa, Mastercard | |
MultipleAuthorisations |
Proof of multiple authorizations. | Mastercard | |
NoAuthorisationRequiredNotX2X |
Proof that the service code on the card was not X2X. | Mastercard | |
NoAuthorisationRequiredOffline |
Proof that the transaction was processed on an offline POS device. | Mastercard | |
NotCancelled |
Documentation showing that the service was not cancelled. | Visa | |
NotChargebacked |
Documentation showing that the transaction was not charged back. | Visa | |
NotChargebackedAuto |
Documentation showing that the transaction was not charged back. (automatic response). | Visa | |
NotNotified |
Documentation showing that the acquirer and your business were not notified of cancellation of membership. | Visa | |
NotX2X |
Proof that the service code on the card was not X2X. | Mastercard | |
OriginalAmount |
The original transaction amount if the disputed transaction represents partial shipment. | Mastercard, Discover | |
PaperAirlineTicket |
Documentation showing that the cardholder was issued a paper airline ticket. | Mastercard, Elo | |
PartialAuthorisation |
Proof that the captured amount was partially authorized, and that the amount that was not authorized is higher than the amount that was charged back. | Mastercard | |
PassengerIdentification |
Passenger identification documentation showing a link to the cardholder. | Mastercard | |
PaymentByOtherMeans |
An appropriate explanation and documentation showing two separate transactions. | Mastercard, Discover | |
PayPassTransaction |
Proof that the transaction was a PayPass transaction below the chargeback protection amount. | Mastercard | |
PINTransaction |
Proof that the PIN was provided with the transaction | Visa, Mastercard | |
PosDeviceFailure |
Documentation showing that there was a POS failure at the time of purchase. | Mastercard | |
PositiveAVS |
Documentation showing a positive AVS response (X or Y). |
Mastercard, Discover | |
PresentmentWithinTimeLimit |
Proof that the transaction was presented within the given time limit. | Visa | |
PrintedSignedTerminalReceipt |
A printed and signed terminal receipt. | Mastercard | |
ProofOfAbilityToProvideServices |
Proof showing that you are able to provide the services. | Mastercard, Discover, Elo | |
ProofOfAccountTakeover |
Documentation showing that the transaction resulted from an account takeover. | Mastercard | |
ProofOfAttendedPOSTerminal |
Documentation showing that the transaction occurred on an attended POS terminal. | Mastercard | |
ProofOfCardPresenceAndSignatureChipNoPIN |
Proof that the card was present and the chip was used. | Mastercard | |
ProofOfCardPresenceAndSignatureWithTerminalReceipt |
Proof that the card was present and that a signed terminal receipt is available. | Mastercard | |
ProofOfCardPresenceSignatureOrChipPIN |
Proof that the card was present and that a cardholder signature is available. | Mastercard | |
ProofOfGoodsOrServicesProvided |
Proof showing that the goods or services were provided to the cardholder. | Visa, Mastercard, Discover, Elo, American Express | |
ProofOfNoShow |
Documentation showing that a reservation was made by the cardholder. | Mastercard | |
ProofOfRecurringTransaction |
Description of goods and proof that the transaction is a recurring transaction with no previous chargeback. | Visa, Mastercard | |
ProofOfRetailSaleRatherThanCredit |
A copy of the Transaction Identification Document (TID) as proof that the transaction involved a retail sale rather than a credit. | Mastercard, Discover | |
QPSTransaction |
Proof that the QPS transaction has an invalid reason code. | Mastercard | |
ReasonForReturn |
Documentation showing that the reason for return was supplied. | Visa, Mastercard | |
RetrievalRequestFulfilled |
Automatically generated proof that a retrieval request has been fulfilled. | Discover | |
ReturnedMerchandiseNotReceived |
Documentation showing that you did not receive the merchandise. | Visa | |
SaleTermsNotMisrepresented |
Documentation showing that the terms of sale of the merchandise or services were not misrepresented. | Visa | |
ShippedToAVS |
Documentation showing that the merchandise was sent to the AVS-confirmed billing address. | Mastercard, Discover | |
ShipToAddress |
Documentation showing the ship to address. | Mastercard, Discover | |
SuspiciousTransaction |
Documentation showing that the issuer was advised that the transaction was suspicious. | Mastercard | |
TechnicalFallback |
Documentation showing that the transaction was the result of a technical fallback. | Mastercard | |
TelecomFailure |
Documentation showing that there was a telecom failure at the time of purchase. | Mastercard | |
Telex |
Proof that the issuer authorized the transaction amount or higher by telex. | Mastercard | |
TIDorInvoice |
A copy of the Transaction Identification Document (TID) or invoice. | Visa, Mastercard, Discover, Elo, American Express | |
TransactionNotPOS |
Proof that the transaction was not a POS transaction. | Mastercard | |
TwoDifferentTIDs |
Copies of two different Transaction Identification Documents (TIDs). | Visa, Mastercard, Discover | |
TwoPINTransactions |
Copies of two different PIN transactions. | Mastercard | |
TwoPriorFraudChargebacks |
Copies of two previous fraudulent chargeback transactions. | Mastercard | |
UnreasonableAmount |
Documentation showing that the transaction amount did not exceed the reasonable amount range as agreed with the cardholder. | Mastercard |