Lithic's Settlement API enables you to reconcile daily cash movements from your settlement account against your transactions, as well as view interchange and network fees. The Settlement Summary endpoint shows the aggregate gross settlement by report date while the Settlement Details endpoint breaks down the gross settlement by transaction.

The Settlement API is intended for use in reconciliation, transaction inspection, and other data analysis. Customers managing their own settlements with the card network are encouraged to reference settlement advisement reports sent directly by the network, in lieu of the Settlement API, when facilitating actual cash movements.

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 available.

Settlement Summaries generally become available at a consistent time every day, but some variation in timing may occur due to multiple operational factors, such as when Lithic receives settlement information from the networks.

This feature is only available in your production environment.

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

Settlement Summary Schema

{
  "currency": String,
  "settled_net_amount": Integer,
  "transactions_gross_amount": Integer, 
  "interchange_gross_amount": Integer,
  "disputes_gross_amount": Integer,
  "other_fees_gross_amount": Integer,
  "details": [
    {
      "currency": String,
      "network": NETWORK.ENUM,
      "institution": String,
      "settled_net_amount": Integer,
      "transactions_gross_amount": Integer,
      "interchange_gross_amount": Integer,
      "disputes_gross_amount": Integer,
      "other_fees_gross_amount": Integer
    }
  ],
  "is_complete": Boolean,
  "report_date": String,
  "created": String,
  "updated": String
}

See Network and Fee Type enumerations below for a list of possible values.


currency	Three-digit alphabetic ISO 4217 code
settled_net_amount	The total net amount of cash moved. (net value of settled_gross_amount, interchange, fees)
transactions_gross_amount	The total amount of settlement impacting transactions (excluding interchange, fees, and disputes).
interchange_gross_amount	Total gross amount of interchange. Interchange data is available from 2023-05-04 onwards.
disputes_gross_amount	Total gross amount of disputes settlements.
other_fees_gross_amount	Total gross amount of other fees besides interchange.
details	A JSON response that contains a breakdown by network and institution. Institution is the most granular ID the network settles with (e.g., ICA for Mastercard, FTSRE for Visa). See Network enumerations below.
is_complete	All transaction-level data has been processed and reconciliation is complete. This will generally occur at a consistent time daily but may vary sometimes within a given day due to various operational factors.
created	Timestamp of when the report was first generated; in UTC timezone. Example: 2023-06-01T00:00:00
updated	Timestamp of when the report was updated; in UTC timezone Example: 2023-06-01T00:00:00
report_date	Date of when the report was first generated

Settlement Details Schema

{
    "token": String,
    "institution": String,
    "account_token": String,
    "card_token": String,
    "card_program_token": String,
    "event_tokens": [String],
    "transaction_token": String,
    "currency": String,
    "network": String,
    "transactions_gross_amount": Integer,
    "disputes_gross_amount": Integer,
    "interchange_gross_amount": Integer,
    "interchange_fee_extended_precision": Integer,
    "other_fees_gross_amount": Integer,
    "other_fees_details": {
      "FEE_TYPE.ENUM": Integer
    },
    "type": String,
    "created": String,
    "updated": String,
    "settlement_date": String,
    "report_date": String
}


token	Globally unique identifier denoting the Settlement Detail
institution	The most granular ID the network settles with (e.g., ICA for Mastercard, FTSRE for Visa)
account_token	Globally unique identifier denoting the Account associated with this settlement
card_token	Globally unique identifier denoting the card that the associated Transaction occurred on
card_program_token	Globally unique identifier denoting the card program that the associated Transaction occurred on
event_tokens	Globally unique identifiers denoting the Events associated with this settlement
transaction_token	Globally unique identifier denoting the associated Transaction object
currency	3-digit alphabetic ISO 4217 code
network	Network on which this interchange was collected. Enumerations include: VISA, MASTERCARD, MAESTRO, INTERLINK, UNKNOWN
transactions_gross_amount	The gross settled amount of this record. A positive amount indicates a debit (e.g., clearing) while a negative amount indicates a credit (e.g., refund). This will be in the currency’s smallest unit (e.g., cents for USD).
interchange_gross_amount	The gross interchange amount associated with this settled transaction
interchange_fee_extended_precision	The gross interchange amount associated with this settled transaction in six-digit extended precision (e.g., $0.101 = 101000. The total for interchange shown in the Summary endpoint is the sum of this field for every record.
disputes_gross_amount	Total gross amount of disputes settlements.
other_fees_gross_amount	Total gross mount of other fees besides interchange.
other_fees_details	A json response that describes the total gross amount of other fees by type. The json contains an amount and a fee type. See Fee Type enumerations below.
fee_description	The network's description of the fee. Only present if `type` is `FEE`.
type	Identifies the type of record. See Type enumerations below. Data available for `MASTERCARD` and `MAESTRO` records only. Others expected Q1 2024.
created	Timestamp of when the report was first generated; in UTC timezone. Example: 2023-06-01T00:00:00
updated	Timestamp of when the report was updated; in UTC timezone Example: 2023-06-01T00:00:00
settlement_date	Date of when money movement is triggered for the transaction
report_date	Date of when the report was first generated

Get Settlement Summary

GET https://api.lithic.com/v1/reports/settlement/summary/{report_date}

Sample Request

curl https://api.lithic.com/v1/reports/settlement/summary/2023-06-16 \
  -H 'AUTHORIZATION: YOUR_API_KEY'

Sample Response

{
  "currency": "USD",
  "settled_net_amount": 1893,
  "transactions_gross_amount": 1900,
  "interchange_gross_amount": -7,
  "disputes_gross_amount": 0,
  "other_fees_gross_amount": 0,
  "details": [
    {
      "network": "MASTERCARD",
      "institution": "00001",
      "settled_net_amount": 1893,
      "transactions_gross_amount": 1900,
      "interchange_gross_amount": -7,
      "disputes_gross_amount": 0,
      "other_fees_gross_amount": 0
    }
  ],
  "is_complete": true,
  "report_date": "2024-11-25",
  "created": "2024-11-25T02:07:42.591295",
  "updated": "2024-11-25T02:07:42.591295"
}


report_date (required, path parameter)	Date string in YYYY-MM-DD format. Date of when the report was first generated. String. Permitted values: Date string in the form YYYY-MM-DD.

Get Settlement Details

GET https://api.lithic.com/v1/reports/settlement/details/{report_date}

Sample Request

curl https://api.lithic.com/v1/reports/settlement/details/2023-06-16?starting_after=41820d45-95ea-4364-8b0e-4c55c7d45330&page_size=1 \
  -H 'AUTHORIZATION: YOUR_API_KEY'

Sample Response

{
  "data": [
    {
      "token": "e34a817f-119d-4976-9fb3-8b020b8bbec3",
      "institution": "00001",
      "account_token": "6c25d6a4-4ff3-46f0-8f9b-f2cbb7e20e09",
      "event_tokens": [
        "8fce9192-41ff-4a7a-8359-bd33b3e0a7c9"
      ],
      "transaction_token": "0e98152b-3753-4a17-bfe2-c6f575c83b85",
      "card_token": "047298ea-5789-46e4-95fa-154aeeab6af3",
      "card_program_token": "62135b36-324f-443a-a630-bab38fe86868",
      "currency": "USD",
      "network": "MASTERCARD",
      "transactions_gross_amount": 1900,
      "interchange_gross_amount": -7,
      "interchange_fee_extended_precision": -70000,
      "disputes_gross_amount": 0,
      "other_fees_gross_amount": 80,
      "other_fees_details": {},
      "type": "CLEARING",
      "created": "2024-11-25T02:07:42.591295",
      "updated": "2024-11-25T02:07:42.591295",
      "settlement_date": "2024-11-25",
      "report_date": "2024-11-25",
    }
  ],
  "page_size": 1,
  "has_more": true
}


report_date (required, path parameter)	Date string in YYYY-MM-DD format. Date of when the report was first generated. String. Permitted values: Date string in the form YYYY-MM-DD.
page_size (optional, query parameter)	For cursor-based pagination - specifies the number of entries to be included on each page in the response. Default value is 50. Integer. Permitted values: 1-1000.
starting_after (optional, query parameter)	For cursor-based pagination - will return a list starting after the object whose token is passed in the parameter. Requests can only use either starting_after or ending_before. For example, you have a list of 100 Card Transaction objects where the first entry is UUID abcd and last entry is UUID wxyz. A request of starting_after = abcd and page_size = 100 will return 99 results (abcd is excluded from the response). String. Permitted values: 36-digit version 4 UUID (including hyphens)
ending_before (optional, query parameter)	For cursor-based pagination - will return a list ending before the object whose token is passed in the parameter. Requests can only use either starting_after or ending_before. For example, you have a list of 100 Card Transaction objects where the first entry is UUID abcd and last entry is UUID wxyz. A request of ending_before = wxyz and page_size = 100 will return the full list of 99. String. Permitted values: 36-digit version 4 UUID (including hyphens)

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)