Getting Started with Reports

The reporting API can be used to create and download reports for payments and refunds. Each report type can be filtered by using the parameters specified in the API reference.

The start_date and end_date parameters must be in UTC timezone, and the API supports a maximum reporting window of 90 days per request.

After you've created a report, it will be processed asynchronously. Once the report completes with a status value of successful, the Retrieve a report response will include a url property, which contains the URL for your report. Alternatively, you can also specify the report to be delivered via email or the pre-configured SFTP location.

Create a reportCopy URL

API Reference

This endpoint allows you to create the following reports, by specifying the report type:

See the Data Format page for an example of the CSV output that will be generated for each of these.

You can receive the report—via URL, email, or SFTP. The report generation process is asynchronous, and you'll receive a report ID to track the status.

Selecting Report ColumnsCopy URL

By default, a report includes every available column for its report type, as shown on the Data Format page. If you only need a subset, you can add a selected_columns object to the request body alongside report_specific_filters:

{
  "report_specific_filters": {
    "type": "payment_report"
  },
  "selected_columns": {
    "columns": ["payment_id", "created_timestamp", "state", "amount"]
  }
}

The columns array accepts any of the column names listed below for the matching report type. Columns are returned in the same order you list them, and repeating a column name is allowed—both are preserved exactly as submitted.

Each report type has one mandatory column that must always be included:

If you omit selected_columns entirely, the request behaves as before and every column is returned. Requests will be rejected with a 400 error if:

• columns is present but empty
• a column name isn't valid for any report type
• a column name belongs to a different report type than the one requested
• the mandatory column for the report type is missing from columns

Here is an example request that will create a Payin Payments CSV report for April 2024, for 2 of your business applications, to be delivered via email:

{
  "start_date": "2024-04-01T00:00:00Z",
  "end_date": "2024-04-30T23:59:59Z",
  "mode": "live",
  "scoped_resources": {
    "type": "business_application",
    "scopes": [
      "app_id_1",
      "app_id_2"
    ]
  },
  "file_format": "csv",
  "delivery_config": [
    {
      "email": "merchant@example.com",
      "type": "email_delivery"
    }
  ],
  "report_specific_filters": {
    "type": "payment_report"
  }
}

The response includes a report_id with status = "pending":

{
  "start_date": "2024-04-01T00:00:00Z",
  "end_date": "2024-04-30T23:59:59Z",
  "mode": "live",
  "file_format": "csv",
  "report_specific_filters": {
    "type": "payment_report"
  },
  "delivery_config": [
    {
      "type": "email_delivery",
      "email": "merchant@example.com"
    }
  ],
  "report_id": "1ae1ce03-dfa9-4593-b487-65c656991cb5",
  "timestamp": "2024-10-24T21:24:58.059Z",
  "scoped_resources": {
    "type": "business_application",
    "scopes": [
      "app_id_1",
      "app_id_2"
    ]
  },
  "status": "pending"
}

Retrieve ReportCopy URL

API Reference

You can retrieve the current status of a report by its report_id. If the report is complete, it will return with status = "successful". Depending on the delivery option you specified, you'll either receive a download URL or confirmation of delivery via email or SFTP.

Using the example above, if you were to retrieve the above report after it completes, the response would look like this:

{
  "start_date": "2024-04-01T00:00:00Z",
  "end_date": "2024-04-30T23:59:59Z",
  "mode": "live",
  "file_format": "csv",
  "report_specific_filters": {
    "type": "payment_report"
  },
  "delivery_config": [
    {
      "type": "email_delivery",
      "email": "merchant@example.com"
    }
  ],
  "report_id": "1ae1ce03-dfa9-4593-b487-65c656991cb5",
  "timestamp": "2024-10-24T22:46:14.235Z",
  "url": "https://example.com/report.csv",
  "scoped_resources": {
    "type": "business_application",
    "scopes": [
      "app_id_1",
      "app_id_2"
    ]
  },
  "status": "successful"
}

In rare occasion where a report encounters an error, it'll return with status = "failed" and the corresponding error object:

{
  "start_date": "2024-04-01T00:00:00Z",
  "end_date": "2024-04-30T23:59:59Z",
  "mode": "live",
  "file_format": "csv",
  "report_specific_filters": {
    "type": "payment_report"
  },
  "delivery_config": [
    {
      "type": "email_delivery",
      "email": "merchant@example.com"
    }
  ],
  "report_id": "1ae1ce03-dfa9-4593-b487-65c656991cb5",
  "timestamp": "2024-10-24T22:46:14.235Z",
  "error": {
    "code": "invalid",
    "description": "invalid credentials or bad request"
  },
  "scoped_resources": {
    "type": "business_application",
    "scopes": [
      "app_id_1",
      "app_id_2"
    ]
  },
  "status": "failed"
}

Download ReportCopy URL

API Reference

You can download reports using this endpoint once the report status has changed to successful.

Successfully generated reports will remain available for 30 days, after which they will be deleted.