Reporting

This guide provides comprehensive information on how to interact with Silverflow's reporting endpoints. It covers available reports, functionality, best practices, and step-by-step instructions for generating, retrieving, scheduling, and distributing reports.

Silverflow supports acquiring workflows by providing the relevant information to our customers. One way of doing that is exposing information through our Reports. Our reports include information on authorisations, transactions, compliance, disputes and more. We provide item-level reports as well as dedicated formats for specific use cases. Some workflow examples that we support through our reports include daily financial reconciliation, merchant payout calculations, quarterly scheme reporting (GOC/QMR), monthly scheme fee invoice reconciliation, and dispute management. Our dedicated reporting team continuously adds new reports to the suite as well as improving the infrastructure to deliver them.

If you have specific questions about our infrastructure, the content of a report, or would like to request a new one, please contact your account manager or reach us at support@silverflow.com.

Current reporting suite

Functionality

The Silverflow reporting API offers the following key features:

Our asynchronous generation and retrieval reporting infrastructure allows for large report generation while remaining high performance.
Receive push notifications on report status updates through our events subscriptions.
Reports can be created and accessed through our API as well as through the Acquirer Portal in the Reports section.
Reports may be available in JSON, CSV, and Excel formats.
Our reports follow a strict change management policy to ensure continuity of performance (both JSON formats on the API as well as file downloads).
We ensure secure delivery of reports through authentication and permissions, as well as maintaining security protocols.
Users are able to create report schedules with a variety of intervals (quarterly, daily, hourly).
Users are able to automatically distribute generated reports over e-mail by creating distribution objects, and attaching them to report schedules.

Asynchronous reporting infrastructure

As described in the Functionality above, our report generation is asynchronous, meaning that Agents can trigger a report generation, which will be enqueued for generation, and when the report is created Agents can retrieve it via a different endpoint. The infrastructure is designed this way to handle larger reports while maintaining performance, without timing out the API response. It works as follows:

Users generate a report through the POST /v1/reports/{reportName} endpoints. The response will list the report object created with a report key.
The report object is enqueued and we will start generating the report file. Users can receive a status update by calling our GET /v1/reports/{key} endpoint.
Once the report file creation is finalised, the report object will receive a completed status and the report is ready for access. Silverflow sends out a notification that the report with its key has been completed through the event source https://silverflow.com/reports.
Users can retrieve the report file with the GET /v1/reports/{key}/file.

Best practices for integration

Integrate continuously: For daily item-level or transaction-level reports, make sure to properly integrate with the time elements. For example for daily reports, the user should generate reports from 00:00:00 to 23:59:99 on D+0, and then again from 00:00:00 to 23:59:99 on D+1.
Use event notifications for always up to date information: To stay updated on the report object status, users may integrate to our event notifications, which will be pushed once the report object received its Completed status.
Schedule and automatically distribute reports: Some users may not have access to the APIs or portal to create and retrieve reports. To still deliver reporting to them, we advise to setup a distribution object and including that object when creating a report schedule. This way, every time the report schedule generates a new report, it is automatically distributed to the targets described in the distribution object.

Step-by-step guides

Generate and retrieve individual reports via the API

In order to generate and retrieve individual reports the user should follow the following flow:

Users generate a report through the POST reports/{report name} endpoints. The response will list the report object created with a report key. An example request for a reconciliationDetails report looks like the following:
The response will list the report object created with a report key.
The report is then scheduled for generation. Users can receive a status update by calling our GET reports/{Key} endpoint using the key received when creating the request.

Note that in order to omit the need of periodically calling the GET report endpoint in step 2, clients may subscribe to our Report Event Notifications. Agents will receive an Completed update once the report has been finalised and is available for retrieval.

Users can retrieve the report file with the GET reports/{Key}/file using the key that was provided during creation of the report.

Generate and retrieve individual reports via the Acquirer Portal

Authenticate and access the Acquirer Portal, navigate to the Reports Download section
Generate a report via the “Generate report” button
Select the report name and parameters relevant to the report name, in this case the “Date Range”. Click “Generate Report”
Navigate back to the reports download section. The report status will initially mention scheduled. Once the status is completed, click the download button on the right to retrieve the report.

Schedule report generation

A user can create a new report schedule using the POST /v1/reportSchedules endpoint using the parameters mentioned above. For example, the following request will create a SchemeFeeDetails report on an hourly basis by setting the following parameters. Note that the report will be build in JSON format because of its mimeType.
- Users can optionally add distribution objects to automatically distribute reports that are generated by the schedule. See more on distributions below.
After a new report schedule is created, new report entities will be created following the type and cadence interval. To confirm the successful scheduling of the report, the user will receive a 200 response. In the response, you will find the status as active.
To retrieve the report schedule object(s), the user may call the GET /v1/reportSchedules endpoint to list all report schedules or the GET /v1/reportSchedules/{reportScheduleKey} endpoint using the key of the report schedule.
To archive a report schedule, the user may call the DELETE /v1/reportSchedules/{reportScheduleKey} endpoint which will change its status to archived.

Distributing reports

To distribute generated reports to the user, it should create a distribution object. That object can be attached to a created report to trigger the distribution. Currently, Silverflow offers the following distribution delivery types: email

To create a distribution object, the user should use the POST /v1/distributions endpoint. Here, a distribution type should be included (see list above). Depending on the distribution delivery type, the user should then provide where the reports should be delivered to in the targets field. Optionally, the user can provide a reference for internal purposes. An example request is the following:
- The response from that request will include the distributionKey, that should then be used when creating a report schedule on our POST /v1/reportSchedules endpoint as shown above.
The response from the request above will look like the following:
To retrieve the distribution object(s), the user may call the GET /v1/distributions endpoint to list all distribution objects or the GET /v1/distributions/{distributionKey} endpoint using the key of the distribution object.
To update an existing distribution configuration, one should use PATCH /v1/distributions/{distributionKey}. This is useful to update email addresses or to change the reference without having to create a new distribution object and report schedule.
To archive a distribution object, the user may call DELETE /v1/distributions/{distributionKey} which will change its status to archived.