Scheme Fee Details Report

Description

The Scheme Fee Details report provides a detailed breakdown of all calculated scheme fees incurred by an Agent's actions on the platform. Each fee booking is traceable to a specific action (e.g., authentication, authorization) and a particular merchant, allowing for granular cost analysis. It's important to note that these fees are calculated by Silverflow and can differ from the actual applied amounts by the card networks. Card networks do not provide detailed insight into which transaction incurs a specific fee.

Audience

Product
Finance

Purpose

The Scheme Fee Details Report is used to support core financial and operational tasks:

Invoice merchants using an interchange-plus-plus (IC++) model by leveraging the merchant or transaction identifiers on each fee booking.
Gain deeper insight into card network invoices by comparing Silverflow's action-level figures to the transactional billing lines in your invoices.

Functionality

Create reports	Via API Generate via portal
Access reports	Via API Download via portal Push to SFTP or e-mail
Schedule reports	Hourly Daily
Query patterns	The report is generated by specifying a date range using the `bookDate`parameter with `from`and `to`values.
Data types	NDJSON JSON CSV
Data sources	Data is sourced from Silverflow's internal event architecture, which tracks actions performed by the Agent on the platform.

Considerations

Silverflow vs card networks invoices: Silverflow's scheme fee calculations may not match card network invoices one-to-one. Discrepancies can occur due to card network billing practices and currency conversions, which are often not transparently explained by the networks.
Tiering: The Scheme Fee Detailsreport returns all possible tiers for a given fee because it does not know the specific tiering of a customer or merchant. Tier 0 is the most conservative option. It is up to the Agent to select and apply the appropriate tier.
Impact: Each scheme fee includes an impactfield (debit or credit). This should be used for aggregation. In some countries, some scheme fees can be a credit to the acquirer.
Currency: Fees are returned in the expected billing currency from the card network. Depending on the settlement service configurations, fees can be billed in various currencies.
Fee date vs book date:
- Fee Date: This is the date the fee was logically incurred, matching the time of the source event (e.g., a transaction authorization). It is a logical date, not a technical one.
- Book Date: This is the technical timestamp of when the fee was recorded in the ledger and, therefore, when it will appear in the report. The book date will always be on or after the fee date.

Content

Field	Description
key	A unique identifier for a scheme fee booking, starting with `sfb-`.
agentKey	A foreign key that identifies the agent, starting with `cgt-`.
cardNetwork	The card network to which the fee entry belongs. Possible values include: `mastercard` `visa` `american-express` `discover` `bancontact`
binKey	A key assigned by Silverflow to uniquely identify a BIN.
bin	Acquirer BIN. The BIN number as assigned by the card network. Also referred to as the Acquirer Reference ID (Mastercard) or Submitter Id (AMEX).
acquirerIdCode	The identifier of the Acquirer as defined by the Card Network (e.g., Visa CIB, Mastercard ICA).
merchantAcceptorKey	A unique identifier for a Merchant Acceptor, starting with `mac-`.
merchantKey	A unique identifier for a Merchant, starting with `mkt-`.
mid	The Merchant ID assigned to the merchant by the acquirer.
threeDsKey	A unique identifier for a 3DS authentication, starting with `tds-`.
chargeKey	A unique identifier for a Charge, starting with `chg-`.
chargeActionKey	A unique identifier for an action on a charge, starting with `act-`. A partial clearing will result in two different action keys.
clearingArn	The Acquirer Reference Number (ARN) for dual-message systems or Retrieval Reference Number (RRN) for single-message systems.
transactionReference	The unique ID assigned by the merchant or payment service provider.
actionReference	An action reference assigned by the agent during creation. Will not start with `act-`.
billingFrequency	The interval at which the card networks bill this fee. May have one of the following values: `daily` (each processing date, settling the next processing date). `weekly` (for example each Sunday for mastercard, settling the next processing date). `monthly` (for example on the 15th of each month, settling the next processing date). `quarterly`
tierId	The optional Mastercard "Tier ID" for this fee as it appears on the invoice. Note that the presence of this field does not indicate if this fee has multiple tiers. See the `tiering` field.
feeId	The fee identifier as it appears on the card network invoice (e.g., Mastercard "Event ID" or Visa "Billing line").
feeDescription	The Mastercard "Event description" or the Visa "Description", as they appear on the corresponding invoices.
feeDate	The date the fee was logically incurred (in UTC), based on the source event.
bookDate	The timestamp (in UTC) when the fee booking was created in the ledger. This is a technical date that indicates when the fee will appear in the report.
tiering	The type of tiering used to determine the applicable fee. Values may include: `volume`: indicates that the applicable fee is determined using the total `sourceAmount` for a given period. `count`: indicates that the applicable fee is determined using the total number of fees (transactions).
numberOfTiers	The number of tiers defined for this fee.
feeRate.type	Type of fee. Values may include: `fixed`: a fixed amount, shown in the `value` field. `basisPoints`: a variable, should be applied to the `sourceAmount` field.
feeRate.currency	Three-letter ISO code of the currency (for example `USD` or `EUR`).
feeRate.tiers.[x].value	Value of the fee. This is defined either as a `fixed` value, or `basisPoints` value and depends what is defined in the `type` field. In minor units and may have decimals.
feeRate.tiers.[x].impact	Funding impact. May be `credit` or `debit`.
feeRate.tiers.[x].upToIncluding	This field indicates the value up to (including) which this tier [x] applies. This is based either on `volume` or `count` as described in the `tiering` field.
feeRate.tiers.[x].above	This field indicates the value from which this tier [x] applies. This is based either on `volume` or `count` as described in the `tiering` field.
sourceAmount.currency	Three-letter ISO code of the currency (for example `USD` or `EUR`).
sourceAmount.value	Source amount on which the fee rate is calculated. In minor units and may have decimals.
conversionRates.[x].date	Conversion rates are published by card networks each day. This field shows what rate date was used.
conversionRates.[x].source	Three-letter ISO code of the currency (for example `USD` or `EUR`).
conversionRates.[x].target	Three-letter ISO code of the currency (for example `USD` or `EUR`).
conversionRates.[x].rate	Rate between the source and the target. May have up to 11 decimals. Note there may be multiple rates if indirect currency conversion took place. For example, from THB to USD, from USD to EUR.
conversionRates.[x].operation	Operation of the rate between the source and target currency. May have values: `divide` `multiply`
convertedSourceAmount.currency	Three-letter ISO code of the currency (for example `USD` or `EUR`).
convertedSourceAmount.value	Source amount denominated in the `feeRate` currency. Only applies when the `feeRateCurrency` is different from the `sourceAmountCurrency`.
billingAmount.currency	Three-letter ISO code of the currency (for example `USD` or `EUR`).
billingAmount.amounts.[x].value	Calculated billing amount to the acquirer, using the fee rate and the source amount. In minor units and may have decimals.
billingAmount.amounts.[x].impact	Funding impact. May be `credit` or `debit`.
billingAmount.amounts.[x].upToIncluding	This field indicates the value up to (including) which this tier [x] amount applies. This is based either on `volume` or `count` as described in the `tiering` field.
billingAmount.amounts.[x].above	This field indicates the value from which this tier [x] applies. This is based either on `volume` or `count` as described in the `tiering` field.