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

## Overview {#overview}

This tutorial will show you the end-to-end flow of an acquirer creating a representment in response to a first chargeback. The flow includes the related steps of retrieving claim details, retrieving chargeback documents, acknowledging chargebacks, uploading documents, and retrieving document details.

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

> * How to create a representment
> * How to update (acknowledge) a representment
> * How to reverse a representment
> * How to update a representment reversal (*Applicable only for customers in India processing domestic disputes.*)

## 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: Retrieve list of claims within a queue {#step-1-retrieve-list-of-claims-within-a-queue}

The acquirer retrieves a list of claims from the Acquirer First Chargeback Unworked queue.

API Reference: `GET /queues/{queue_id}/claims`

**Refer to [Step 4](https://developer.mastercard.com/mastercom-extended/documentation/tutorials-and-guides/queues-tutorial/index.md) of the [Queues](https://developer.mastercard.com/mastercom-extended/documentation/tutorials-and-guides/queues-tutorial/index.md) tutorial for more specific information on how to utilize this endpoint.**

## Step 2: Retrieve the claim details from an existing claim {#step-2-retrieve-the-claim-details-from-an-existing-claim}

The acquirer retrieves the claim details for an existing claim and its associated events.

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 3: Retrieve chargeback documents {#step-3-retrieve-chargeback-documents}

The acquirer retrieves the processed documents attached to the chargeback.

API Reference: `GET /documents/{document_completed_id}`

**Refer to [Step 4](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 4: Acknowledge chargebacks {#step-4-acknowledge-chargebacks}

The acquirer acknowledges the received chargebacks to move the claim from Acquirer First Chargeback Unworked queue to Acquirer Worked queue.
Note: The acquirer may take further actions on acknowledged chargebacks.
API Reference: `PUT /claims/{claim_id}/chargebacks/{event_id}`

**Refer to [Step 1](https://developer.mastercard.com/mastercom-extended/documentation/tutorials-and-guides/chargebacks-tutorial/index.md) of the [Chargebacks](https://developer.mastercard.com/mastercom-extended/documentation/tutorials-and-guides/chargebacks-tutorial/index.md) tutorial for more specific information on how to use this endpoint.**

## Step 5: Upload documents {#step-5-upload-documents}

The acquirer 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 6: Create a representment {#step-6-create-a-representment}

Acquirers use the endpoint to create a representment. A claim and a chargeback submitted to the claim are required to create a representment.

API Reference: `POST /claims/{claim_id}/chargebacks/{event_id}/representments`

To create a representment, create a `RepresentmentsApi` object. Then use method `representmentsApi.representmentCreate` to create the representment.

This method expects the `claimId`, `eventId` and request body to be provided. The request body is an instantiation of a `RepresentmentCreate` object.

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

    RepresentmentsApi representmentsApi = new RepresentmentsApi(client);
    
    String claimId = "713992756751";
    String eventId = "814345676342";
    
    RepresentmentSingleMessage representmentSingleMessage = new RepresentmentSingleMessage();
    representmentSingleMessage.setControlNumber("99999");

    RepresentmentCreate body = new RepresentmentCreate();
    body.setDisputeAmount("10000");
    body.setReasonCode("13");
    body.documentIndicator(false);
    body.additionalInformation("MULTIPLE AUTH REQUESTS");
    body.setSingleMessage(representmentSingleMessage);
    
    try {
        RepresentmentCreatEventId result = representmentsApi.representmentCreate(claimId, eventId, body);
        System.out.println(result.getEventId());
    } catch (ApiException e) {
        System.err.println("Exception when calling RepresentmentsApi#representmentCreate");
        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_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    | File is not allowed when document indicator is false            | 230000                                                                                                         |
| 400       | INVALID_INPUT_VALUE    | Representment amount is higher than allowed                     | 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                                                                                                         |
| 400       | INVALID_INPUT_VALUE    | Selected `reasonCode` not allowed for this transaction.         | 230000                                                                                                         |
| 400       | MISSING_REQUIRED_INPUT | Missing required field `cashBackDisputeAmount`.                 | 250000                                                                                                         |
| 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                                                                                                         |

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`.

## Step 7: Retrieve the document processing details {#step-7-retrieve-the-document-processing-details}

The acquirer retrieves the document processing details of the previously uploaded representment 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.**

## Step 8: Acknowledge a representment {#step-8-acknowledge-a-representment}

Issuers use this endpoint to acknowledge a representment that has been submitted. The issuer acknowledges the received representment to move the claim from the Issuer Representment Unworked queue to the Issuer Worked queue.

*Applicable only for customers in India processing domestic disputes* :  

Acquirers use this endpoint to acknowledge a rejected representment that was previously submitted. This moves the claim from the Reject queue to the Acquirer Worked queue.
Note: The issuer may take further actions on acknowledged representments.
API Reference: `PUT /claims/{claim_id}/representments/{event_id}`

To update a representment, create a `RepresentmentsApi` object. Then use method `representmentsApi.updateRepresentment` to acknowledge the representment.

This method expects the `claimId`, `eventId` and request body to be provided. The request body is an instantiation of a `RepresentmentUpdate` object.

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

    RepresentmentsApi representmentsApi = new RepresentmentsApi(client);
    
    String claimId = "713992756751";
    String eventId = "800000152099";
    
    RepresentmentUpdate body = new RepresentmentUpdate();
    body.setAcknowledge(true);
    
    try {
        // Update representment call has no return
        representmentsApi.updateRepresentment(claimId, eventId, body);
    } catch (ApiException e) {
        System.err.println("Exception when calling RepresentmentsApi#updateRepresentment");
        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       | 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    | INVALID_INPUT_VALUE                       | 230000                                                                                                         |
| 400       | INVALID_INPUT          | Invalid input                             | 230004, 230005, 230006, 230007, 230008, 230009, 230010, 230011, 230012, 230013, 230014, 230015, 230016, 230017 |
| 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-1}

You should receive a 204 Success - No content response.

## Step 9: Reverse a representment {#step-9-reverse-a-representment}

Acquirers use this endpoint to reverse existing representments. If a previously created representment is no longer needed, acquirers can use this endpoint to reverse the representment.

API Reference: `POST /claims/{claim_id}/representments/{event_id}/reversals`

To reverse a representment, create a `RepresentmentsApi` object. Then use method `representmentsApi.reverseRepresentment` to reverse the representment.

This method expects the `claimId`, `eventId` and request body to be provided. The request body is an instantiation of a `RepresentmentReversal` object.

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

    RepresentmentsApi representmentsApi = new RepresentmentsApi(client);
    
    String claimId = "713992756751";
    String eventId = "800000152099";
    
    RepresentmentSingleMessageReversal representmentSingleMessageReversal = new RepresentmentSingleMessageReversal();
    representmentSingleMessageReversal.setControlNumber("99999");

    RepresentmentReversal body = new RepresentmentReversal();
    body.setReasonCode("06");
    body.setSingleMessage(representmentSingleMessageReversal);
    
    try {
        RepresentmentReversalEventId result = representmentsApi.reverseRepresentment(claimId, eventId, body);
        System.out.println(result.getEventId());
    } catch (ApiException e) {
        System.err.println("Exception when calling RepresentmentsApi#reverseRepresentment");
        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       | MISSING_REQUIRED_INPUT | Missing required field `singleMessage.reversalReasonCode` | 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    | 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                                                                                                         |

\|400\|MISSING_REQUIRED_INPUT\|Missing required field `singleMessage.reversalReasonCode`\|200003\|

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 201 Created response. Returns the `eventId`.

## Step 10: Update a representment reversal {#step-10-update-a-representment-reversal}

*Applicable only for customers in India processing domestic disputes.*

Acquirers use this endpoint to acknowledge a rejected representment reversal that was previously submitted. This moves the claim from the Reject queue to the Acquirer Worked queue.

API Reference: `PUT /claims/{claim_id}/representments/{event_id}/reversals`

To update a representment reversal, create a `RepresentmentsApi` object. Then use method `representmentsApi.updateRepresentmentReversal` to update the representment reversal.

This method expects the `claimId`, `eventId` and request body to be provided. The request body is an instantiation of a `RepresentmentReversalUpdate` object.

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

    RepresentmentsApi representmentsApi = new RepresentmentsApi(client);

    String claimId = "713992756751";
    String eventId = "800000152099";

    RepresentmentReversalUpdate body = new RepresentmentReversalUpdate();
    body.setAcknowledgeReject(true);

    try {
      // Update representment reversal call has no return
      representmentsApi.updateRepresentmentReversal(claimId, eventId, body);
    } catch (ApiException e) {
      System.err.println("Exception when calling RepresentmentsApi#updateRepresentmentReversal");
      System.err.println("Status code: " + e.getCode());
      System.err.println("Reason: " + e.getResponseBody());
      System.err.println("Response headers: " + e.getResponseHeaders());
      e.printStackTrace();
    }
  }
}public class Main {
  public static void main(String[] args) {
    // API client set up here...

    RepresentmentsApi representmentsApi = new RepresentmentsApi(client);

    String claimId = "713992756751";
    String eventId = "800000152099";

    RepresentmentReversalUpdate body = new RepresentmentReversalUpdate();
    body.setAcknowledgeReject(true);

    try {
      // Update representment reversal call has no return
      representmentsApi.updateRepresentmentReversal(claimId, eventId, body);
    } catch (ApiException e) {
      System.err.println("Exception when calling RepresentmentsApi#updateRepresentmentReversal");
      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        | 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    | 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).

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).