Settlement Reports

The API's reports section provides insights into our activities to support reconciliation, reporting, and analysis. Information is available through endpoints under Settlement reports, Card Network reports, and Dispute reports.

Settlement Reports

The Settlement Reports provide information on the amounts that the card networks will settle each day. This takes into account when the settlement of cleared charges will take place and which settlement services will be used. Two endpoints are available: one for the Network Funds Transfers, which provides information on the total amounts that will be transferred, and one for the Reconciliation Details, which explains what is included in the settlement amounts.

Interchange++

We provide Interchange on a per transaction level in the correct currency within the Reconciliation Details report. Scheme fees that are attributable to cleared and settled transactions are available from the Scheme Fee Details report. This report also includes transactional scheme fees that can be triggered and billed by the card networks but aren't necessarily linked to a cleared and settled transaction.

We do not currently calculate an Acquirer markup on behalf of our customers; however, if a client has a specific requirement, we can support it if necessary.

Network Funds Transfers

The Network Funds Transfers endpoint returns the total amounts to be settled as reported by the card networks. These totals are aggregated based on the settlement services and currencies involved, with the exact aggregation levels depending on the card network and the BIN configuration. The Network Funds Transfer Totals should match the Bank Transfers performed by the Card Networks on the corresponding day.

Settlement Services

The settlement currency for a particular transaction is determined by the BIN configuration and settlement services set up for an Agent and their underlying Merchant Acceptors.

Visa transactions in Europe can be settled either over the International Settlement Service (mandatory participation), Euro Area National Net Settlement Service, or an individual country's National Net Settlement Service. The ISS is used for all International transactions or domestic or Intra-regional transactions where the Issuer does not participate in the National Net Settlement Service. Area or National Net Settlement Services will be used where the cardholder, issuer, and transaction currency corresponds to that area or country.

Mastercard uses Regional (mandatory) and Intra-currency (Domestic) settlement services, and criteria include issuer location/configuration, acquirer location/configuration, and card program identifier. For example, a transaction will be Intra-Currency settled if all of the following are met: transaction currency, issuer, and acquirer participation.

Our onboarding process and the appropriate card networks will discuss expected costs and expected settlement behavior extensively.

Reconciliation Details

The Reconciliation Details endpoint returns all individual entries that comprise the Network Funds Transfer Totals. The most common kind of detail would correspond to a payment between a Cardholder and a Merchant, but there are also details coming in from the Card Networks, such as Card Network fees and Chargebacks. Each Detail will contain a Network Funds Transfer Key linking it to the corresponding Network Funds Transfer Total and a netSettlementAmount, which denotes how it contributes to the Total amount. Depending on the type of the Reconciliation Detail, it will also contain other information, explaining how the netSettlementAmount is built up and how it links to other entities, such as the Merchant. This information varies by type and is contained in the typeSpecific field. Suppose all Reconciliation Details corresponding to a Network Funds Transfer Total are aggregated. In that case, the sum of the netSettlementAmount of each Detail should be equal to the amount of the Network Funds Transfer Total.

Reconciliation Detail Types

firstPresentment-dms: The initial authorized transaction, e.g., purchase or refund, that uses a dual message system. These are Normal Visa and Mastercard eCommerce and POS transactions in Europe.
firstPresentment-sms: The initial authorized transaction submitted by a single message system with combined authorization and clearing messages. For example, Visa Direct in Europe, US PIN Debit in the United States, and Maestro transactions outside of Europe.
firstPresentment-rtc: The initial authorized transaction using real-time clearing, where clearing occurs simultaneously with authorization but using a separate message. This is used, for example, in Bancontact transactions.
cardNetworkFee-dms: Card network fees deducted from an acquirer's Settlement. Shown as a bulk amount (not transaction level scheme fees) and includes non-transactional and transaction fees.
firstChargeback-dms: The cardholder requests a chargeback from the merchant, which appears as a deduction from the settlement amount as a first chargeback.
secondPresentment-dms: A second presentment occurs when the Acquirer initiates a chargeback defense, money moves from the Issuer to the Acquirer, and this shows up as a second presentment.
arbitrationChargeback: This is the final stage of a chargeback cycle, during which the Issuer can then dispute the second presentment, and Mastercard will determine responsibility.

Book Date and Value Date

Generally, a bank transfer can have a book date distinct from the value date. In such cases, the Book Date refers to the date the Transfer is posted to the account, and the Value Date refers to the date on which the funds become available to the recipient. We make this distinction by using fundsTransferDate for the Funds Transfer Value Date and fundsTransferBookDate for the Funds Transfer Book Date. However, none of the supported Card Networks currently use different Value and Book Dates, so the fundsTransferDate and fundsTransferBookDate fields will contain the same date. This could change if any Card Networks alter their Funds Transfer process.

Corrections

For each Reconciliation Detail, Silverflow deduces and calculates several attributes. For example:

settlementService is used based on the BIN Configuration.
fundsTransferDate is based on Bank Holidays.
interchangeFeeAmount is based on the Fee Manuals of the Card Networks.
netSettlementAmount is potentially based on currency conversion rates provided by the Card Networks.

The result may be inaccurate due to an error in the calculation method or the input used. Depending on the severity of the error, it might be necessary to apply a correction. To ensure transparency and consistency, reconciliation details are immutable. A correction, therefore, involves creating one new reconciliation detail to nullify the original record and often a second record to replace it. The field groupReference may be used to link the original entry with the correction entries.

Example Funds transfer date

Every Reconciliation Detail is created with an entry 1 and isCorrection as false.

key	groupReference	type	entry	isCorrection	fundsTransferDate	settlementAmount	correctedDetailKey
key-1	grp-1	firstPresentment	1	false	2022-09-15	10 EUR Credit	-

If a correction is needed, a nullification record nullifies the original record. isCorrection is set to true to identify the record as a nullification, entry is equal to the original record, indicating that that record is being nullified, and the correctedDetailKey contains the key of the reconciliation detail that was corrected.

key	groupReference	type	entry	isCorrection	fundsTransferDate	settlementAmount	correctedDetailKey
key-1	grp-1	firstPresentment	1	false	2022-09-15	10 EUR Credit	-
key-2	grp-1	firstPresentment	1	true	2022-09-15	10 EUR Debit	key-1

The corrected record will then be added with the corrected value(s). Here entry is incremented to distinguish it from the original record

key	groupReference	type	entry	isCorrection	fundsTransferDate	settlementAmount	correctedDetailKey
key-1	grp-1	firstPresentment	1	false	2022-09-15	10 EUR Credit	-
key-2	grp-1	firstPresentment	1	true	2022-09-15	10 EUR Debit	key-1
key-3	grp-1	firstPresentment	2	false	2022-09-17	10 EUR Credit	-

The first two records will cancel each other out, and the Net Result will be that of the last entry. The process can repeat with higher entry numbers if additional corrections are needed.

Note that the corrected record might have a different fundsTransferDate and, therefore, be available under a different URL.
In some cases, amounts also might be corrected.

Correcting returned transactions

Silverflow provides Reconciliation Details for Visa transactions of type firstPresentment-dms before final confirmation of the scheme. This approach introduces the unlikely possibility of generating a Reconciliation Detail for a submitted transaction that will later be returned (i.e., rejected) by Visa. In this case, we will create a nullification record to nullify the original record corresponding to the returned transaction, proceed to solve the issue, and re-submit the transaction. Upon re-submission of the transaction, a new record for that transaction will be available with the updated settlement information. The new record will have an incremented entry field.

Example Returned Visa Clearing

Every Reconciliation Detail is created with entry 1 and isCorrection as false upon transaction submission.

key	groupReference	type	entry	isCorrection	processingDate	fundsTransferDate	settlementAmount	correctedDetailKey
key-1	grp-1	firstPresentment	1	false	2022-09-15	2022-09-15	10 EUR Credit	-

If the scheme returns the record, a nullification record nullifies the previous one. isCorrection is set to true to identify the record as nullification, and entry is equal to the original record, indicating that that record is being nullified. The correctedDetailKey contains the key of the reconciliation detail that was corrected.

key	groupReference	type	entry	isCorrection	processingDate	fundsTransferDate	settlementAmount	correctedDetailKey
key-1	grp-1	firstPresentment	1	false	2022-09-15	2022-09-15	10 EUR Credit	-
key-2	grp-1	firstPresentment	1	true	2022-09-15	2022-09-15	10 EUR Debit	key-1

We will work to fix the issue and re-submit the transaction to Visa, which will generate a new record. Here entry is incremented to distinguish it from the original record.

key	groupReference	type	entry	isCorrection	processingDate	fundsTransferDate	settlementAmount	correctedDetailKey
key-1	grp-1	firstPresentment	1	false	2022-09-15	2022-09-15	10 EUR Credit	-
key-2	grp-1	firstPresentment	1	true	2022-09-15	2022-09-15	10 EUR Debit	key-1
key-2	grp-1	firstPresentment	2	false	2022-09-16	2022-09-16	10 EUR Credit	-

The first two records will cancel each other out, and the Net Result will be that of the last entry. The process can repeat with higher entry numbers if additional corrections are needed.

Note that the corrected record will most likely have a different processingDate, which will result in a different fundsTransferDate and, therefore, be available under a different URL.
In some cases, other aspects of the settlement information might also be corrected.