# Claims tutorial
source: https://developer.mastercard.com/mastercom-extended/documentation/tutorials-and-guides/claims-tutorial/index.md

## Overview {#overview}

This tutorial will show you the process of an issuer or acquirer creating a claim, retrieving a list of claims, retrieving claim details, and changing the status of a claim. A claim contains events from the dispute lifecycle (chargebacks, representments, documents, adjustments) that are related to the same original transaction.
Tip: A claim is always associated with a transaction. You must have a transaction to create a claim.

#### What you will learn {#what-you-will-learn}

> * How to create a claim
> * How to retrieve a list of claims
> * How to retrieve claim details
> * How to change the status of a claim

## 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: Create a claim {#step-1-create-a-claim}

The issuer or acquirer uses this endpoint to create a new claim.
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.
API Reference: `POST /claims`

Use the `contextId` to create a claim. The `contextId` is returned by the transaction search. Refer to the [Transactions](https://developer.mastercard.com/mastercom-extended/documentation/tutorials-and-guides/seachtrans-tutorial/index.md) tutorial for details.
Tip: Customers must create a claim within 10 minutes of retrieving a transaction using POST /transactions/searches. If POST /claims is submitted more than 10 minutes after the transaction search is executed, the request is rejected and an error is returned. Rerun POST /transactions/searches and submit POST /claims within the 10-minute window to successfully create a claim.

To create a claim, create a `ClaimsApi` object. Use the method `claimsApi.createClaim` to create the claim.

This method expects the request body to be provided. The request body is an instantiation of the `CreateClaim` object.

```java
public class Main {
  public static void main(String[] args) {
    // API client set up here...    

    ClaimsApi claimsApi = new ClaimsApi(client);
    
    CreateClaim body = new CreateClaim();
    body.setContextId("TXN_63cef42e6f7711eaa77feeee0afdc116");
    body.setContextType(CreateClaim.ContextTypeEnum.TRANSACTION);

    try {
        ClaimCreateId result = claimsApi.createClaim(body);
        System.out.println(result.getClaimId());
    } catch (ApiException e) {
        System.err.println("Exception when calling ClaimsApi#createClaim");
        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       | RESOURCE_NOT_FOUND     | Resource not found for provided `contextId` value                                | 200005                                                                                                         |
| 400       | INVALID_FORMAT         | Invalid format for field `fieldName`                                             | 220000                                                                                                         |
| 400       | CLAIM_EXISTS_IN_LEGACY | Claim already exists as claim `fieldName`. Use Mastercom API to continue dispute | 220008                                                                                                         |
| 400       | INVALID_INPUT_VALUE    | Invalid input value for field `fieldName`                                        | 230000                                                                                                         |
| 400       | INVALID_INPUT_VALUE    | INVALID_INPUT_VALUE                                                              | 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 `contextId`                                               | 250000                                                                                                         |
| 401       | NOT_AUTHORIZED_REQUEST | User is not authorized                                                           | 200010                                                                                                         |

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 and the `claimId`.

After the claim is created, the `claimId` can be used to initiate a dispute.

## Step 2: Retrieve a list of claims {#step-2-retrieve-a-list-of-claims}

Issuers and acquirers use this endpoint to retrieve a list of claims.

API Reference: `POST /claims/searches`

To retrieve claims, create a `ClaimsApi` object. Then use method `claimsApi.searchClaim` to search for the claims for a given time period.

This method expects the request body to be provided. The request body is an instantiation of the `ClaimSearch` object.

```java
public class Main {
  public static void main(String[] args) {
    // API client set up here...    

    ClaimsApi claimsApi = new ClaimsApi(BaseClassUtil.getClient());
    
    ClaimSearch body = new ClaimSearch();
    body.setPrimaryAccountNumber("2241150000000842");
    body.setContextType(ContextTypeEnum.TRANSACTION);
    body.setStartDateTime(OffsetDateTime.now().withOffsetSameInstant(ZoneOffset.UTC).minusDays(40));
    body.setEndDateTime(OffsetDateTime.now().withOffsetSameInstant(ZoneOffset.UTC).minusDays(35));
    body.setLimit(25);
    body.setOffset(0);

    try {
      ClaimsList result = claimsApi.searchClaim(body);
      System.out.println(result);
    } catch (ApiException e) {
      System.err.println("Exception when calling ClaimsApi#claimSearch");
      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-1}

| HTTP Code |            Error             |                                                       Error Description                                                        |                                                   Error Code                                                   |
|-----------|------------------------------|--------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------|
| 400       | RESOURCE_NOT_FOUND           | Resource not found for provided `contextId` value                                                                              | 200005                                                                                                         |
| 400       | INVALID_FORMAT               | Invalid format for field `fieldName`                                                                                           | 220000                                                                                                         |
| 400       | MIN_SEARCH_CRITERIA          | Provide at minimum a `contextId`, `switchSerialNumber`, `primaryAccountNumber` or `acquirerReferenceNumber`                    | 220003                                                                                                         |
| 400       | MAX_SEARCH_CRITERIA          | Only one of `contextId`, `switchSerialNumber`, `primaryAccountNumber` or `acquirerReferenceNumber` can be provided per search. | 220006                                                                                                         |
| 400       | CONTEXT_TYPE_SEARCH_CRITERIA | The field `contextType` can only be used in conjunction with `contextId`.                                                      | 220007                                                                                                         |
| 400       | FNC_OR_BRN_MISSING_PAN       | The fields `financialNetworkCode` and `banknetReferenceNumber`can only be used in conjunction with `primaryAccountNumber`.     | 220011                                                                                                         |
| 400       | INVALID_INPUT_VALUE          | Invalid input value for field `fieldName`                                                                                      | 230000                                                                                                         |
| 400       | INVALID_INPUT_VALUE          | Minimum search date limit is `{{0}}` `{{1}}`                                                                                   | 230000                                                                                                         |
| 400       | INVALID_INPUT_VALUE          | Largest search window allowed is `{{0}}` `{{1}}`                                                                               | 230000                                                                                                         |
| 400       | INVALID_INPUT_VALUE          | The `endDateTime` cannot be before the `startDateTime`                                                                         | 230000                                                                                                         |
| 400       | INVALID_INPUT_VALUE          | Maximum search date limit is `{{0}}` `{{1}}`                                                                                   | 230000                                                                                                         |
| 400       | INVALID_INPUT_VALUE          | INVALID_INPUT_VALUE                                                                                                            | 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 `contextId`                                                                                             | 250000                                                                                                         |
| 401       | NOT_AUTHORIZED_REQUEST       | User is not authorized                                                                                                         | 200010                                                                                                         |

Review additional error codes [here](https://developer.mastercard.com/mastercom-extended/documentation/code-and-formats/errorsandexceptions/index.md).

#### Verify response {#verify-response-1}

You should receive a 200 OK response. Returns `ClaimsList.claimsData`.

## Step 3: Retrieve details for an existing claim {#step-3-retrieve-details-for-an-existing-claim}

Issuers and acquirers use this endpoint to retrieve details for an existing claim.

API Reference: `GET /claims/{claim_id}`

You can retrieve the claim details using the `claimId`. The `claimId` is required. The claim details contain Collaboration, transaction, chargeback, adjustment, representment and valid action details. Use the `ClaimsApi` class.

Note: PANs can be masked.

Optional: Provide the `claimId` and a list of `claimEntities` to be included in the result.   
> `claimEntities`:
>
> * TRANSACTION
> * TRANSACTION_REVERSAL
> * COLLABORATION
> * CHARGEBACK
> * CHARGEBACK_REVERSAL
> * ADJUSTMENT
> * ADJUSTMENT_REVERSAL
> * REPRESENTMENT
> * REPRESENTMENT_REVERSAL
> * CASE_FILING
> * SEND_PAYMENT
> * VALID_ACTIONS  
> * FEE_COLLECTION
> * GOOD_FAITH
> * REPORT_FRAUD  

If you do not provide any claim entities, all will be returned in the response.

To retrieve the claim details, call method `claimsApi.retrieveClaim(claimId, claimEntities, unmaskedResponseData)`.

```java
public class Main {
  public static void main(String[] args) {
    // Retrieve claim id here...

    ClaimsApi claimsApi = new ClaimsApi(client);

    String claimId = "713992756751";
    Boolean unmaskedResponseData = false;

    String[] claimEntitiesArray = {"TRANSACTION", "COLLABORATION", "VALID_ACTIONS"};
    List<String> claimEntities = Arrays.asList(claimEntitiesArray);

    try {
      ClaimDetails result = claimsApi.retrieveClaim(claimId, claimEntities, unmaskedResponseData);
      System.out.println(result);
    } catch (ApiException e) {
      System.err.println("Exception when calling ClaimsApi#retrieveClaim");
      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-2}

| HTTP Code |         Error          |                 Error Description                 |                                                   Error Code                                                   |
|-----------|------------------------|---------------------------------------------------|----------------------------------------------------------------------------------------------------------------|
| 400       | RESOURCE_NOT_FOUND     | Resource not found for provided `contextId` value | 200005                                                                                                         |
| 400       | INVALID_FORMAT         | Invalid format for field `fieldName`              | 220000                                                                                                         |
| 400       | INVALID_INPUT_VALUE    | Invalid input value for field `fieldName`         | 230000                                                                                                         |
| 400       | INVALID_INPUT_VALUE    | INVALID_INPUT_VALUE                               | 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                                                                                                         |
| 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-2}

You should receive a 200 OK response. Returns the `ClaimDetails`.

## Step 4: Change the status of a claim {#step-4-change-the-status-of-a-claim}

Issuers and acquirers use this endpoint to change the status of a claim.

API Reference: `PUT /claims/{claim_id}/status`

To change the status of a claim, create a `ClaimsApi` object. Then use the `claimsApi.changeClaimStatus` method.

This method expects the request body to be provided. The request body is an instantiation of `ClaimsApi` object.

This method does not have any response body.

```java
public static void main(String[] args) {
     //API client set up here...

             ClaimsApi claimsApi = new ClaimsApi(client);

             ChangeClaimStatus request = new ChangeClaimStatus();

             request.setStatus(ChangeClaimStatus.StatusEnum.REOPEN);

             try {
                //Reopen claim call has no return
                claimsApi.changeClaimStatus(request);
             } catch (ApiException e) {
                System.err.println("Exception when calling ClaimsApi#changeClaimStatus");
                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-3}

| HTTP Code |         Error          | Error Description  | Error Code |
|-----------|------------------------|--------------------|------------|
| 400       | INVALID_REQUEST        | Bad Request        | 200001     |
| 401       | NOT_AUTHORIZED_REQUEST | Unauthorized       | 200002     |
| 403       | FORBIDDEN              | Forbidden          | 220003     |
| 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-3}

You should receive a 204 Success - No Content response.

Return to [Tutorials](https://developer.mastercard.com/mastercom-extended/documentation/tutorials-and-guides/index.md).