Lithic's Settlement API provides a distilled, unified view of cash movement and daily network activity. It enables customers to reconcile daily cash movements from their settlement accounts against their transaction history, as well as view interchange and network fees.

The Settlement API consists of the following:

Settlement Summary: A daily aggregated view of gross settlement amounts
Settlement Details: A transaction-level breakdown of the Settlement Summary
Network Totals: Official settlement totals as reported directly by the card networks

Please refer to the API Reference for information about how to use the Settlement API endpoints.

📘
The Settlement API is an Enterprise product available in production only. Please contact [email protected] if you are interested in using our settlement reporting.

Settlement Summary and Details

The Settlement Summary and Settlement Details go hand-in-hand to present gross settlement amounts, itemized at the transaction level and rolled up to a daily basis. They are intended for use in reconciliation and transaction analysis, such as understanding how an individual transaction contributes to the overall settlement.

What is a "complete" Settlement Summary?

Settlement Summaries update over time to account for new data delivered by the card networks. When the is_complete flag on a Settlement Summary is false, additional updates are expected for the given report date. When the is_complete flag is true, all data for a given report date has been reconciled and is accounted for in the Settlement Summary.

The optimal time to pull settlement data is once daily when you receive the is_complete flag set to true. This ensures you're retrieving the most comprehensive and finalized dataset for that settlement date.

Settlement Summaries are generally marked complete at a consistent time every day; however, variation in timing may occur due to multiple operational factors, with delays in the network's delivery of settlement reports to Lithic being a primary cause. Such delays are outside Lithic's control and must be addressed by the network. Lithic will declare an incident on the status page if a Settlement Summary is still not marked completed by end of day Eastern time.

If you receive another update for a date that was already marked complete (this can happen occasionally), simply re-pull all the settlement details for that date and replace what you have in your system.

Customers can subscribe to event webhooks to receive updates on their Settlement Summaries.

Network Totals

Network Totals source official settlement figures directly from network settlement reports. While the Settlement Summary aggregates Settlement Details to obtain its daily totals, idiosyncratic rounding rules used by certain networks can occasionally result in slight differences between these computed totals and the official totals. Customers who manage their own network settlement can consult the Network Totals for the exact figures when facilitating actual cash movements.

How should Network Totals be interpreted?

Each card network employs its own settlement strategy and structures its settlement reporting accordingly. Furthermore, each customer has a specific settlement institution hierarchy configured for each partner network, which directly impacts the network's reporting as well. As a result, the Network Totals also reflect each customer's hierarchy and the network involved. Customers will need to determine which Network Total records to use based on their particular institution setup and the guidance below.

Each Network Total record represents a unique combination of settlement service, report date, clearing cycle, and institution ID. Visa, Interlink, and Maestro follow one daily cycle, while Mastercard utilizes six cycles. This means we report Mastercard Network Totals six times as often as for other networks. Additionally, Network Total records are typically returned for all institutions in a hierarchy; some may also overlap in covering the same transaction activity.

Network Totals generally follow these conventions by network:

For Visa/Interlink: The Network Totals of the parent institution contain the sum of the Network Totals of the child institutions, effectively presenting the day's totals precomputed.
For Mastercard/Maestro: The Network Totals of the parent institution do not include the Network Totals of the child institutions. The day's totals must be obtained by summing up the Network Totals across all the institutions.

The Maestro Single Message System Default settlement service (denoted by 000) settles on a T+1 basis.

What is a "complete" Network Total?

A Network Total is deemed complete when all corresponding Settlement Details are available in this endpoint. This is reflected in the is_complete flag in the Network Total.

Customers can subscribe to event webhooks to receive notifications about new or modified Network Totals. When is_complete in a Network Total transitions from false to true, an event webhook of type network_total.updated will be dispatched.

Enumerations

Network Enumerations


INTERLINK
MAESTRO
MASTERCARD
UNKNOWN
VISA

Type Enumerations


CLEARING	Dual Message System transaction settlement
FINANCIAL	Single Message System transaction settlement
NON_FINANCIAL	Single Message System message. These messages do not have a `transactions_gross_amount` but can have `interchange_gross_amount`. A common example is a card balance check.
ADJUSTMENT	Adjustment issued by the network to correct a transaction, interchange, fee, or other amount
CHARGEBACK	Issuer has initiated a chargeback
REPRESENTMENT	Merchant response to a first chargeback
PREARBITRATION	Issuer response to a merchant's representment
ARBITRATION	Final phase of the dispute lifecycle
FEE	Fee collected by the network at the ICA/FTSRE level

Fee Type Enumerations


ISA	International Service Assessment (ISA) fees for cross-border transactions (Visa only)