# Mastercard Processing Dispute APIs
source: https://developer.mastercard.com/mastercard-processing-dispute/documentation/index.md

## Overview {#overview}

The Mastercard Processing Dispute API provides APIs exposed by the Mastercard Processing Dispute Assistant Module (DAM). DAM is an extension to the Workbench 3.0 application suite, the Graphic User Interface (GUI) of our Card Management System (CMS).

DAM is an innovative tool designed to enhance and simplify the dispute case management and chargeback raising process. The DAM tool is integrated with the payment network through API (Mastercom in case of Mastercard) as per payment network specification, which supports the whole, end-to-end chargeback cycle.

Disputes may arise when specific cardholder transactions are called into question. There are three main reasons for disputes:

* Fraudulent transactions
* Billing errors
* Service not rendered or bad service level

The dispute is a formal way to clear up suspicious transactions and ambiguities to agree on facts. In most cases, it leads to posting back charged amounts due to a chargeback.

A chargeback is a formal procedure established by payment schemes. A chargeback allows a cardholder to recover money from disputed, card-based transactions. A chargeback transaction is a financial record initiated and sent by the bank that issued the payment card to the merchant through a payment scheme. If both the issuer and the acquirer cannot agree, the dispute case can be escalated to the case filing stage, called arbitration. During arbitration, the payment scheme acts as a conciliator and decides which party to the dispute is right. Chargeback rules and procedures are established and well described in the payment scheme regulations, for example, the *Chargeback Guide* for Mastercard transactions.

## Glossary and Conventions {#glossary-and-conventions}

### Glossary {#glossary}

The glossary explains the various terms and definitions, and the acronyms used throughout this documentation.

|    **Term**    |                                                                     **Definition**                                                                     |
|----------------|--------------------------------------------------------------------------------------------------------------------------------------------------------|
| API            | Application Programming Interface                                                                                                                      |
| Cardholder     | An individual who is the card user is usually also the card owner.                                                                                     |
| CMS            | Card Management System                                                                                                                                 |
| DAM            | Dispute Assistant Module is an extension to the CMS GUI.                                                                                               |
| Issuer         | The institution, bank, or fintech that issues a card.                                                                                                  |
| JSON           | JavaScript Object Notation                                                                                                                             |
| JWE            | JSON Web Encryption                                                                                                                                    |
| MP             | Mastercard Processing is a processor.                                                                                                                  |
| operationId    | It is a unique name for a particular API operation. It is usually in the form of text expressing the name of an operation (for example, `createCard`). |
| OAS            | The OpenAPI Specification is the documentation of an API constructed by the Open API 3.0 standard.                                                     |
| Processor      | It is a company providing services for issuers related to card issuance, card management, and processing transactions.                                 |
| Trusted amount | It is a part of the transaction amount that is not disputed by the cardholder.                                                                         |

### Formatting Conventions {#formatting-conventions}

We use plain text names for our system objects (for example, account contract). For technical descriptions, we frame words in adherence to the OpenAPI Specification (OAS) naming conventions. Framed words can refer to:

* Field names required in API requests: `reasonCode`.
* API methods and operationIds: `POST`, `createDisputeCase`.
* Actors: issuer, processor, payment network, acquirer, and cardholder are in lower-case letters.

### REST Naming Conventions {#rest-naming-conventions}

|  **Term**   |                                              **Definition**                                              |
|-------------|----------------------------------------------------------------------------------------------------------|
| method      | An HTTP request method, such as `POST` or `GET`.                                                         |
| operation   | A specific procedure that is invoked on an object using a method.                                        |
| endpoint    | A path or address that the API exposes for your requests. A single path can support multiple operations. |
| operationId | A unique name used to identify a specific operation (for example, `createDisputeCase`).                  |

Mastercard Processing Dispute API specification uses the following case format:

|      Term       |    Case    |     Example      |
|-----------------|------------|------------------|
| Property names  | camelCase  | reasonCode       |
| Path parameters | snake_case | case_id          |
| Path segments   | kebab-case | /trusted-amounts |

## How It Works {#how-it-works}

Your Dispute team has access to DAM in the Workbench, the GUI of our CMS. DAM is the primary tool to manage disputes and chargebacks. Mastercard Processing provides the Dispute API, which supports you in efforts to enhance effectiveness by automatization of processes. A cardholder can initiate a dispute process and check information about its status in the mobile banking app or web portal. At the same time, your Dispute team will access newly created cases through DAM. Connecting the mobile banking app with the Dispute API will enhance the cardholder's experience and simplify your Dispute team's work.

There are two models of cooperation with Mastercard Processing for dispute management:

* [On-behalf model](https://developer.mastercard.com/mastercard-processing-dispute/documentation/index.md#on-behalf-model)
* [Self-service model](https://developer.mastercard.com/mastercard-processing-dispute/documentation/index.md#self-service-model)

### On-behalf model {#on-behalf-model}

The Mastercard Processing Chargeback team is responsible for processing dispute claims and raising chargebacks to the Schemes on behalf of the Issuer. The communication between the parties happens only within DAM to boost the effectiveness and simplicity of the process from your perspective.  

![](https://static.developer.mastercard.com/content/mastercard-processing-dispute/uploads/dam-on-behalf-new.png)

**Diagram description**

1. The cardholder disputes a transaction.
2. The dispute is reported in the Issuer's back-end through an available channel.
3. The dispute case is created in DAM.
4. The Issuer Dispute team analyses the request and initiates the process.
5. The Mastercard Processing Dispute team analyses the case and initiates a chargeback.
6. The chargeback is sent through API to Mastercom.
7. The chargeback is processed as per Mastercard rules.
8. The chargeback status is updated.
9. Clearing files are processed by Mastercard Processing and shared with the Issuer.
10. The Issuer credits the cardholder.

**Flow**

When a dispute case is created through API in CMS, it is visible in DAM. Therefore, your Dispute team can analyze it and decide whether to process it further, terminate it, or create a chargeback case. The Mastercard Processing Chargeback team receives your team's decision in DAM, analyzes the case, performs further steps toward the chargeback procedure, and prepares data to be sent by our CMS to the payment network (for example, Mastercom). You will be notified in DAM about all steps taken in the chargeback process.

### Self-service model {#self-service-model}

In the self-service model, your Dispute team is responsible for the complete dispute process.  

![](https://static.developer.mastercard.com/content/mastercard-processing-dispute/uploads/dam-self-service-new.png)

**Diagram description**

1. The cardholder disputes a transaction.
2. The dispute is reported in the Issuer's back-end through an available channel.
3. The dispute case is created in DAM.
4. The Issuer Dispute team analyses the request and initiates a chargeback.
5. The chargeback is sent through API to Mastercom.
6. The chargeback is processed as per Mastercard rules.
7. The chargeback status is updated.
8. Clearing files are processed by Mastercard Processing and shared with the Issuer.
9. The Issuer credits the cardholder.

**Flow**

When a dispute case is created through API in CMS, it is visible in DAM. Therefore, your Dispute team can analyze it and decide whether to process it further or terminate it. In case of a decision to raise a chargeback, your team analyzes the case, collects all needed data, and marks the case in DAM to be sent from our CMS to the payment network (for example, Mastercom). You will be notified in DAM about all steps taken in the chargeback process.

Despite the cooperation mode, you can use our solution to keep complete records of disputes effectively and have full access to the data needed in the process.

Although DAM gives your team a lot of flexibility in case management, you can access it in a more automated way through the Mastercard Processing Dispute API to:

* Create a dispute case for a given transaction.
* Add files to the created dispute case.
* Change the amount of the dispute case (only available in the self-service model).
* Retrieve dispute case details, including current status.

Note: During the dispute and chargeback process, Mastercard Processing:

* Communicates with you through DAM, the primary source of knowledge and management tool.
* Provides the Dispute API to enhance cardholder experience and automate customer service.
* Sends files in a format defined by industry standards through ETL to a location dedicated to you on our FTP.

## Next Steps {#next-steps}

* Review the [Quick Start Guide](https://developer.mastercard.com/platform/documentation/getting-started-with-mastercard-apis/quick-start-guide/) to learn how to use the Mastercard Developers platform.
* See [API Basics](https://developer.mastercard.com/mastercard-processing-dispute/documentation/api-basics-section/index.md) to learn more about authentication and encryption.
* See the [Tutorials](https://developer.mastercard.com/mastercard-processing-dispute/documentation/tutorials-and-guides/index.md) to learn how to get access to the API or build an end-to-end API application.
* Review the [Use Cases](https://developer.mastercard.com/mastercard-processing-dispute/documentation/use-cases/index.md), their implementations, and sequence diagrams.
* Use the [API Reference](https://developer.mastercard.com/mastercard-processing-dispute/documentation/api-reference/index.md) to review the OpenAPI Specification and execute each API endpoint.
* Review the [Error Codes](https://developer.mastercard.com/mastercard-processing-dispute/documentation/code-and-formats/index.md) and the formats that we use.
* Review [Support](https://developer.mastercard.com/mastercard-processing-dispute/documentation/support/index.md) to find answers to questions and get technical support.