Scheme Fee Details Report

The Scheme Fee Details report returns all estimated scheme fees that are calculated based on actions (authentications, authorizations and clearing) performed by an Agent that causes an interaction with the card networks which is expected to trigger fees. This results in every fee estimate being traceable to a specific transaction or action and thus to a particular merchant. Due to the complexities of calculating scheme fees caused by currency conversion and uncertain criteria, scheme fees should always be considered an estimate.

In order to do this, scheme fees are recorded in a specialized ledger within the Silverflow platform. This Scheme Fee Ledger uses decimal arithmetic, retains the degree of precision of the calculated fees, and stores fees in an immutable way. This makes the ledger a suitable source for financial reporting of scheme fees.

Fees are returned in the expected billing currency from the card network, therefore currency conversion may be required to convert the fees into the currency in which they are billed to the merchant. Depending on the Settlement Service configuration certain Visa transactions may trigger scheme fees in more than one currency, so it is the Acquirers' responsibility to convert into a single currency in order to calculate the merchant payout deduction.

It should be noted that some fees will returned with multiple tiers; it is up to the Agent to select the appropriate tier that should be passed onto to the Merchant. Each scheme fee detail will also include an impact (debit or credit), this should be used as part of the aggregation, as in certain countries scheme fees are credited to the Agent.

Silverflow's scheme fee estimation is built on the internal event architecture of the Silverflow platform. This event architecture is largely asynchronous, which means that (transaction lifecycle) events are produced and consumed outside of (and after) the critical transaction flows. Consequently, the scheme fee estimation offers only "eventual consistency".

However, when a scheme fee is estimated, it is assigned a fee date. This fee date designates the moment that the fee was logically incurred. For instance, when a transaction is authorized, the fee(s) for that transaction will get a fee date that matches the time of authorization and not the time that the estimation is calculated. This mitigates, to a large degree, the side-effects of this delayed processing.

When a fee is recorded in the ledger, the fee "booking" is assigned a book date. This book date holds the exact moment that the fee was recorded. It is therefore merely a technical date that does not bear any meaning on the fee itself.

The book date is always after the fee date. For the majority of fees the book date is on the same calendar day as the fee date. However, in the following cases the dates may be on different calendar days:

To better illustrate the relation between fee date and book date, consider the following diagram.

Fee 1, 2, 3 and 9 are based on transactions that occurred on May 1st. They are also recorded in the ledger on the same calendar day. Hence their fee date and book date "day" are the same.

Fee 10 has occurred only seconds before midnight May 2nd. As it takes some time to calculate and transport the scheme fee, it is persisted seconds after midnight, on May 2nd. Hence the book date of this fee is on the next calendar day.

Fee 11 is, similar to fee 1, 2, 3 and 9, persisted on the same day as it was incurred. Fee- and book date "day" are the same.

Fee 12 on the other hand, that was incurred on May 1st, was delayed due to a 'technical disruption' and only delivered for persistence the next day, on May 2nd. So the fee date "day" is May 1st but the book date is on May 2nd.

Fee 18 and 19 are a correction for fee 1 caused by an interchange calculation error. This correction consists of two fee records. The first (18) is a reversal that “negates” the amount in fee 1. The second (19) is the actual correction that holds the corrected amount. The correction was for a fee with a fee date of May 1st. So the fee date of the correction is also May 1st. However, the correction was processed and persisted on May 2nd so the book date is May 2nd. Interchange corrections typically occur within hours of original fee. Please note, corrections in the Scheme Fee Details report are not currently supported but the report has been designed to support this functionality in the near future.

Fee 31 and 32 are a correction for fee 2. Fee 2 was calculated incorrectly due to a software error. The correction was created as part of a data repair procedure. Similar to the correction for fee 1, this correction consists of two fee records. The first (31) is a reversal that “negates” the amount in fee 2. The second (32) is the actual correction that holds the corrected amount. The correction was for a fee with a fee date of May 1st. So the fee date of the correction is also May 1st. However, the correction was processed and persisted on May 4th so the book date is May 4th. Data repair corrections are very rare but may occur. They are always marked as such and contain a note referencing a particular incident that is shared with impacted customers prior to being created. This type of correction may have a large impact on daily merchant payout. Hence, the Silverflow Technical Account Manager will reach out to discuss if, when and how these corrections will be applied.

The scheme fee details report supports two distinct use cases:

Both of these use cases are facilitated by the "Scheme Fee Details" report, accessed through the Silverflow Reporting API. They differ only in the parameters used and frequency of the report.

This can be achieved by doing a POST to /reports/schemeFeeDetails and will schedule a report to be generated according to the requested input parameters.

This report use case will retrieve all fees for a given historic period that is "closed". It uses both a fee start date and a fee end date, where the end date is in the past. It is a stand alone report that retrieves all records that have a fee date that fall within this range. This includes any corrections that are present in the ledger, even if they have been inserted after the fee end date. Hence, this report can be used to provide a corrected (and thus most accurate) view of scheme fees for the specified period.

Due to possible delays between feeDate and bookDate it is recommended that the report should be executed at least 48 hours after the end of the reporting period, to allow both delayed fees and interchange fee corrections to be included.

The second use case of the Scheme Fee Details report supports continuous retrieval of fees. This mechanism allows to retrieve all fees, as they become available. The fees are retrieved through successive calls to the report. The calculated scheme fees will be returned across multiple API calls without duplicates and with no fees omitted.

This use case is best described as a stream of fees, from which chunks of fees are read in successive calls. For example if an Agent wishes to see all the scheme fee estimates in this analogy the lastToken/sinceToken parameters function as the cursor in the stream. The lastToken of the preceding call tracks the 'last read fee'. Specifying this value in the sinceToken of the subsequent call will return fees 'since'.

The following section illustrates which fees this report variation will include, using the same diagram as earlier.

Example 1

In a first example, a scheme fee details report stream is created using only a historic fee start date. The purpose is to get all fees, including all future fees, starting from the specified date, in 12-hour increments.

First Call - Approximate execution time: May 1st, 12:00:00 UTC

Considering the fees highlighted in the diagram, this report will contain fees 1, 2 and 3. Let's say that the lastToken of call #1 was eyJjcmVhdGVkIjoiMjAyMy0.

To get 12-hour increments, the second call should be issued approximately 12 hours after the first. It must have the same report parameters as the initial report and also specify the lastToken of the initial call returned in the result field as the sinceToken parameter.

Second Call - Approximate execution time: May 2nd, 00:00:00 UTC

Considering the fees highlighted in the diagram, this report will contain only fee 9. Let's say that the lastToken of this call was C44NzNaIiwiZW50aXR5IjoiZm.

Call # - Approximate execution time: May 2rd, 12:00:00 UTC

Returned fees are 10, 11 and 12, and value of lastToken is Zmlyc3RQcmVzZW50bWVudCNmY which can be used in subsequent calls.

Note that the frequency of the calls (the time between successive calls) can be changed without affecting the integrity of the stream.