# Reports tutorial source: https://developer.mastercard.com/mastercom-extended/documentation/tutorials-and-guides/reports-tutorial/index.md ## Overview {#overview} This tutorial will show you the process of an acquirer or issuer searching, creating, and obtaining reports. #### What you will learn {#what-you-will-learn} > * How to retrieve a list of report fields > * How to retrieve report fields > * How to create a report > * How to search for reports > * How to retrieve the report status > * How to retrieve the completed report ## 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: Review standard report names and their associated ID and fields {#step-1-review-standard-report-names-and-their-associated-id-and-fields} Refer to the following table for details. | Standard report | ID | Fields | |----------------------------------------------------------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Acquirer Collaboration Unworked Report *Region: Global* | RD-00-1 | Claim ID Collaboration Event ID Collaboration Creation Date Collaboration ID Account Number Tokenized Primary Account Number Acquirer Reference Number Auth Code Collaboration Amount Currency Code (Alpha) Merchant Descriptor Refund/Reversal Date Refund/Reversal Type Refund/Reversal Amount Refund/Reversal Reference ID Refund/Reversal Currency Code (Alpha) Responded By Acquirer Response Code Acquirer Response Date Acquirer Response Due Date Acquirer ICA Switch Serial Number Acquirer Proc ID Acquirer Institution Number Issuer Proc ID Issuer Institution Number Settlement Date Claim Status Report Type | | Acquirer Collaboration Worked Report *Region: Global* | RD-00-2 | Claim ID Collaboration Event ID Collaboration Creation Date Collaboration ID Account Number Tokenized Primary Account Number Acquirer Reference Number Auth Code Collaboration Amount Currency Code (Alpha) Merchant Descriptor Refund/Reversal Date Refund/Reversal Type Refund/Reversal Amount Refund/Reversal Reference ID Refund/Reversal Currency Code (Alpha) Responded By Acquirer Response Code Acquirer Response Date Acquirer Response Due Date Acquirer ICA Switch Serial Number Acquirer Proc ID Acquirer Institution Number Issuer Proc ID Issuer Institution Number Settlement Date Claim Status Report Type | | Acquirer Collaboration Penalty Report *Region: Global* | RD-00-3 | Claim ID Collaboration Event ID Collaboration Creation Date Collaboration ID Account Number Tokenized Primary Account Number Acquirer Reference Number Auth Code Collaboration Amount Currency Code (Alpha) Merchant Descriptor Refund/Reversal Date Refund/Reversal Type Refund/Reversal Amount Refund/Reversal Reference ID Refund/Reversal Currency Code (Alpha) Responded By Acquirer Response Code Acquirer Response Date Acquirer Response Due Date Acquirer ICA Switch Serial Number Acquirer Proc ID Acquirer Institution Number Issuer Proc ID Issuer Institution Number Settlement Date Claim Status Report Type | | Acquirer Collaboration All Report *Region: Global* | RD-00-4 | Claim ID Collaboration Event ID Collaboration Creation Date Collaboration ID Account Number Tokenized Primary Account Number Acquirer Reference Number Auth Code Collaboration Amount Currency Code (Alpha) Merchant Descriptor Refund/Reversal Date Refund/Reversal Type Refund/Reversal Amount Refund/Reversal Reference ID Refund/Reversal Currency Code (Alpha) Responded By Acquirer Response Code Acquirer Response Date Acquirer Response Due Date Acquirer ICA Switch Serial Number Acquirer Proc ID Acquirer Institution Number Issuer Proc ID Issuer Institution Number Settlement Date Claim Status Report Type | | Debit Issuer Worked Report *Region: Global, India domestic* | RD-00-8 | Event ID Claim ID Account Number Tokenized Primary Account Number Dispute Amount Dispute Amount Currency Code (Alpha) Original Requested Amt Original Requested Amnt Currency Advice Reason Code Original Switch Serial Number Switch Serial Number Settlement Date Acquirer PROC ID Acquirer Institution No. ISSUER PROC Issuer Institution No. | | Debit Issuer Representment Unworked Report *Region: Global, India domestic* | RD-00-9 | Event ID Claim ID Account Number Tokenized Primary Account Number Dispute Amount Dispute Amount Currency Code (Alpha) Original Requested Amt Original Requested Amnt Currency Advice Reason Code Original Switch Serial Number Switch Serial Number Settlement Date Acquirer PROC ID Acquirer Institution No. ISSUER PROC Issuer Institution No. | | Debit Acquirer First Chargeback Unworked Report *Region: Global, India domestic* | RD-00-10 | Event ID Claim ID Account Number Tokenized Primary Account Number Dispute Amount Dispute Amount Currency Code (Alpha) Original Requested Amt Original Requested Amnt Currency Advice Reason Code Original Switch Serial Number Switch Serial Number Settlement Date Acquirer PROC ID Acquirer Institution No. ISSUER PROC Issuer Institution No. | | Debit Acquirer Worked Report *Region: Global, India domestic* | RD-00-11 | Event ID Claim ID Account Number Tokenized Primary Account Number Dispute Amount Dispute Amount Currency Code (Alpha) Original Requested Amt Original Requested Amnt Currency Advice Reason Code Original Switch Serial Number Switch Serial Number Settlement Date Acquirer PROC ID Acquirer Institution No. ISSUER PROC Issuer Institution No. | | Enhanced Reconciliation Report *Region: India domestic* | RD-00-12 | File ID Message Number Claim ID Event ID Card Issuer Reference Data Acquirer Reference Number MTI Primary Account Number Processing Code Function Code Message Reason Code Amount, Transaction Transaction Currency Code Transaction Currency Exponent Amount, Sender's DE 05 without fees Reconciliation Currency Code Reconciliation Currency Exponent Amount, Cardholder Billing Cardholder Billing Currency Code Cardholder Billing Currency Exponent Retrieval Reference Number Card Acceptor Business Code Card Acceptor ID Card Acceptor Name Date \& Time of Transaction Transaction Originator Institution ID Code Reversal Flag Conversion Rate Reconciliation Amounts, Original Original Amount Currency Code Original Amount Currency Exponent Amount, Transaction fee Clearing Date Clearing Cycle ID Transaction Status Amount, Reconciliation with fees Reconciliation Currency Code Reconciliation Currency Exponent Reason for Rejection Transaction Life Cycle ID Currency Conversion Assessment Amount Currency Conversion Assessment Currency Code Currency Conversion Assessment Currency Exponent GCMS Product Identifier Licensed Product Identifier Flex Code | | Credit Issuer Unworked Report *Region: India domestic* | RD-00-13 | Claim ID Event ID Event Type Card Issuer Reference Data Dispute Reconciliation Amount Dispute Reconciliation Currency Code (Numeric) Account Number Tokenized Primary Account Number Acquirer Reference Data Issuing ICA Acquiring ICA Business Processing Date Business Processing Cycle Reason Code Sub Reason Sub Reason Description Document Status Response Due Date | | Credit Issuer Worked Report *Region: India domestic* | RD-00-14 | Claim ID Event ID Event Type Card Issuer Reference Data Dispute Reconciliation Amount Dispute Reconciliation Currency Code (Numeric) Account Number Tokenized Primary Account Number Acquirer Reference Data Issuing ICA Acquiring ICA Business Processing Date Business Processing Cycle Reason Code Sub Reason Sub Reason Description Document Status Response Due Date | | Credit Acquirer Unworked Report *Region: India domestic* | RD-00-15 | Claim ID Event ID Event Type Card Issuer Reference Data Dispute Reconciliation Amount Dispute Reconciliation Currency Code (Numeric) Account Number Tokenized Primary Account Number Acquirer Reference Data Issuing ICA Acquiring ICA Business Processing Date Business Processing Cycle Reason Code Sub Reason Sub Reason Description Document Status Response Due Date | | Credit Acquirer Worked Report *Region: India domestic* | RD-00-16 | Claim ID Event ID Event Type Card Issuer Reference Data Dispute Reconciliation Amount Dispute Reconciliation Currency Code (Numeric) Account Number Tokenized Primary Account Number Acquirer Reference Data Issuing ICA Acquiring ICA Business Processing Date Business Processing Cycle Reason Code Sub Reason Sub Reason Description Document Status Response Due Date | | Pending Documentation Report *Region: Global, India domestic* | RD-00-17 | Claim ID Event ID Event Type Reason Code Account Number Tokenized Primary Account Number Acquirer Reference Data Creation Date Document Due Date Document Status Dispute Amount Dispute Amount Currency Code (Alpha) Original Switch Serial Number | ## Step 2: Retrieve a list of reports and their fields {#step-2-retrieve-a-list-of-reports-and-their-fields} Issuers and acquirers use this endpoint to retrieve a list of reports and their fields. API Reference: `GET /report-definitions` To retrieve a list of all the available report definitions, create a `ReportDefinitionsApi` object. Then use method `reportDefinitionsApi.getReportDefinitions`. This method does not require any input parameters or any request body. Optionally, the limit and offset can be provided. ```java public class Main { public static void main(String[] args) { // API client set up here... ReportDefinitionsApi reportDefinitionsApi = new ReportDefinitionsApi(client); try { ReportDefinitionList result = reportDefinitionsApi.getReportDefinitions(offset, limit); System.out.println(result); } catch (ApiException e) { System.err.println("Exception when calling ReportDefinitionsApi#getReportDefinitions"); 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 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 200 OK response. Returns report details. ## Step 3: Retrieve fields for a specific report {#step-3-retrieve-fields-for-a-specific-report} Issuers and acquirers use this endpoint to retrieve fields for a specific report. API Reference: `GET /report-definitions/{report_definition_id}` To retrieve the fields that could be returned on a particular report definition, create a `ReportDefinitionsApi` object. Then use method `reportsDefinitionsApi.getReportDefinition`. This method expects a `reportDefinitionId` to be provided in the path. ```java public class Main { public static void main(String[] args) { // API client set up here... ReportDefinitionsApi reportDefinitionsApi = new ReportDefinitionsApi(client); try { ReportDefinition result = reportDefinitionsApi.getReportDefinition(reportDefinitionId); System.out.println(result); } catch (ApiException e) { System.err.println("Exception when calling ReportDefinition#getReportDefinition"); 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 | |-----------|--------------------|----------------------------------|------------| | 403 | FORBIDDEN | Unable to Authorize User | 200010 | | 404 | RESOURCE_NOT_FOUND | `report_definition_id` 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 200 OK response. Returns details of specific report. ## Step 4: Create a report {#step-4-create-a-report} Issuers and acquirers use this endpoint to request the creation of a report. Note: The system requires at least 120 seconds to generate a report. API Reference: `POST /reports` To create a report, create a `ReportsApi` object. Then use method `reportsApi.createReport` to request a report to be generated. This method expects the request body to be provided. The request body is an instantiation of the `ReportsCreate` object. ```java public class Main { public static void main(String[] args) { // API client set up here... ReportsApi reportsApi = new ReportsApi(client); List filterValues = new ArrayList<>(); filterValues.add("1234"); filterValues.add("5678"); ReportFilter filter = new ReportFilter().filterName(FilterNameEnum.ICA).filterValues(filterValues); List reportFilters = new ArrayList<>(); reportFilters.add(filter); ReportsCreate body = new ReportsCreate(); body.setReportDefinitionId("RD-00-1"); body.setFormat(ReportsCreate.FormatEnum.CSV); body.setFilters(reportFilters); try { CreatedReportDetails result = reportsApi.createReport(body); System.out.println(result); } catch (ApiException e) { System.err.println("Exception when calling ReportsApi#createReport"); 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_INPUT_LENGTH | Invalid input list length for FGA criteria | 210000 | | 400 | INVALID_INPUT_VALUE | Invalid input value for field `format` | 230000 | | 400 | INVALID_INPUT_VALUE | The `END_DATE` cannot be before the `START_DATE` | 230000 | | 400 | INVALID_INPUT_VALUE | `fieldName` is not supported by the report definition | 230000 | | 400 | INVALID_INPUT_VALUE | Report for `dataFilter:EVENT_REASON_CODE` is not allowed. | 230000 | | 400 | INVALID_INPUT_VALUE | Only one FGA criteria can be provided per request | 230000 | | 400 | MISSING_REQUIRED_INPUT | Missing required field `dataFilter:EVENT_REASON_CODE`. | 250000 | | 400 | MISSING_REQUIRED_INPUT | Missing required field `dataFilter:CYCLE_ID`. | 250000 | | 400 | INVALID_INPUT | Invalid input | 230004 | | 400 | Missing required field `START_DATE` | Missing required field `criteria.START_DATE` | 250000 | | 400 | Missing required field `criteria.END_DATE` | Missing required field `criteria.END_DATE` | 250000 | | 400 | MISSING_REQUIRED_FIELD | Missing required field `fieldName` | 250000 | | 401 | NOT_AUTHORIZED_REQUEST | User is not authorized | 200010 | | 404 | RESOURCE_NOT_FOUND | `report_definition_id` 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 201 Created response. Returns `reportRequestId`. ## Step 5: Search for reports {#step-5-search-for-reports} Issuers and acquirers use this endpoint to obtain a report status and reportCompletedId. API Reference: `POST /reports/searches` To search for a report, create a `ReportsApi` object. Then use method `reportsApi.searchReport`. This method expects the request body to be provided. The request body is an instantiation of the `ReportSearch` object. ```java public class Main { public static void main(String[] args) { // API client set up here... ReportsApi reportsApi = new ReportsApi(client); ReportSearch body = new ReportSearch(); body.setReportDefinitionIds(Collections.singletonList("RD-00-1")); body.setStartDateTime(OffsetDateTime.now().withOffsetSameInstant(ZoneOffset.UTC).minusDays(40).toString()); body.setEndDateTime(OffsetDateTime.now().withOffsetSameInstant(ZoneOffset.UTC).minusDays(25).toString()); body.setReportStatus(com.mastercard.mastercomextended.model.ReportSearch.ReportStatusEnum.PENDING); body.setSortKey(com.mastercard.mastercomextended.model.ReportSearch.SortKeyEnum.CREATED_DATE_TIME); body.setSortOrder(com.mastercard.mastercomextended.model.ReportSearch.SortOrderEnum.ASC); body.setOffset(0); body.setLimit(10); try { ReportList result = reportsApi.searchReport(body); System.out.println(result); } catch (ApiException e) { System.err.println("Exception when calling ReportsApi#searchReport"); 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_INPUT | Invalid input | 230004 | | 404 | RESOURCE_NOT_FOUND | `report_request_id` 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 200 OK response. Returns information pertaining to the specific report, including `reportStatus` and `reportCompletedId`. ## Step 6: Retrieve report status {#step-6-retrieve-report-status} Issuers and acquirers use this endpoint to retrieve the status of a specific report. API Reference: `GET /reports/{report_request_id}/status` To retrieve the status of a report, create a `ReportsApi` object. Then use method `reportsApi.getReportStatus`. This method expects `reportRequestId` to be provided on the path. ```java public class Main { public static void main(String[] args) { // API client set up here... ReportsApi reportsApi = new ReportsApi(client); try { ReportsStatus result = reportsApi.getReportStatus(reportRequestId); System.out.println(result); } catch (ApiException e) { System.err.println("Exception when calling ReportsApi#getReportStatus"); 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-4} | HTTP Code | Error | Error Description | Error Code | |-----------|------------------------|------------------------|------------| | 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-4} You should receive a 200 OK response. Returns `reportStatus`. ## Step 7: Retrieve a completed report {#step-7-retrieve-a-completed-report} Issuers and acquirers use this endpoint to retrieve a completed report. API Reference: `GET /reports/{report_completed_id}` To retrieve a completed report, create a `ReportsApi` object. Then use method `reportsApi.getReport`. This method expects a `reportCompletedId` to be provided on the path. The `reportCompletedId` identifier can be obtained from [Step 5](https://developer.mastercard.com/mastercom-extended/documentation/tutorials-and-guides/reports-tutorial/index.md) leveraging `GET /reports/{report_request_id}/status`. ```java public class Main { public static void main(String[] args) { // API client set up here... ReportsApi reportsApi = new ReportsApi(client); try { Report result = reportsApi.getReport(body); System.out.println(result); } catch (ApiException e) { System.err.println("Exception when calling ReportsApi#getReport"); 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-5} | HTTP Code | Error | Error Description | Error Code | |-----------|------------------------|-------------------------------|------------| | 401 | NOT_AUTHORIZED_REQUEST | User is not authorized | 200010 | | 404 | RESOURCE_NOT_FOUND | `report_request_id` 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-5} You should receive a 200 OK response. Returns `fileName` and the `file` of the completed report. Return to [Tutorials](https://developer.mastercard.com/mastercom-extended/documentation/tutorials-and-guides/index.md).