Risk-management icon

Disputes API reference

Learn about possible Disputes API errors, and the different defense reasons and document type codes that can be returned using the Disputes API.

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. -white_check_mark- -white_check_mark- -white_check_mark- -white_check_mark-
Dispute is not defendable. -white_check_mark- -white_check_mark- -white_check_mark- -white_check_mark-
Error retrieving dispute. -white_check_mark- -white_check_mark- -white_check_mark- -white_check_mark-
Invalid disputePspReference provided. -white_check_mark- -white_check_mark- -white_check_mark- -white_check_mark-
Accept dispute failed. -white_check_mark-
Defend dispute failed. -white_check_mark-
Dispute already defended. -white_check_mark-
Dispute defense period has ended. -white_check_mark-
No defense reason code specified. -white_check_mark-
No defense documents supplied. -white_check_mark-
No content of defense document specified. -white_check_mark-
No content type of defense document specified. -white_check_mark-
No defense document type of defense document specified. -white_check_mark-
Failed to store defense documents. -white_check_mark-
Failed to validate defense documents. -white_check_mark-
No document found to delete. -white_check_mark-
Unable to delete. -white_check_mark-

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

See also