Reporting

Current reporting suite

• Charges Report

• Reconciliation Details Report

• Network Funds Transfer Report

• Quarterly Scheme Report

• Scheme Fee Details report

• Disputes Details Report

• Fraud Notifications Report

Functionality

• 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 and SFTP by creating distribution objects, and attaching them to report schedules.

Asynchronous reporting infrastructure

• 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.

Considerations regarding CSV reports

1. 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.

2. CSV reports are UTF-8 encoded. They may also include special characters such as “éâöì”.

3. 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.

4. 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.

5. 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

• 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.

• 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

1. 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:

2. The response will list the report object created with a report key.

3. 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

1. Authenticate and access the Acquirer Portal, navigate to the Reports Download section

   

    

2. Generate a report via the “Generate report” button

   

3. Select the report name and parameters relevant to the report name, in this case the “Date Range”. Click “Generate Report”

   

4. 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

1. 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.

2. 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.

3. 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.

4. To archive a report schedule, the user may call the DELETE /v1/reportSchedules/{reportScheduleKey} endpoint which will change its status to archived.

Distributing reports

• email

• SFTP

1. 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.

2. The response from the request above will look like the following:

3. 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.

4. 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.

5. To archive a distribution object, the user may call DELETE /v1/distributions/{distributionKey} which will change its status to archived.

Setting up SFTP distribution

• Silverflow authenticates to your SFTP server using the SSH protocol. To facilitate this, users should add Silverflow's public SSH key to your SFTP server's authorized keys (see our keys below). Silverflow will sign all files sent through the SFTP connection with our private SSH key. This ensures secure and authenticated file transfers.

• After adding the public key to your SFTP server, you can create a SFTP distribution configuration with a POST request to /distributions to set-up the SFTP distribution object with the following body:

• Parameter details:

  • type: Must be sftp

  • targets.host: Your SFTP server hostname (without sftp:// prefix)

  • targets.username: SSH username for authentication

  • targets.dirPath: Directory path where files should be stored

  • reference: Your unique reference for this distribution configuration

• After receiving a successful 201 response, you'll get a distributionKey in the response. Use this key when creating report schedules. Every report generated by the report schedule configuration will be automatically distributed to the SFTP folder and directory path.

• Clients get notified by succesful and failed SFTP file deliveries by subscribing to our com.silverflow.distributions event source. Please read more on event subscriptions here.

SSH Keys for SFTP per environment