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 and retrieving 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

Charges Report	API docs	Report guide
Settlement Details Report	API docs	Report guide
Network Funds Transfer Report	API docs	Report guide
Scheme Fee Details Report	API docs	Report guide
Quarterly Scheme Report	API docs	Report guide
AMMF Report	API docs	Report guide
Disputes Report	API docs	Report guide
Fraud Notifications Report	API docs	Report guide

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.
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 NDJSON, 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.

Supporting functionality

Event notifications: Receive updates through webhooks using our event notification subscriptions.
Scheduling reports: Users are able to create report schedules with a variety of intervals (daily, hourly).
Distributing reports: Users are able to automatically distribute generated reports to their preferred target destination (e.g. e-mail, SFTP, S3).

Best practices for integration

Integrate continuously: For item-level or transaction-level reports, make sure to properly integrate with the time elements. For example for hourly reports, the user should generate reports from 00:00:00 to 00:59:99, and then again from 01:00:00 to 01:59:99.
Set up Report Distribution: 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.
Set up Report Schedules: To ensure no data is missed and to automate data retrieval workflows, we advise to setup report schedules for important operational workflows. To do this, the user can create a report schedule on their preferred cadence, and the reports will automatically be generated. See our guide on scheduling reports here.
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.

Considerations regarding CSV reports

This section outlines how we manage changes to the CSV reports that we operate. The way these are parsed and integrated into systems are different from (ND)JSON formats. Key things to consider include:

Delimiter-separated files are often given a ".csv" extension even when the field separator is not a comma. Many applications or libraries that consume or produce CSV files have options to specify an alternative delimiter. however, at Silverflow we standardise this to be comma-separated.
CSV reports are UTF-8 encoded. They may also include special characters such as “éâöì”.
NDJSONs are better for processing of large datasets and are native to developer environments. This is why Silverflow advises to integrate the NDJSON version of each CSV report.
Clients are required to integrate with CSV reports using column headers instead of the column number. This eliminates interruptions in case of new data fields, changes in column order.
CSV reports will be versioned to provide clarity about changes over time, with version identifiers included in the report file name to help clients distinguish between schema iterations. We will have a single version live for creating reports, which may evolve over time instead of having multiple versions simultaneously. This allows us to introduce new information maintain accuracy while remaining consistent with the information available via the API.

Breaking and non-breaking changes for CSV reports

Examples of breaking changes specific to CSV reports include:

Removing a column
Renaming a column
Changes in level of granularity in the data (e.g. Reporting daily data instead of hourly data).
Modifying the data format in columns (e.g., changing date format from YYYY-MM-DD to MM/DD/YYYY).
Changing enumerated values in fields (e.g., replacing "SUCCESS" with "1").
Altering the file naming convention of the CSV file.

Examples of non-breaking changes specific to CSV reports include:

Adding columns to the file (at the end, beginning, or in the middle).
Changing the order of columns.
Improving the calculation logic for aggregated metrics.
Changes in special characters. For example, whether the report allows for special characters (such as éàä).
Introducing new enumerated values while retaining existing ones.
Offering new delivery methods while retaining existing methods.

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.