# Create a Payment Report
source: https://developer.mastercard.com/ob-accept-payments/documentation/tutorials-and-guides/create-payment-report-tutorial/index.md

This guide walks you through creating a payment report, fetching the latest status of a report, and fetching the items of a report once they are ready.

Please find more detailed specification for this scenario, in the Reports section.

## Prerequisites {#prerequisites}

* You have been onboarded to Open Finance and obtained a `destinationId` to receive payments. Refer to the [Quick Start](https://developer.mastercard.com/ob-accept-payments/documentation/quickstart/index.md) guide.
* You have successfully processed payments in the environment you want to generate the report in.
* You have successfully authenticated with the API using the `ob_reporting` scope in the request body. Refer to the [Authentication](https://developer.mastercard.com/ob-accept-payments/documentation/api-basics/index.md) guide.

## Step 1 - Consider the Type of Report That You Want to Generate {#step-1---consider-the-type-of-report-that-you-want-to-generate}

When creating a new report, you need to specify the `reportType` you want to generate. For the purpose of this tutorial we will specify the report type as `Payments`. A report of type `Payments` returns information on all of the payments that were made within the filtering criteria set by you when creating the report.
Note: You can also generate reports of type `Mandates`, `Refunds` and `Settlement`. Refer to [Reports](https://developer.mastercard.com/ob-accept-payments/documentation/payments/reports/index.md) for more information.

## Step 2 - Consider the Format in Which You Would Like the Report Generated {#step-2---consider-the-format-in-which-you-would-like-the-report-generated}

When creating a new report, you need to specify the `mimeType` of the report to be generated. The `mimeType` specifies the format in which the report will be generated. For the purpose of this tutorial we will specify the `mimeType` as `application/json`.
Note: Currently, the only `mimeType` available using the reporting API is `application/json`.

## Step 3 - Consider the Filtering That You Would Like to Apply to the Report Being Generated {#step-3---consider-the-filtering-that-you-would-like-to-apply-to-the-report-being-generated}

When creating a report, you can filter the content of the report that will be generated. The fields that can be used to filter a report depend on the report type that you are generating, for the purpose of this tutorial we will focus on the filtering that can be applied to a report of type Payments. When creating a new Payments report you can filter the output of the report. Items returned once the report has been generated will fall inside the scope specified using these fields:

* `createdDateFrom`: Items in the report that is generated will be from the date specified here or later.
* `createdDateTo`: Items in the report that is generated will be from the date specified here or earlier.
* `requestedDateFrom`: The report that is generated will include items where the `requestedDate` on or after the date specified here. This is the date that was requested by the Integrator when creating a payment.
* `requestedDateTo`: The report that is generated will include items where the `requestedDate` on or after the date specified here. This is the date that was requested by the Integrator when creating a payment.
* `lastUpdatedDateFrom`: The report that is generated will include items where the status was updated on or after the date specified here.
* `lastUpdatedDateTo`: The report that is generated will include items where the status was updated on or before the date specified here.
* `country`: Items in the report that is generated will only be from the country that is specified here.
* `statuses`: Items in the report that is generated will 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.

Note: Different `reportTypes` have different filtering options. Refer to [Reports](https://developer.mastercard.com/ob-accept-payments/documentation/payments/reports/index.md) for more information.

## Step 4 - Create a Report Request {#step-4---create-a-report-request}

Once you have identified the report type, report format and report filtering from the previous steps and collected the parameters needed for it, you can create a report and retrieve a reportId for that will be used to identify the report and to specify this particular report in subsequent API calls.

API Reference: `POST /reports`

### Request {#request}

* Use the `reportTyp`e and `mimeType` identified during steps 1 and 2.
* Use the `destinationId` that you obtained from onboarding.
* Specify your desired filtering as identified in step 3 using a suitable combination of the following fields:
  * `createdDateFrom`
  * `createdDateTo`
  * `requestedDateFrom`
  * `requestedDateTo`
  * `lastUpdatedDateFrom`
  * `lastUpdatedDateTo`
  * `country`
  * `statuses`

### Response {#response}

If the request is successful, the response will look like:

```json
{
  "reportId": "472e651e-5a1e-424d-8098-23858bf03ad7"
}
```

Record the `reportId` for next steps.

## Step 5 - Report Status Webhook Notification {#step-5---report-status-webhook-notification}

When the Report status changes you will receive webhook notifications from Mastercard Open Finance Pay of type="ReportStatusUpdated".

An example of how the webhooks content should appear:

```json
{
  "type": "ReportStatusUpdated",
  "data": {
                 "reportId": "acb29db6-70df-4c99-888c-d8485cd40c3d",
                 "executionTime": "2024-01-01T12:34:56.123456+00:00"
              },
  "retryCount": 0
}
```

Record the `reportId` for the next steps.

## Step 6 - Check the Latest Status of a Report Generation {#step-6---check-the-latest-status-of-a-report-generation}

Once you have a `reportId`, you can now call the Get report to understand the latest status of a report generation. We recommend waiting for the ReportStatusUpdated webhook before calling the Get report to reduce the number of Get calls you need to make.

API Reference: `GET /reports/{report_id}`

### Request {#request-1}

Use the `reportId` retrieved from step 4 or 5 as the `report_id` path parameter to get the latest report generation payment status.

### Response {#response-1}

If the request is successful, the response will look like:

```json
{
  "reportType": "Payments",
  "reportId": "472e651e-5a1e-424d-8098-23858bf03ad7",
  "mimeType": "application/json",
  "createdDate": "2023-11-28T00:00:00.0000000+00:00",
  "expirationDate": "2024-11-28T00:00:00.0000000+00:00",
  "status": {
    "code": "READY",
    "lastUpdated": "2023-10-30T10:10:00.7539418+00:00",
    "events": [
      {
        "event": "READY",
        "timestamp": "2024-01-17T12:29:36.919957+00:00"
      }
    ],
    "details": {
      "code": "READY",
      "reason": "Reason"
    }
  },
  "createdDateFrom": "2023-11-28T00:00:00.0000000+00:00",
  "createdDateTo": "2023-11-28T00:00:00.0000000+00:00",
  "country": "GB",
  "requestedDateFrom": "2023-11-28T00:00:00.0000000+00:00",
  "requestedDateTo": "2023-11-28T00:00:00.0000000+00:00",
  "lastUpdatedDateFrom": "2023-11-28T00:00:00.0000000+00:00",
  "lastUpdatedDateTo": "2023-11-28T00:00:00.0000000+00:00",
  "statuses": [
    "PAYMENT_EXECUTED_DEBITED",
    "PAYMENT_EXECUTED_CREDITED",
    "INITIATED"
  ],
  "paymentsCount": 100
}
```

## Step 7 - Fetch the Items That Have Been Generated for Your Report {#step-7---fetch-the-items-that-have-been-generated-for-your-report}

Once a report has reached a status of `READY`, it is possible to access the items of the report. You do this by calling the Get report items endpoint. Once you do this, the report items are returned in the format specified in the mimeType in when creating the report in step 4.

{\< swagger file="apv3 6.yaml" path="/reports/{report_id}/items" action="get" \>}

### Request {#request-2}

Use the `reportId` retrieved from step 4 or 5 as the `report_id` path parameter to fetch the report items.

### Response {#response-2}

If the request is successful, the response will look like:

```json
{
  "payments": [
    {
      "paymentId": "472e651e-5a1e-424d-8098-23858bf03ad7",
      "destinationId": "472e651e-5a1e-424d-8098-23858bf03ad7",
      "paymentRail": "UkFasterPayments",
      "amount": 123.5,
      "currency": "EUR",
      "createdDate": "2023-11-28T00:00:00.0000000+00:00",
      "date": {
        "requestedDate": "2023-11-28T00:00:00.0000000+00:00",
        "actualDate": "2023-11-30T00:00:00.0000000+00:00"
      },
      "status": {
        "code": "PREPARING",
        "lastUpdated": "2023-10-30T10:10:00.7539418+00:00"
      },
      "clientAssignedReference": "MyOwnReference-8cfbeb8f-71bf-4848-a802-830fa3d7815d",
      "forwardSettlementReference": "123-reference",
      "endToEndId": "Example ID",
      "providerId": "GB_TestBank",
      "providerPaymentId": "472e651e-5a1e-424d-8098-23858bf03ad7",
      "mandateId": "77afaef2-4d17-4251-b8bf-3fcf765cf8f5"
    }
  ]
}
```