Use the Create a report endpoint to create a report in a region where your merchants offer Pay by Bank. Each report type can be filtered by required and optional parameters to generate the exact data you need. 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.
When the run completes with status of successful, the response to Retrieve a report will include a URL where you can download your results. 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 a report in the specified region based on filters provided in the request body. You can choose one of the supported report types to create a consolidated report on all your merchants in the specified region, or just a subset of your merchant(s) or their business application(s). You can also specify how you'd like to 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.
For example, you can create a consolidated Pay-in Payments report on 3 of your merchants in EU region for April 2024 in CSV format, to be delivered via email:
POST /partner/v2/reports/{region}
{
"start_date": "2024-04-01T00:00:00Z",
"end_date": "2024-04-30T23:59:59Z",
"mode": "live",
"scoped_resources": {
"type": "business",
"scope": [
"business_id_1",
"business_id_2",
"business_id_3"
]
},
"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":
{
"report_id": "75d6d371-5cff-474a-b49b-aaf639446447",
"timestamp": "2024-10-24T21:24:58.059Z",
"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"
},
],
"scoped_resources": {
"type": "business",
"scope": [
"business_id_1",
"business_id_2",
"business_id_3"
]
},
}
Retrieve Report
Retrieve the current status of a report by its report_id. If the report is complete, it’ll return with status = “successful”. Depending on the delivery option you’d specified, you’ll either receive a download URL or confirmation of delivery via email or SFTP.
For example, if you were to retrieve the above report using after it completes using GET /partner/v2/reports/{region}/{report_id}, the response would look like this:
{
"report_id": "75d6d371-5cff-474a-b49b-aaf639446447",
"timestamp": "2024-10-24T22:46:14.235Z",
"status": "successful",
"url": "https://storage.googleapis.com/b/example-file.txt?",
"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"
},
],
"scoped_resources": {
"type": "business",
"scope": [
"business_id_1",
"business_id_2",
"business_id_3"
]
},
}
In rare occasion when a report request or processing encounters an error, it’ll return with status = failed and the corresponding error object:
{
"report_id": "75d6d371-5cff-474a-b49b-aaf639446447",
"timestamp": "2024-10-24T22:46:14.235Z",
"status": "failed",
"error": {
"code": "report_delivery_failed",
"description": "missing necessary data to deliver the report"
},
"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"
},
],
"scoped_resources": {
"type": "business",
"scope": [
"business_id_1",
"business_id_2",
"business_id_3"
]
},
}
Download Report
If you’d opted for the requested report to be delivered via URL, you can download the report by the report_id:
GET /partner/v2/reports/eu/75d6d371-5cff-474a-b49b-aaf639446447/download
A successfully generated report shall remain available for retrieval for 30 days.