# Initiate disputes tutorial source: https://developer.mastercard.com/mastercom-extended/documentation/tutorials-and-guides/disputeinitiate-tutorial/index.md ## Overview {#overview} This tutorial will show you the end-to-end flow of an issuer initiating a dispute and first chargeback. The flow includes the related steps of searching for transactions, creating a claim, retrieving claim details, uploading documents, and retrieving document details. #### What you will learn {#what-you-will-learn} > * How to initiate a dispute ## Before you start {#before-you-start} Before starting this tutorial, ensure that you have already completed the following: * [Mastercom Extended API Client Generation Tutorial](https://developer.mastercard.com/mastercom-extended/documentation/tutorials-and-guides/clientgeneration-tutorial/index.md) * [Quick Start Guide](https://developer.mastercard.com/mastercom-extended/documentation/quick-start-guide/index.md) ## Step 1: Search for transactions {#step-1-search-for-transactions} The issuer or acquirer searches for transactions. Note: The transaction search response will contain any claims in Mastercom Extended already associated with the transaction. Claims from the Mastercom API v6 system will not be included in this response. API Reference: `POST /transactions/searches` **Refer to [Step 1](https://developer.mastercard.com/mastercom-extended/documentation/tutorials-and-guides/seachtrans-tutorial/index.md) of the [Transactions](https://developer.mastercard.com/mastercom-extended/documentation/tutorials-and-guides/seachtrans-tutorial/index.md) tutorial for more specific information on how to use this endpoint.** ## Step 2: Create a claim {#step-2-create-a-claim} The issuer creates a claim for the selected transaction. Alert: If a claim has previously been created in Mastercom v6 for a transaction, an attempted Mastercom Extended Claim Creation API call (POST /claims) will yield an error message indicating a claim has already been created for this transaction in the Mastercom v6 system. **Refer to [Step 1](https://developer.mastercard.com/mastercom-extended/documentation/tutorials-and-guides/claims-tutorial/index.md) of the [Claims](https://developer.mastercard.com/mastercom-extended/documentation/tutorials-and-guides/claims-tutorial/index.md) tutorial for more specific information on how to use this endpoint.** API Reference: `POST /claims` ## Step 3: Retrieve the claim details from an existing claim {#step-3-retrieve-the-claim-details-from-an-existing-claim} The issuer retrieves the claim details from an existing claim. API Reference: `GET /claims/{claim_id}` **Refer to [Step 3](https://developer.mastercard.com/mastercom-extended/documentation/tutorials-and-guides/claims-tutorial/index.md) of the [Claims](https://developer.mastercard.com/mastercom-extended/documentation/tutorials-and-guides/claims-tutorial/index.md) tutorial for more specific information on how to use this endpoint.** ## Step 4: Upload documents {#step-4-upload-documents} The issuer uploads documents. API Reference: `POST /documents` **Refer to [Step 1](https://developer.mastercard.com/mastercom-extended/documentation/tutorials-and-guides/documents-tutorial/index.md) of the [Documents](https://developer.mastercard.com/mastercom-extended/documentation/tutorials-and-guides/documents-tutorial/index.md) tutorial for more specific information on how to use this endpoint.** ## Step 5: Initiate a dispute {#step-5-initiate-a-dispute} The issuer initiates a dispute and creates a first chargeback for the original transaction. API Reference: `POST /claims/{claim_id}/disputes` To initiate a dispute, create a `DisputesApi` object. Then use method `disputesApi.createDisputes` to raise the dispute. This method expects the `claimId` and request body to be provided. The request body is an instantiation of the `InitiateDispute` object. ```java public class Main { public static void main(String[] args) { // API client set up here... DisputesApi disputesApi = new DisputesApi(client); String claimId = "713992756751"; InitiateDispute body = new InitiateDispute(); body.setAutoChargeback(true); body.setDisputeAmount("10000"); body.setReasonCode("70"); ChargebackSingleMessage chargebackSingleMsg = new ChargebackSingleMessage(); chargebackSingleMsg.setControlNumber("99999"); body.setSingleMessage(chargebackSingleMsg); try { DisputesCreateEventId result = disputesApi.createDisputes(claimId, body); System.out.println(result.getEventId()); } catch (ApiException e) { System.err.println("Exception when calling DisputesApi#createDisputes"); System.err.println("Status code: " + e.getCode()); System.err.println("Reason: " + e.getResponseBody()); System.err.println("Response headers: " + e.getResponseHeaders()); e.printStackTrace(); } } } ``` #### Review the possible error codes associated with this request {#review-the-possible-error-codes-associated-with-this-request} | HTTP Code | Error | Error Description | Error Code | |-----------|--------------------------------------------------|------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------| | 400 | Invalid Field combination for dispute initiation | Invalid Field combination for dispute initiation. | 200003 | | 400 | INVALID_REQUEST | Action is invalid at this time. | 200007 | | 400 | INVALID_FORMAT | Invalid format for field `fieldName`. | 220000 | | 400 | INVALID_INPUT_VALUE | Invalid input value for field `fieldName`. | 230000 | | 400 | INVALID_INPUT_VALUE | Currency `fieldName` only allows `{{1}}` decimal places. | 230000 | | 400 | INVALID_INPUT_VALUE | Chargeback - The Security Bulletin Number supplied in request is not required for this reason code. | 230000 | | 400 | INVALID_INPUT_VALUE | Chargeback - The program supplied in request is not required for this reason code. | 230000 | | 400 | INVALID_INPUT_VALUE | File is not allowed when document indicator is false. | 230000 | | 400 | INVALID_INPUT_VALUE | Chargeback amount is higher than allowed. | 230000 | | 400 | INVALID_INPUT_VALUE | INVALID_INPUT_VALUE | 230000 | | 400 | INVALID_INPUT_VALUE | Selected `reasonCode` not allowed for this transaction. | 230000 | | 400 | INVALID_INPUT_VALUE | Selected `subReasonCode` not allowed for this transaction. | 230000 | | 400 | INVALID_INPUT_VALUE | `purchaseDisputeAmount` is higher than allowed. | 230000 | | 400 | INVALID_INPUT_VALUE | `cashBackDisputeAmount` is higher than allowed. | 230000 | | 400 | INVALID_INPUT_VALUE | `cashBackDisputeAmount` is not applicable for this transaction. | 230000 | | 400 | INVALID_INPUT_VALUE | Dispute on `cashBackDisputeAmount` not allowed. | 230000 | | 400 | INVALID_INPUT_VALUE | Dispute on `cashBackDisputeAmount` not allowed. | 230000 | | 400 | INVALID_INPUT_VALUE | Action is invalid at this time. | 230000 | | 400 | INVALID_INPUT_VALUE | Dispute not permitted beyond allowed days since transaction date. | 230000 | | 400 | INVALID_INPUT | Invalid input | 230004, 230005, 230006, 230007, 230008, 230009, 230010, 230011, 230012, 230013, 230014, 230015, 230016, 230017 | | 400 | MISSING_REQUIRED_INPUT | Missing required field `fieldName`. | 250000 | | 400 | MISSING_REQUIRED_INPUT | Missing required field `cashBackDisputeAmount`. | 250000 | | 400 | MISSING_REQUIRED_INPUT | `documentIndicator` is not valid. The `reasonCode` provided requires a supporting document to be attached. | 250000 | | 400 | MISSING_REQUIRED_INPUT | Missing required field `memberMessageText`. | 250000 | | 401 | NOT_AUTHORIZED_REQUEST | User is not authorized. | 200010 | | 404 | RESOURCE_UNKNOWN | Resource unknown | 200004 | | 404 | RESOURCE_NOT_FOUND | Resource not found. | 200005 | Review additional error codes [here](https://developer.mastercard.com/mastercom-extended/documentation/code-and-formats/errorsandexceptions/index.md). #### Verify response {#verify-response} You should receive a 201 Created response. Returns `eventId` and `eventType`:"CHARGEBACK". ### OPTIONAL: The issuer uploads and attaches the chargeback documentation (if not uploaded when the dispute was created). {#optional-the-issuer-uploads-and-attaches-the-chargeback-documentation-if-not-uploaded-when-the-dispute-was-created} Refer to [Step 1](https://developer.mastercard.com/mastercom-extended/documentation/tutorials-and-guides/documents-tutorial/index.md) and [Step 2](https://developer.mastercard.com/mastercom-extended/documentation/tutorials-and-guides/documents-tutorial/index.md) of the [Documents](https://developer.mastercard.com/mastercom-extended/documentation/tutorials-and-guides/documents-tutorial/index.md) tutorial for more specific information. ## Step 6: Upload documents {#step-6-upload-documents} The issuer uploads and attaches the chargeback documentation (if not uploaded when the dispute was created). API Reference: `POST /documents` **Refer to [Step 1](https://developer.mastercard.com/mastercom-extended/documentation/tutorials-and-guides/documents-tutorial/index.md) of the [Documents](https://developer.mastercard.com/mastercom-extended/documentation/tutorials-and-guides/documents-tutorial/index.md) tutorial for details.** ## Step 7: Retrieve document processing details {#step-7-retrieve-document-processing-details} The issuer retrieves the document processing details of the previously uploaded chargeback documentation. API Reference: `GET /documents/attributes` **Refer to [Step 3](https://developer.mastercard.com/mastercom-extended/documentation/tutorials-and-guides/documents-tutorial/index.md) of the [Documents](https://developer.mastercard.com/mastercom-extended/documentation/tutorials-and-guides/documents-tutorial/index.md) tutorial for more specific information on how to use this endpoint.** Return to [Tutorials](https://developer.mastercard.com/mastercom-extended/documentation/tutorials-and-guides/index.md).