The reporting API can be used to create and download reports for payments and mandates. 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 report
This endpoint allows you to create the following reports, by specifying the report type:
| Report type | Context |
|---|---|
| Pay-In Payments Report | Provides details on payments made to your account. |
| Pay-Out Payments Report | Provides details on payments made from your account. |
| Refund Report | Provides details on refunds processed from your account. |
| Mandates Report | Provides details on mandates created between your business and your customers. |
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.
Here is an example request that will create a Mandates 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",
"scope": [
"app_id_1",
"app_id_2"
]
},
"file_format": "csv",
"delivery_config": [
{
"email": "merchant@example.com",
"type": "email_delivery"
}
],
"report_specific_filters": {
"type": "mandate_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": "mandate_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",
"scope": [
"app_id_1",
"app_id_2"
]
},
"status": "pending"
}
Retrieve Report
You can retreive 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": "mandate_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": "string",
"scoped_resources": {
"type": "business_application",
"scope": [
"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": "mandate_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",
"source": {
"parameter": "invalid"
},
"title": "invalid credentials or bad request"
},
"scoped_resources": {
"type": "business_application",
"scope": [
"app_id_1",
"app_id_2"
]
},
"status": "failed"
}
Download Report
You can download reports using this endpoint once the report status has changed to successful.
Successfully generated reports wull remain available for 30 days, after which they will be deleted.