# Reports source: https://developer.mastercard.com/ob-accept-payments/documentation/payments/reports/index.md The End of Day (EOD) Reconciliation process is a crucial component of financial integrity, ensuring that all transactional data spanning payments, refunds, mandates, and settlements are accurately logged, reconciled, and balanced at the close of each business day. This document provides comprehensive guidance on executing EOD reconciliation using the Reports API. The Reports API is designed for customers to access extensive data on all daily transactions, facilitating the accurate reconciliation of accounts, early fraud detection, and precise reporting for enhanced customer transparency. Clients and Merchants receive detailed reconciliation data following each day's issuance of batch onward payments, helping to maintain operational accuracy and financial transparency. #### Data flow {#data-flow} Diagram reports 1. Integrator sends a Create report request to Mastercard Open Finance Pay using the `/reports` endpoint. In the Create report request, the Integrator will specify the `mimeType` which denotes the format that the report will be returned in, the report type and the filtering that the Integrator wants to apply to the new report that will be generated. Details on report types and filtering can be found in STEP 3 - Create a new report below. 2. Mastercard Open Finance Pay returns the `reportId` that will be used by the Integrator to identify this specific report for other report related endpoints. 3. Mastercard Open Finance Pay sends a ReportStatusUpdated webhook to let the Integrator know that the status of the report has changed. This webhook will include the `reportId` of the report that has had a status change. 4. The Integrator calls the `/reports/{report_id}` endpoint using the `reportId` from the Create report response or the ReportStatusUpdated webhook to understand what the latest status of the report generation is. 5. Mastercard Open Finance Pay returns the latest status of the report generation. When the report reaches a status of `READY`, the Integrator can proceed to fetch the full report. 6. The Integrator calls the `/reports/{report_id}/items` endpoint using the `reportId` from the Create report response or the ReportStatusUpdated webhook to instruct Mastercard Open Finance Pay to return the report items. 7. Mastercard Open Finance Pay returns the report items in the format specified in the `mimeType` specified during the initial Create report request. #### STEP 1: Authenticate with the API {#step-1-authenticate-with-the-api} To use the API, you need to be authenticated with the service. You will need to make sure that you are using the **ob_reporting** scope in the request body when authenticating. Refer to [API Authentication](https://developer.mastercard.com/ob-accept-payments/documentation/developer-support/api-basics/authentication/index.md) for detailed instructions regarding how you can authenticate with the service. #### STEP 2: Call the Reports API {#step-2-call-the-reports-api} After the initial onboarding and authentication, you are ready to call the Reporting endpoints. Using the Reports API is an asynchronous process. This is because compiling large datasets can take some time. There are three steps: Create a Report (specify the filtering), get reports generation status and get actual data from reports. #### STEP 3: Create a new report {#step-3-create-a-new-report} API Reference: `POST /reports` When you call this endpoint, a `reportId` is generated and returned to the Integrator. The Generation of the requested report begins in the background. In step 4, you see how to fetch the latest status of the Report generation. When creating the report, `mimeType` is a mandatory field. Setting the `mimeType` determine the format that is used for the generation of the report. Currently, the only `mimeType` that is available is `application/json`. Setting `application/json` as the `mimeType` results in the report being returned in JSON format when calling Get report items described in Step 5. When creating a report, you need to specify the type of Report that you want to create. There are four different types of reports: * `Payments` A Report of type Payments generates a report that includes payment details. * `Mandates` A Report of type Mandates generates a report that includes mandate details. Access to Mandate reports is only available for Clients who have been configured for access to mandate functionality. * `Refunds` A Report of type Refunds generates a report that includes mandate details. Access to Refund reports is only available for Clients who have been configured for access to refund functionality * `Settlement` A Report of type Settlement generates a report that includes settlement payment details. Note: Access to Settlement reports is only available for clients who make use of Mastercard's Open Finance Settlement Service. When creating a Report, you can filter the content of the Report that is generated. The fields that can be used to filter a report depend on the report type that you are generating: ##### Filtering for reports of type Payments: {#filtering-for-reports-of-type-payments} | **Field** | **Description** | |-----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `createdDateFrom` | Items in the generated report are from the date specified here or later. | | `createdDateTo` | Items in the generated report are from the date specified here or earlier. | | `requestedDateFrom` | The generated report includes items where the `requestedDate` is on or after the date specified here. The date is the date that was requested by the Integrator when creating a payment. | | `lastUpdatedDateFrom` | The generated report includes items where the status was updated on or after the date specified here. | | `lastUpdatedDateTo` | The generated report includes items where the status was updated on or before the date specified here. | | `country` | Items in the generated report are from the country that is specified here. | | `statuses` | Items in the generated report have statuses that match the statuses passed in here. You can pass in a list of several statuses that you want to be returned in the report. The statuses that are applicable to each report type are specified below. | ##### Filtering for reports of type Mandates: {#filtering-for-reports-of-type-mandates} | **Field** | **Description** | |-------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `createdDateFrom` | Items in the generated report are from the date specified here or later. | | `createdDateTo` | Items in the generated report are from the date specified here or earlier. | | `country` | Items in the generated report are from the country that is specified here. | | `statuses` | Items in the generated report have statuses that match the statuses passed in here. You can pass in a list of several statuses that you want to be returned in the report. The statuses that are applicable to each report type are specified below. | ##### Filtering for reports of type Refunds: {#filtering-for-reports-of-type-refunds} | **Field** | **Description** | |-------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `createdDateFrom` | Items in the generated report are from the date specified here or later. | | `createdDateTo` | Items in the generated report are from the date specified here or earlier. | | `country` | Items in the generated report are from the country that is specified here. | | `statuses` | Items in the generated report have statuses that match the statuses passed in here. You can pass in a list of several statuses that you want to be returned in the report. The statuses that are applicable to each report type are specified below. | ##### Filtering for reports of type Settlement: {#filtering-for-reports-of-type-settlement} | **Field** | **Description** | |------------------------------|----------------------------------------------------------------------------| | `createdDateFrom` | Items in the generated report are from the date specified here or later. | | `createdDateTo` | Items in the generated report are from the date specified here or earlier. | | `country` | Items in the generated report are from the country that is specified here. | | `forwardSettlementReference` | Items in the generated report are related to this specific settlement. | ##### Statuses applicable to reports of type Payment: {#statuses-applicable-to-reports-of-type-payment} | **Status** | **Description** | |---------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `PREPARING` | The payment request details have been captured and the payment is ready to be authorized by the Payer. | | `AUTHORIZING` | The Payer is going through the payment authorization journey. | | `PROVIDER_PROCESSING` | The ASPSP received the payment request. We are awaiting confirmation that the payment has been initiated. | | `PENDING` | The ASPSP placed the payment in a pending state. Further action from the Payer may be required. | | `INITIATED` | The ASPSP validated and accepted the payment request. The payment has been scheduled for the provided payment date, or as soon as possible. | | `PAYMENT_EXECUTED_DEBITED` | The payment has been settled and debited from the Payer's account. | | `PAYMENT_EXECUTED_CREDITED` | The payment has been settled and we received confirmation that it was credited to the Payee's account. | | `CANCELLED` | The Payer either cancelled the payment at the authorization stage, did not proceed before the payment expired, or cancelled a scheduled future payment before it reached its execution date. The payment has not been executed. | | `FAILED` | The payment failed. More information about the cause of the failure may be available in the details.code and details.reason fields of the status object. | | `UNKNOWN` | It is no longer possible to refresh the payment status at the ASPSP. For confirmation of payment execution, perform reconciliation against transactions in the destination account. | | `AUTHORIZATION_FLOW_INCOMPLETE` | The payment authorization URL expired, or the Payer left the payment authorization page. The payment authorization has not been completed. | ##### Statuses applicable to reports of type Refunds: {#statuses-applicable-to-reports-of-type-refunds} | **Status** | **Description** | |-------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `PREPARING` | The refund request details have been captured and it is ready to be processed. | | `PENDING` | The refund is being processed by our settlement account provider. | | `PAYMENT_EXECUTED_DEBITED` | The payment has been settled and debited from the settlement account. | | `SOURCE_ACCOUNT_AVAILABLE` | The refund cannot be executed, but the source account is available. The source account details are provided as a set of payment rails so that the client can execute the refund themselves. | | `SOURCE_)ACCOUNT_UNAVAILABLE` | The refund cannot be executed and the source account cannot be obtained. | | `FAILED` | The refund failed. More information about the cause of the failure may be available in the details property within the code or reason. | ##### Statuses applicable to reports of type Mandates: {#statuses-applicable-to-reports-of-type-mandates} | **Status** | **Description** | |---------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------| | `PREPARING` | The mandate was just created. | | `AUTHORIZING` | The mandate has been created but is awaiting authorization. | | `AUTHORIZED` | The mandate is authorized and ready to be used. | | `CANCELLED` | The mandate was cancelled by the user before authorization finished. | | `INACTIVE` | The mandate is inactive, but not revoked. The mandate can reach this state if for example the end user is under KYC investigation. | | `FAILED` | The mandate is in a failed state. | | `REVOKED ` | The mandate has been revoked by bank. | | `AUTHORIZATION_FLOW_INCOMPLETE` | The mandate authorization was not completed in time. After a certain time, we consider that the user abandoned the flow to create the mandate. | | `EXPIRED` | Past the 'Valid To' date. | #### STEP 4: Get a report status {#step-4-get-a-report-status} API Reference: `GET /reports/{report_id}` Fetches the status of the Report generation by the `reportId`. In the following table, you can see the possible statuses that a report generation can be in: | **Status** | **Description** | |--------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `PROCESSING` | The report is still being processed and is not yet ready. You should not call the Get report items endpoint while the report is in a PROCESSING state. | | `READY` | The report generation is now complete and the report is ready to be consumed by your system. While a Report is in a READY state, you can proceed to call the Get report items endpoint. | | `FAILED` | Mastercard Open Finance Pay was unable to generate the report you requested. You should create a new report or reach out to our support team for more information. | Once Reports are available in a READY status, they are available for seven days from the `createdDate`. #### STEP 5: Get the report items {#step-5-get-the-report-items} API Reference: `GET /reports/{report_id}/items` Fetch the items of a Report by `reportId`. The Report needs to be in a READY status before you can fetch the Report items. The report items are returned in the format defined in the `mimeType` in step 3. The items returned in the report vary based on the report type that has been generated and the filtering used by the Integrator when creating the report. Refer to the [API reference](https://developer.mastercard.com/ob-accept-payments/documentation/api-reference/index.md) for a full description of the items that can be returned for a report. Below we describe the key points to consider for each report type. ##### Fetching items for reports of type Payments: {#fetching-items-for-reports-of-type-payments} When you fetch the items for a report of type Payments, the endpoint returns a collection of Payment objects that fall under the scope of the filtering defined by the integrator when creating the report in Step 3. Inside each payment object, the details for a specific payment are returned. ##### Fetching items for reports of type Mandates: {#fetching-items-for-reports-of-type-mandates} When you fetch the items for a report of type Mandates, the endpoint returns a collection of Mandate objects that fall under the scope of the filtering defined by the integrator when creating the report in Step 3. Inside each Mandate object, the details for a specific mandate are returned. ##### Fetching items for reports of type Refunds: {#fetching-items-for-reports-of-type-refunds} When you fetch the items for a report of type Refunds, the endpoint returns a collection of Refund objects that fall under the scope of the filtering defined by the integrator when creating the report in Step 3. Inside each Refund object, the details for a specific refund are returned. ##### Fetching items for reports of type Settlement: {#fetching-items-for-reports-of-type-settlement} When you fetch the items for a report of type Settlement, the endpoint returns: * A collection of Payment objects that fall under the scope of the filtering defined by the integrator when creating the report in Step 3. * A collection of Refund objects that fall under the scope of the filtering defined by the integrator when creating the report in Step 3. * A collection of of External Transaction objects that fall under the scope of the filtering defined by the integrator when creating the report in Step 3, ExternalTransactions are defined as transactions that happen outside of Mastercard Open Finance Pay on the Mastercard operated Settlement Account. An example of an external transaction would be a top-up payment made to the Mastercard operated Settlement Account.