This page provides guidance on managing disputes primarily through our Dispute API. This includes information on features, receiving new disputes and updates in dispute status, submitting dispute responses, how to find related transactions, and testing.

For more information on the disputes process and how to use the Maast Manager portal for disputes, see Disputes in the Maast Knowledge Base. For conventions, see Dispute Conventions.

Features

The following table shows an overview of the features our API supports and how to access them. See each feature's corresponding section below for more information:

Configuring a Dispute Vendor

If you are a dispute vendor, Maast tracks which merchants have configured and accepted to share data with you. You must request the Maast merchant ID (MID) from your merchant to map to API requests and responses.

If you are a merchant, you can configure your dispute vendor by doing the following:

• Sign in to your Maast merchant portal and select 'Administration' from the left-hand menu.
• In the 'Account Configuration' section, select 'Dispute Management Setup' and click 'Add Dispute Vendor.'
• From here, you can configure which vendor and services are used, then click to agree to
  share data with your merchant.

Receiving Disputes and Changes in Case Status

This section shows you how to receive and interpret dispute data. When you learn the dispute type and reason for the dispute, you can form your business strategy to respond. Providing a timely response to disputes can help you to attempt to recover disputed funds.

How to Receive Dispute Notifications

You can receive new dispute cases and case updates through one of the following methods:

• Notification email - By default, the account administrator receives emails containing new dispute cases and all cases that have changed status in the last seven days. For additional users to receive these emails, configure notification settings in the Maast Manager portal. See Notifications for more information.

• Daily webhook post - Dispute cases are usually posted once a day around 4 a.m. PST (U.S.) for the period midnight to midnight of the previous day. To set up the webhook post, send your information with the endpoint to [email protected].

• Dispute API - Send a Get Disputes request. By default, this returns data for the full day before the GET request (midnight to midnight) and the day of the GET request (up to the time of request). Use filters to request disputes from a different time period.

Whichever method is used, the Get Dispute Fields Returned table in Dispute Conventions provides the fields returned for each dispute case.

Dispute Types

American Express, Discover, Visa, and Mastercard typically use the same dispute types. However, the dispute flows, reason codes, and statuses differ across the card brands.

You can get the dispute type of a given dispute through the following methods:

• In Merchant Manager - Sign in to your Maast manager portal and select 'Reports' in the left-hand menu. In the 'Disputes' section, select 'Dispute History.' Select the funnel icon at the top left and 'Dispute Type' from the drop-down menu. In the pop-up window, add filters to view the various dispute types. Each dispute type is assigned a letter within reports. The description can be viewed by hovering over that value with a cursor. To view new disputes of each type, select 'Disputes' in the left-hand menu and select a dispute type from the 'Quick Links' menu.
• Through a webhook or Dispute API - Find the dispute type letter in the data_type field of a relevant webhook notification or a Get Disputes request response.

The table below shows all possible dispute types, along with the code and description of each:

Dispute Reasons

American Express, Discover, Visa, and Mastercard use separate dispute reason codes for retrieval requests and first-time disputes. They also have different requirements for supporting documentation.

Find the reason code of your dispute using one of the following methods:

• In Merchant Manager - Sign in to the Maast merchant portal. Select Reports, then Dispute History, and view any of the dispute cases and the reason code of each.
• Through a webhook or Dispute API - Find the reason code in the reason_code field of a relevant webhook notification or a Get Disputes request response.

Subsequent dispute types, such as second-time and pre-arbitration disputes, will adopt the same reason code used in the first-time dispute.

Dispute Reason Categories

Dispute reason codes for first-time disputes fall into four main categories: Fraud, Authorization, Processing Errors, and Consumer Disputes. These categories are described below.

To find the category associated with your dispute reason code, reference Dispute Reason Codes: VISA and Dispute Reason Codes: MC, AMEX, DISC in Dispute Conventions.

Fraud Disputes

This category is used when a cardholder claims that they do not recognize a transaction, didn't participate, and didn't provide permission for the transaction to be charged to their account. The assumption is that the cardholder's card information has been used without their knowledge. Included in this category are disputes created due to "friendly fraud." This type of fraud may be caused unknowingly by a cardholder's family member or cardholder.

When responding to these types of disputes, you will be prompted for additional compelling evidence and supporting documentation.

Authorization Disputes

These disputes are initiated when no authorization was obtained or if the authorization code is otherwise invalid. If you did not receive a valid authorization, accept the dispute.

When responding to these types of disputes, you will be prompted for additional evidence and supporting documentation.

As a matter of best practice, when processing a transaction, authorize as close as possible to the full amount of the merchandise or services. When capturing and settling the payment, void the outstanding amount if the amount is less than the authorization. To optimize your dispute outcome, capture the authorization within 7 days. If the amount is greater than the authorization amount and you are not in an industry where tips are enabled, void the previous authorization and create a sale transaction for the total amount.

Processing Error Disputes

This category of disputes is used when the cardholder claims or the issuing bank finds an inaccuracy related to the transaction posted to their account. Examples include:

• Duplicate transactions.
• Incorrect transaction amounts (customer receipt has a different amount to what was processed).
• Credit transactions posted as debit.
• Transactions presented past the allowed time frame once an authorization is obtained.
• Scenarios in which the customer has paid using another form of payment.

When responding to these types of disputes, you will be prompted for additional evidence and supporting documentation.

Consumer Disputes

This category of disputes is used when the cardholder acknowledges participation in the transaction but has a specific complaint about the goods or services. The reasons for this dispute include:

• An expected credit was not received.
• Services or goods were not delivered, performed as expected or were misrepresented.
• Recurring payments were canceled by the cardholder.

When responding to these types of disputes, you will be prompted for additional evidence and supporting documentation.

Dispute Workflows

All Visa disputes are processed through Visa Claims Resolution (VCR), which has two workflow categories - Allocation and Collaboration. These workflows determine money movement and the options available to respond to first-time disputes.

All new Mastercard disputes are processed through the Mastercard Dispute Resolution (MDR) Initiative. Mastercard issues pre-arbitration disputes when the issuer continues a transaction dispute. Any first-time disputes are designated as Collaboration.

For further information, see Visa Dispute Workflows or Mastercard Dispute Workflows in the Maast Knowledge Base.

Submitting Dispute Responses

This section provides reference information for accepting or responding to a dispute through the Dispute API. Please note:

• Before submitting a response, you should understand the following:
  • The dispute type
  • The required response time
  • The reason for the dispute or retrieval request
  • Required supporting documentation
• You can use the API to respond to the following dispute types:
  • First-time disputes
  • Retrieval requests
• You are expected to manage subsequent dispute types through the Maast Manager portal.

Respond to a dispute only if you are within the response time frame and have one of the following:

• Issued a credit to the cardholder. (Never issue a credit once the dispute has been initiated/received, the cardholder has already received credit from the dispute.)
• Proof that the cardholder participated in or benefited from the transaction.
• Proof that the cardholder is no longer disputing the transaction and the issue has been resolved.
• Proof that the cardholder is disputing the charge to benefit from fraudulently denying knowledge of the transaction.

Response Time Frames

The table below shows time windows in which you are required to respond to a given dispute type. All response timing is in relation to the incoming date of a dispute:

🚧

Incoming Dates

All required response timing is in relation to the incoming date of a dispute. Due to the way in which the card brands share dispute data, this may mean that a dispute has an incoming date in the past.

For example, you may receive data on a Tuesday that includes Saturday's, Sunday's, and Monday's incoming disputes.

Accepting a Dispute

By accepting a dispute, you agree to withdraw from challenging the dispute. You can accept the following dispute types via the API:

• First-time chargebacks (C)
• Pre-arbitrations (P)

To do so, send an Accept Dispute request by following the steps in the Accept Dispute implementation guide.

Responding to Retrieval Requests

A retrieval request is a non-monetary request from an issuing bank to retrieve a sales draft (receipt). Generally, these are generated at the request of a cardholder.

To assist the cardholder in recognizing the transaction, provide all pertinent documentation, including transaction receipts, contracts, and agreements proving the cardholder participated in the transaction. If a credit has been issued to the cardholder at any time, provide information about the credit.

To respond to a retrieval request, follow the steps and see sample code in the Dispute API's Submit Dispute Response guide.

Responding to First-Time Chargebacks (C): Mastercard, American Express, or Discover

Mastercard, American Express, and Discover responses use the same response reasons, so they are considered together.

To assemble and submit your response, follow the instructions and see sample code in the Dispute API's Submit Dispute Response guide.

Refer to the Response Conventions: MC, AMEX, DISC section in Dispute Conventions for required and optional fields to include when responding to first-time chargeback (C) disputes involving Mastercard, American Express, or Discover.

Responding to First-Time Disputes: Visa

Visa supports two workflows: Allocation and Collaboration. As part of Visa Claims Resolution (VCR), Visa requires a respondent to select a path based on the reason code provided with the dispute data.

To assemble and submit your response:

1. Locate the dispute's reason code (reason_code) provided in the dispute data you have received. This can be found in response to a Get Disputes request or in a webhook notification.
2. In the Dispute Reason Codes: VISA table, use the reason code to find the dispute's description, its category type, and what documentation to provide to win the dispute.
3. In the Response Reason Options: VISA table, use the reason code to find which response reason (cbr_response_type) to send in your reponse. This table also refers you to any relevant reason detail codes to include.
4. Assemble documentation for your response, ensuring that it meets the requirements in the Supporting Documentation section.
5. Follow the instructions in our Submit Dispute Response guide. Use the control number (rec_id) provided in the dispute data you have received, and send the fields found in Response Body Parameters: VISA.

For general information and Visa Dispute Workflows, please visit the Maast Knowledge Base. For information on the Remedy response option, see the article Visa Compelling Evidence 3.0 (CE 3.0) and April 2023 Changes in the Maast Knowledge Base.

Supporting Documentation

Most dispute responses require supporting documentation. This section delineates requirements and recommendations for the supporting documentation you submit.

Supporting Documentation Requirements

You may upload only one file per dispute response, and the file must meet the following requirements:

• One PDF no greater than 10 MB in size and no more than 19 pages in length.
• For retrieval requests: One PDF no greater than 2 MB in size and no more than 4 pages in length.
• If you have multiple documents to submit, combine them into a single PDF file.
• Do not password-protect or otherwise lock the PDF file.

If you receive an error during upload, verify that the file meets all the requirements above.

Supporting Documentation Guidelines

You should include the following information in the supporting documentation:

• A concise one-page review of why you are responding to the dispute. The review should do the following:
  • Summarize the supporting information you are including.
  • Address specific complaints or points made in the cardholder documentation.
  • Highlight key timeline points, customer interactions, or relevant compelling information that provides evidence that the Authorization is valid.
• Supporting evidence.

For retrieval requests, provide all pertinent documentation that may assist the cardholder in recognizing the transaction. Find recommended documentation for each dispute type in the sections below.

🚧

Do not include the full credit card number in dispute response documentation for security reasons and PCI DSS compliance.

Fraud Disputes: Recommended Documentation

For Mastercard, American Express, or Discover fraud disputes, include supporting compelling evidence such as:

• Positive Address Verification (AVS) and Card Verification Value (CVV) matches during authorization.
• Proof of product delivery to the cardholder. (Use of a delivery vendor that has tracking and requires a signature is advised.)
• Copies of receipts, invoices, or contracts, including a description of any products or services provided.
• Any communication with the cardholder regarding the purchase, including the cardholder’s email address.
• Proof that the cardholder downloaded goods from your company’s website, including purchaser’s IP address, time, date, and device details.
• The card is used in a previously undisputed transaction.
• Other proof showing the cardholder or a member of their family has received and/or used the merchandise or services.

For Visa fraud disputes, here is recommended supporting evidence for each dispute reason code:

• 10.1 - Documentation showing the transaction was chip read and evidence that the full chip data was transmitted.
• 10.2 - Documentation showing the transaction took place at an EMV PIN-compliant terminal.
• 10.3 - One of the following:
  • A copy of the authorization record as proof the card’s magnetic stripe or chip was read at the point of sale.
  • A copy of the manual imprint obtained at the time of sale. (Does not apply to the Europe region.)
• 10.4 - Advise your card processor that the transaction was Verified by Visa-authenticated at time of authorization. If you support subscriptions or other repeat customer purchases, see this article about the Remedy response option and evidence.
• 10.5 - If you already accepted a prior dispute for the same transaction, provide details of the previously accepted dispute.

Authorization Disputes: Recommended Documentation

For Mastercard, American Express, or Discover authorization disputes, include evidence that the transaction received a valid authorization code for the amount of the transaction on the transaction date.

For Visa fraud disputes, here is the recommended supporting evidence for each dispute reason code:

• 11.1 - Documentation showing the transaction took place at an EMV PIN compliant terminal.
• 11.2 - Evidence from your card processor that the transaction was authorized online or offline via the chip.
• 11.3 - Evidence that the cardholder gave consent and authorized the transaction, including, if applicable, an e-signature or a checked box that indicates a purchase was acknowledged and approved.

Processing Error Disputes: Recommended Documentation

For Mastercard, American Express, or Discover processing error disputes, include supporting compelling evidence such as:

• A valid authorization code for the amount of the transaction on the transaction date.
• Evidence of the transaction, including a copy of receipts, invoices, or contracts, and a description of any products or services provided.
• Evidence the transaction posted to the cardholder account matches the transaction receipt, invoice, or contract agreed to by the cardholder.
• Evidence the transaction was processed within 30 days from the date the valid authorization was obtained.
• Evidence that the cardholder was billed after the merchandise was shipped.
• Any communication with the cardholder regarding the purchase, including the cardholder's email address.

For Visa processing error disputes, here is the recommended supporting evidence for each dispute reason code:

• 12.1 - Documentation showing the transaction was completed within the time limit.
• 12.2 - Documentation showing the transaction was processed correctly as a credit or debit to the cardholder’s account.
• 12.3 - Evidence this was a properly processed Dynamic Currency Conversion (DCC) transaction, such as evidence that the cardholder actively chose DCC or a copy of the transaction receipt.
• 12.4 - A copy of the receipt showing that the account number on the dispute matches the account number on the receipt. Additionally, if the dispute relates to a transaction processed on an account number not on the issuer’s master file, a copy of the authorization log.
• 12.5 - Documentation (such as a copy of the transaction receipt) showing the transaction amount is correct.
• 12.6.1 - Information and documentation to show the two transactions are separate and are not for the same item or service.
• 12.6.2 - The sales records or other documentation that shows no other form of payment was used.
• 12.7 - The sales records or other documentation to support that the transaction was authorized with valid data.

Consumer Disputes: Recommended Documentation

For Mastercard, American Express, or Discover consumer disputes, include supporting compelling evidence such as:

• A detailed description of a refund, return, and/or cancellation policy. Include how you properly disclosed the policy at the time of payment. This may include where on your website this information is displayed as well as an invoice or a contract.
• Evidence that a cancellation request was not received during the time allowed in the disclosed cancellation policy.
• Positive Address Verification (AVS) and Card Verification Value (CVV) matches during authorization.
• Proof of product delivery to the cardholder. (Use of a delivery vendor that has tracking and requires a signature is advised.)
• Copies of receipts, invoices, or contracts, including a description of any products or services provided.
• Any communication with the cardholder regarding the purchase, including the cardholder's email address.
• A detailed description of the goods or services the cardholder agreed to at the time of purchase and a specific rebuttal to their claims of those being defective or not as described.
• Proof the cardholder downloaded goods from your company’s website, including the purchaser’s IP address, time, date, and device details.
• Proof card was used in a previously undisputed transaction.
• Evidence the cardholder or a member of their family has received and/or used the merchandise or services.
• Proof that a credit is not due to the cardholder.

For Visa consumer disputes, here is the recommended supporting evidence for each dispute reason code:

• 13.1 - At least one of the following:
  • Documentation to prove that the cardholder or authorized person received the merchandise or services as agreed.
  • Documentation showing the specified delivery date has not yet passed.
  • Documentation showing you were able to provide merchandise or service and that the cardholder cancelled prior to the delivery date.
  • Documentation showing the transaction was a partial payment with additional payments due.
• 13.2 - Proof that the bill in question covered services used by the customer between the date of the customer’s prior billing statement and the date the customer canceled.
• 13.3 - At least one of the following:
  • As much specific information and documentation as possible (invoice, contract, etc.) to prove that the goods or service was as described. It is recommended you address each point the cardholder has made.
  • If applicable, advise that you have not received the returned merchandise and the cardholder never attempted to return it or has not cancelled services. (Double check your incoming shipping records to verify this prior to response.)
  • Evidence that the cardholder agreed to repair or replacement; repair or replacement was received; and the repair or replacement has not since been disputed.
• 13.4 - Specific information and invoices showing the merchandise was not counterfeit.
• 13.5 - Documentation to prove the terms of sale were not misrepresented or, for investments evidence, that there are no funds to withdraw.
• 13.6 - Documentation showing the sale is valid and credit is not due and refuting the validity of the documentation supplied by the cardholder’s bank.
• 13.7 - At least one of the following:
  • Evidence that you never received or accepted the returned merchandise.
  • Documentation showing that your limited return or cancellation policy was properly disclosed and agreed to at the time of sale.
  • Documentation showing that your limited return or cancellation policy was properly disclosed and how the cardholder did not cancel according to the disclosed policy.
  • Evidence showing the cardholder continued to use services.
• 13.8 - Documentation or information showing the credit transaction was reversed.
• 13.9 - A copy of the ATM cash disbursement transaction or load transaction record containing at least the following:
  • an account number,
  • transaction time or sequential number identifying the individual transactions, and
  • an indicator confirming that the ATM cash disbursement or load transaction value was successful.

Related Transactions

A related transaction's reference number (reference_number) is required when you send one of the following responses:

• Response reason CP ("Credit Processed").

• Both reason detail code CE04 (“Digital goods download with time and date”) and the indicator prev_not_disputed (“Evidence that the same device and card used in the disputed transaction were used in any previous transaction that was not disputed”).

• Reason detail code CE13 (“Recurring transaction with a binding contract or previous undisputed recurring transactions and proof the cardholder is using the merchandise or service”).

• Reason detail code CE09 (“Evidence of one or more non-disputed payments for same merchandise or service”).

• Any response to Visa dispute reason code 10.4 or 13.1 in which previous transaction information is required.

Note that the reference number of more than one such transaction may be required to successfully challenge a dispute.

Two API requests help identify transactions related to a dispute:

• Get Credited Transaction Detail - Use the dispute's control number to search for associated credited transactions that occurred within the last 90 days.

• Get Non-Disputed Transaction - Use the dispute's control number to search for assoicated non-disputed transactions from the last 90 days.

The response data in the GET request response will include each transaction's reference_number as well as the transaction amount (amt_tran) for credits and the batch close date (batch_date) for debits.

Editing and Viewing a Dispute Response

You can view and edit a dispute response under the following conditions:

• To view, the dispute case must be a Retrieval Request (V) or a First-Time Chargeback (C) to which you have already responded.
• To edit, the dispute case must be a Retrieval Request (V) or a First-Time Chargeback (C) to which you have already responded, AND the dispute status must be Q ("Doc Under Review”).

To view a submitted dispute response, send a Get Submitted Dispute Response request.

To edit a dispute response, follow the steps in the Submit Dispute Response guide to POST a response. This response will overwrite your previous response.

Testing

This section provides information for testing your API disputes integration.

Create Test Disputes

Follow the Dispute API Create Dispute Data guide to create a test dispute for a select reason code. See the Test Dispute Data table in Dispute Conventions for available test dispute cases and their reason codes.

When you create a test dispute, the same data set is returned as in the response to a GET Disputes request. See GET Dispute Fields Returned in Dispute Conventions for a description of those fields.

Reset Test Disputes

Send a Reset Dispute Data request with the relevant dispute's control number (rec_id) to return the status of a test dispute case to 'New' (N). For example, use the endpoint https://api-test.maast.com/platform/dispute/393435800000003/reset, where 393435800000003 is the dispute's control number.

Go Live

See the Test and Go Live guide to perform all recommended tests of your API integration and to start transacting with a live production account.