New Settlement API Endpoints

At a Glance

Release date: March 4, 2025 (production)
Impact: New API endpoints providing direct access to network-reported settlement totals
Audience: Customers managing their own network settlement
Action required: None
Products affected: Settlement API

Overview

We are introducing two Settlement API endpoints that provide official settlement total amounts as reported directly by the card networks. Each record returned represents a specific combination of settlement service, report date, cycle, and institution ID.

While our existing settlement summary endpoint rolls up line items to obtain the totals, idiosyncratic rounding rules used by certain networks can occasionally result in small differences between the official totals and the computed totals. Customers managing their own settlements with the network can reference the new endpoints documented below for the authoritative settlement figures.

Details

For detailed endpoint specifications and usage examples, visit our API Reference.

Endpoints

Method	Description	Path
`GET`	List network total records with optional filters	`/v1/reports/settlement/network_totals`
`GET`	Retrieve a specific network total record by token	`/v1/reports/settlement/network_totals/{token}`

List Endpoint Query Parameters

Parameter	Type	Description
`report_date`	string	Singular report date to filter on (YYYY-MM-DD). Cannot be populated in conjunction with `report_date_begin` or `report_date_end`.
`report_date_begin`	string	Earliest report date to filter on, inclusive (YYYY-MM-DD).
`report_date_end`	string	Latest report date to filter on, inclusive (YYYY-MM-DD).
`network`	string	Network to filter on (VISA, MASTERCARD, MAESTRO, or INTERLINK).
`institution_id`	string	Institution ID to filter on.
`settlement_institution_id`	string	Settlement institution ID to filter on.
`begin`	string	Date string in RFC 3339 format. Only entries created after the specified time will be included. UTC time zone.
`end`	string	Date string in RFC 3339 format. Only entries created before the specified time will be included. UTC time zone.
`page_size`	integer	Number of records per page (1-100, default 50).
`starting_after`	string	A cursor representing an item's token after which a page of results should begin. Used to retrieve the next page of results after this item.
`ending_before`	string	A cursor representing an item's token before which a page of results should end. Used to retrieve the previous page of results before this item.

List Endpoint Response Schema

Core response fields:

data: Array of network total records (required)
has_more: Boolean for pagination (required)

Each record in data contains:

Field	Type	Required	Notes
`token`	string	✓	Globally unique identifier.
`network`	string	✓	Card network where the transaction took place. VISA, MASTERCARD, MAESTRO, or INTERLINK.
`institution_id`	string	✓	The institution that activity occurred on. For Mastercard: ICA (Interbank Card Association). For Maestro: institution ID. For Visa: lowest level SRE (Settlement Reporting Entity).
`settlement_institution_id`	string	✓	The institution responsible for settlement. For Mastercard: same as `institution_id`. For Maestro: billing ICA. For Visa: Funds Transfer SRE (FTSRE).
`settlement_service`	string	✓	Settlement service.
`report_date`	string	✓	Date that the network total record applies to. YYYY-MM-DD format.
`cycle`	integer		The clearing cycle that the network total record applies to. Mastercard only.
`currency`	string	✓	Three-digit alphabetic ISO 4217 code.
`created`	string	✓	RFC 3339 timestamp for when the record was created. UTC time zone.
`updated`	string	✓	RFC 3339 timestamp for when the record was last updated. UTC time zone.

The amounts object (required):

Field	Type	Required	Notes
`gross_settlement`	integer	✓	Total settlement amount excluding interchange, in currency's smallest unit.
`interchange_fees`	integer	✓	Interchange amount, in currency's smallest unit.
`visa_charges`	integer		Charges specific to Visa/Interlink, in currency's smallest unit.
`net_settlement`	integer	✓	`gross_settlement` net of `interchange_fees` and `visa_charges` (if applicable), in currency's smallest unit.

List Endpoint Response Example

{
  "data": [
    {
      "token": "12cf7505-06a8-435e-b1c7-4c430d02f6c3",
      "network": "VISA",
      "institution_id": "1000000000",
      "settlement_institution_id": "1000000001",
      "settlement_service": "015",
      "report_date": "2025-02-25",
      "currency": "CAD",
      "amounts": {
        "gross_settlement": 100,
        "interchange_fees": -25,
        "visa_charges": 10,
        "net_settlement": 85
      },
      "created": "2025-02-25T13:07:31.419631Z",
      "updated": "2025-02-25T13:07:31.419631Z"
    },
    {
      "token": "0604c316-17f0-456d-9ac7-7d94252acb1a",
      "network": "INTERLINK",
      "institution_id": "1000000000",
      "settlement_institution_id": "1000000001",
      "settlement_service": "001",
      "report_date": "2025-02-25",
      "currency": "USD",
      "amounts": {
        "gross_settlement": 200,
        "interchange_fees": -50,
        "visa_charges": 10,
        "net_settlement": 160
      },
      "created": "2025-02-25T13:07:31.419631Z",
      "updated": "2025-02-25T13:07:31.419631Z"
    },
    {
      "token": "700a1c78-04ed-47e2-8160-b1e18914ec7b",
      "network": "MASTERCARD",
      "institution_id": "031511",
      "settlement_institution_id": "031511",
      "settlement_service": "US00000001",
      "report_date": "2025-02-25",
      "currency": "USD",
      "cycle": 1,
      "amounts": {
        "gross_settlement": 100,
        "interchange_fees": -25,
        "net_settlement": 75
      },
      "created": "2025-02-25T13:07:31.419631Z",
      "updated": "2025-02-25T13:07:31.419631Z"
    },
    {
      "token": "e05d5448-210e-4cc3-bd0d-d54d3c6c9a9f",
      "network": "MASTERCARD",
      "institution_id": "031511",
      "settlement_institution_id": "031511",
      "settlement_service": "US00000001",
      "report_date": "2025-02-25",
      "currency": "USD",
      "cycle": 2,
      "amounts": {
        "gross_settlement": 100,
        "interchange_fees": -25,
        "net_settlement": 75
      },
      "created": "2025-02-25T13:07:31.419631Z",
      "updated": "2025-02-25T13:07:31.419631Z"
    }
  ],
  "has_more": false
}

Important Considerations

The data returned reflects your specific settlement institution hierarchy, with totals potentially appearing at multiple levels. For example, in a hierarchical structure with a parent institution and two child institutions, network total records will be returned for all three. The parent institution's totals will represent the sum of its child institutions' totals. You will need to determine which network total records overlap based on your institution hierarchy.

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

Recommended Actions

We encourage you to integrate this endpoint into your reconciliation processes, particularly if you:

Need the exact settlement amounts as they appear in network reports
Want to access network-reported totals before settlement summaries have been marked complete

Although the network totals are generally immutable, we recommend building support for potential updates in your integration as they may be necessary in rare cases.

If you have any questions or concerns, please contact us via the HELP link in your Lithic Dashboard.

The Lithic changelog has an RSS feed! To monitor for new update announcements, subscribe with your preferred RSS reader.