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

## Overview {#overview}

This tutorial will show you the process of an acquirer or issuer managing documents for dispute events.

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

> * How to upload documents
> * How to attach documents
> * How to retrieve document details
> * How to retrieve processed documents

## 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: Upload documents {#step-1-upload-documents}

The issuer or acquirer uploads documents.

API Reference: `POST /documents`

To upload documents, create a `DocumentsApi` object. Then use method `documentsApi.uploadDocument` to upload the desired document.

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

The method returns a request body, which is an instantiation of the `DocumentUpload` object. This object contains the `documentUploadedId`.

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

    DocumentsApi documentsApi = new DocumentsApi(client);
    
    Document body = new Document();
    body.setFileName("testReport.csv");
    body.setFile("This is a file stored in a base64 encoded string");

    try {
      DocumentUpload result = documentsApi.uploadDocument(body);
      System.out.println(result);
    } catch (ApiException e) {
      System.err.println("Exception when calling DocumentsApi#uploadDocument");
      System.err.println("Status code: " + e.getCode());
      System.err.println("Reason: " + e.getResponseBody());
      System.err.println("Response headers: " + e.getResponseHeaders());
      e.printStackTrace();
    }
  }
}
```

#### Review file restrictions {#review-file-restrictions}

> File name restrictions:
>
> * Sixteen or fewer characters
> * English letters, numbers, hyphens, and underscores
> * Cannot contain spaces
> * Cannot contain account information like primary account numbers
> Supported file formats:
>
> * PDF
> * JPEG, JPG
> * ZIP
> * TIFF
> File size and resolution restrictions:
>
> * The total size of documents uploaded to an event within a claim cannot be larger than 14.5 MB or 14500000 bytes.
> * The resolution of any raster (pixel-based) file must not exceed 300 PPI.
> * The total size of any raster (pixel-based) file must not exceed 30,000,000 pixels.

#### Review the possible error codes associated with this request {#review-the-possible-error-codes-associated-with-this-request}

| HTTP Code |       Error Code       |    Description     |
|-----------|------------------------|--------------------|
| 400       | BAD_REQUEST            | Bad request        |
| 401       | NOT_AUTHORIZED_REQUEST | Unauthorized       |
| 403       | FORBIDDEN              | Forbidden          |
| 404       | RESOURCE_UNKNOWN       | Resource not found |

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 `documentUploadedId`. Use the `documentUploadedId` to attach uploaded document files to events.

## Step 2: Attach documents {#step-2-attach-documents}

The issuer or acquirer attaches previously uploaded documents to an existing dispute event.

API Reference: `PUT /claims/{claim_id}/events/{event_id}/documents`

To attach a previously uploaded document to an event, create a `DocumentsApi` object. Then use the `documentsApi.updateDocument` method.

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

This method does not have any response body.

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

    DocumentsApi documentsApi = new DocumentsApi(client); 
    
    Documents body = new Documents();
    body.setDocumentMemo("This is a sample memo");
    body.setDocumentUploadedId("978bc7d4ba0f11ee88eb2c6dc1fc6e5d");

    try {
      documentsApi.updateDocument(claimId, eventId, body);
    } catch (ApiException e) {
      System.err.println("Exception when calling DocumentsApi#updateDocument");
      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_FORMAT         | Invalid format for field `fieldName`                 | 220000                                                                                                         |
| 400       | INVALID_INPUT_VALUE    | Invalid input value for field `fieldName`            | 230000                                                                                                         |
| 400       | INVALID_INPUT_VALUE    | File is not allowed when document indicator is false | 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-1}

You should receive a 204 Success - No content response.

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

The issuer or acquirer retrieves the document processing details. Document processing details include details of the documents attached to events, including status.

API Reference: `GET /documents/attributes`

To get the details of the documents attached to events, create a `DocumentsApi` object. Then use method `documentsApi.getDocumentsAttributes`.

This method expects a query parameter containing a list of `eventIds` for which the customer would like to check the status.

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

    DocumentsApi documentsApi = new DocumentsApi(client); 
    
    List<String> eventIds = new ArrayList<>();
    eventIds.add("800000084386");

    try {
      DocumentAttributesList result = documentsApi.getDocumentsAttributes(eventIds);
      System.out.println(result);
    } catch (ApiException e) {
      System.err.println("Exception when calling DocumentsApi#getDocumentsAttributes");
      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       | 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                                                                                                         |

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: `claimId`, `eventId`, `documentStatus`, `documentCompletedId`, `documentCompletedFormat`, `documentCompletedFileName`, `documentCompletedFileSize`.

## Step 4: Retrieve processed documents {#step-4-retrieve-processed-documents}

The issuer or acquirer retrieves the processed documents.

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

To retrieve documents in a Base64 encoded format, create a `DocumentsApi` object. Then use method `documentsApi.retrieveDocument`.

This method expects a `documentCompletedId` to be provided. The `documentCompletedId` identifier can be obtained from [Step 3](https://developer.mastercard.com/mastercom-extended/documentation/tutorials-and-guides/documents-tutorial/index.md) leveraging `GET /documents/attributes`.

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

    DocumentsApi documentsApi = new DocumentsApi(client);

    try {
      DocumentRetrieve result = documentsApi.retrieveDocument(documentCompleteId);
      System.out.println(result);
    } catch (ApiException e) {
      System.err.println("Exception when calling DocumentsApi#retrieveDocument");
      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 Code       |    Description     |
|-----------|------------------------|--------------------|
| 400       | BAD_REQUEST            | Bad request        |
| 401       | NOT_AUTHORIZED_REQUEST | Unauthorized       |
| 403       | FORBIDDEN              | Forbidden          |
| 404       | RESOURCE_UNKNOWN       | Resource not found |

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 200 OK response. Returns `fileName` and `file`.

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