Disputes v2

Overview

We've launched a new Disputes API in the /v2 namespace for dispute lifecycle tracking, available to all customers. With this API, you can trace disputes back to the original transaction, follow the flow of funds through to network settlement, and get a live view of financial liability across all parties involved - all within Lithic's API suite.

📘

This new Disputes API is part of Managed Disputes, a comprehensive dispute management service for any customer who wants to hand off compliance and operations-heavy work to Lithic and focus on building out their core business. Please reach out to your Customer Success Manager if you are interested in a walkthrough or demo.

The new API contains two GET endpoints:

Also available are event webhooks that customers can use to trigger automated workflows:

• dispute_transaction.created - fires when a dispute object is initialized. For customers on Managed Disputes, this occurs when the dispute is opened. For all other customers, this occurs when the chargeback is processed by the network.
• dispute_transaction.updated - fires when the dispute object is updated on any subsequent event.

With the exception of customers on Managed Disputes, the API and webhooks contain disputes from February 27 onward.

Introducing the Dispute Object

The API endpoints and webhooks return a dispute object that captures key updates throughout the dispute's lifecycle, from initial filing to resolution. Using this, customers can access:

• An event timeline showing what has happened with each dispute
• A live breakdown of financial liability across the parties involved in the dispute - in other words, between the cardholder, issuer, and acquirer, who's on the hook for what amount
• Details about the merchant involved in the original transaction
• Flexible filtering by card, account, and original transaction

The level of detail you receive depends on your dispute workflow. Customers on Managed Disputes get the richest information, since Lithic manages the end-to-end process and has visibility into every event along the way. Customers on Chargebacks, and customers handling their own disputes, will be able to see dispute financial events (chargebacks, representments, etc) resulting from network filing.

*only populated for Visa.
**in the liability allocation object, only recovered_amount is populated. This tracks how much your program has successfully recovered from the merchant's acquirer.

Note: this dispute object and the object returned by /v1/disputes do not share the same token. This is relevant to customers using Chargebacks.

Here's how a dispute_transaction.updated webhook looks for the same dispute case, depending on your program's dispute setup:

    {
      "account_token": "3f7a1c2e-9b44-4d81-bc23-e105d7f8a930",
      "card_token": "c82d4f71-0e3a-4b56-9d18-7a3e2c1f0b85",
      "case_id": "5530482917",
      "created": "2026-01-08T09:22:14.531820Z",
      "currency": "USD",
      "disposition": "WON",
      "event_type": "dispute_transaction.updated",
      "events": [
        {
          "created": "2026-01-08T09:22:14.531820Z",
          "data": {
            "action": "OPENED",
            "amount": 18750,
            "disposition": null,
            "reason": "Merchandise Not Received",
            "stage": "CLAIM"
          },
          "token": "c04e92b1-7a31-4d58-f813-29d0e5c7a641",
          "type": "WORKFLOW"
        },
        {
          "created": "2026-01-08T10:47:33.201450Z",
          "data": {
            "action": "PROVISIONAL_CREDIT_GRANTED",
            "amount": 18750,
            "reason": "Provisional Credit"
          },
          "token": "d71f3a28-05bc-4e90-b924-38a1f6d0c857",
          "type": "CARDHOLDER_LIABILITY"
        },
        {
          "created": "2026-01-08T09:22:14.531820Z",
          "data": {
            "amount": 18750,
            "polarity": "CREDIT",
            "stage": "CHARGEBACK"
          },
          "token": "a1d3c7e9-4f02-5b18-d6a4-82fc39e10d27",
          "type": "FINANCIAL"
        },
        {
          "created": "2026-01-29T11:34:22.817540Z",
          "data": {
            "amount": 18750,
            "polarity": "DEBIT",
            "stage": "REPRESENTMENT"
          },
          "token": "b5e82f14-7c60-5d93-e1b7-04a917c28f63",
          "type": "FINANCIAL"
        },
        {
          "created": "2026-02-23T16:08:47.219305Z",
          "data": {
            "amount": 18750,
            "polarity": "CREDIT",
            "stage": "ARBITRATION"
          },
          "token": "f2c741a8-3b90-5e64-d027-19e8c36a5b04",
          "type": "FINANCIAL"
        },
        {
          "created": "2026-02-23T16:08:47.219305Z",
          "data": {
            "action": "CLOSED",
            "amount": null,
            "disposition": "WON",
            "reason": "Issuer favored in arbitration",
            "stage": "CLAIM"
          },
          "token": "e83a571c-2d04-4f17-a960-50b7c18d3e92",
          "type": "WORKFLOW"
        }
      ],
      "liability_allocation": {
        "denied_amount": 0,
        "original_amount": 18750,
        "recovered_amount": 18750,
        "remaining_amount": 0,
        "written_off_amount": 0
      },
      "merchant": {
        "acceptor_id": "MNR4LBQ82VHKTZ9",
        "acquiring_institution_id": "",
        "city": "PORTLAND",
        "country": "USA",
        "descriptor": "URBAN THREADS APPAREL CO",
        "mcc": "5621",
        "state": "OR"
      },
      "network": "VISA",
      "status": "CLOSED",
      "token": "d94b260c-5fa3-4e17-b832-6c09e471d15a",
      "transaction_series": {
        "related_transaction_event_token": "e37f841b-2d95-5a06-c914-18b053e7a462",
        "related_transaction_token": "f60c193d-7e58-4b72-a285-51d2c9847f30",
        "type": "DISPUTE"
      },
      "updated": "2026-02-23T16:08:47.219305Z"
    }

Improved Reconciliation

Settlement details in the Settlement API now tie directly to dispute financial events in the dispute object. Each settlement detail includes the dispute token and dispute event token (in the fields transaction_tokens and event_tokens), giving you a clear link between settlement line items and the specific dispute events that drove them. For customers on Managed Disputes, this means full traceability from the original transaction all the way through dispute resolution and cash movement. Read more about this here.

Let's continue the example from above. Here are the settlement details you would receive for the $187.50 dispute:

{
  "data": [
    {
      "account_token": "3f7a1c2e-9b44-4d81-bc23-e105d7f8a930",
      "card_program_token": "a7f3c291-4d02-4e81-b947-12d0e8c3f150",
      "card_token": "c82d4f71-0e3a-4b56-9d18-7a3e2c1f0b85",
      "created": "2026-02-23T16:08:47.219305Z",
      "currency": "USD",
      "disputes_gross_amount": 18750,
      "event_tokens": ["f2c741a8-3b90-5e64-d027-19e8c36a5b04"],
      "institution": "00000020307",
      "interchange_fee_extended_precision": 0,
      "interchange_gross_amount": 0,
      "network": "VISA",
      "other_fees_details": {},
      "other_fees_gross_amount": 0,
      "report_date": "2026-02-23",
      "settlement_date": "2026-02-23",
      "token": "d4e82b39-5f17-4c92-f641-28b4a1e3c085",
      "transaction_token": "d94b260c-5fa3-4e17-b832-6c09e471d15a",
      "transactions_gross_amount": 0,
      "type": "ARBITRATION",
      "updated": "2026-02-23T16:08:47.219305Z"
    },
    {
      "account_token": "3f7a1c2e-9b44-4d81-bc23-e105d7f8a930",
      "card_program_token": "a7f3c291-4d02-4e81-b947-12d0e8c3f150",
      "card_token": "c82d4f71-0e3a-4b56-9d18-7a3e2c1f0b85",
      "created": "2026-01-29T11:34:22.817540Z",
      "currency": "USD",
      "disputes_gross_amount": -18750,
      "event_tokens": ["b5e82f14-7c60-5d93-e1b7-04a917c28f63"],
      "institution": "00000020307",
      "interchange_fee_extended_precision": 0,
      "interchange_gross_amount": 0,
      "network": "VISA",
      "other_fees_details": {},
      "other_fees_gross_amount": 0,
      "report_date": "2026-01-29",
      "settlement_date": "2026-01-29",
      "token": "c9d04f17-2a83-4b61-e528-17a3f0d2b794",
      "transaction_token": "d94b260c-5fa3-4e17-b832-6c09e471d15a",
      "transactions_gross_amount": 0,
      "type": "REPRESENTMENT",
      "updated": "2026-01-29T11:34:22.817540Z"
    },
    {
      "account_token": "3f7a1c2e-9b44-4d81-bc23-e105d7f8a930",
      "card_program_token": "a7f3c291-4d02-4e81-b947-12d0e8c3f150",
      "card_token": "c82d4f71-0e3a-4b56-9d18-7a3e2c1f0b85",
      "created": "2026-01-08T09:22:14.531820Z",
      "currency": "USD",
      "disputes_gross_amount": 18750,
      "event_tokens": ["a1d3c7e9-4f02-5b18-d6a4-82fc39e10d27"],
      "institution": "00000020307",
      "interchange_fee_extended_precision": 0,
      "interchange_gross_amount": 0,
      "network": "VISA",
      "other_fees_details": {},
      "other_fees_gross_amount": 0,
      "report_date": "2026-01-08",
      "settlement_date": "2026-01-08",
      "token": "b3e71a04-9c52-4d38-a817-05f2e9d1c463",
      "transaction_token": "d94b260c-5fa3-4e17-b832-6c09e471d15a",
      "transactions_gross_amount": 0,
      "type": "CHARGEBACK",
      "updated": "2026-01-08T09:22:14.531820Z"
    }
  ],
  "has_more": false
}

Observe that the transaction_token in each of these, d94b260c-5fa3-4e17-b832-6c09e471d15a, is the token in the dispute object further above. Additionally, the event_tokens in each of these contains a single identifier matching the token in the corresponding event within the dispute object. For instance, the ARBITRATION settlement detail has "event_tokens": ["f2c741a8-3b90-5e64-d027-19e8c36a5b04"] which identifies the ARBITRATION event in the dispute object.

FAQ

What's the difference between /v2/disputes and /v1/disputes?

The suite of endpoints under /v1/disputes powers Lithic Chargebacks, where Lithic handles network filing of chargebacks (and as needed, escalations to pre-arbitration or arbitration) for customers who want to simplify their dispute workflows. Customers using Chargebacks are responsible for managing all other aspects of the dispute, such as cardholder communications, provisional credits, and evidence collection.

Customers on Lithic Chargebacks should continue to use /v1/disputes endpoints to initiate and modify disputes, upload evidence, and check on dispute resolution outcomes. The new endpoints under /v2/disputes provide a supplemental view of these same disputes.

What are the /v2/disputes endpoints for then?

These endpoints help you trace the history of a transaction from when it first occurs to when it is disputed and when cash moves as a result. How?

• The dispute object references the original transaction, so given a dispute, you can easily fetch the original transaction. You can also search in the other direction by querying disputes with the original transaction token as an input.
• Customers managing their own network settlement can tie each settlement line item to the specific dispute and dispute financial event within.

Are you going to add more endpoints to /v2/disputes?

Yes! Keep a lookout for future changelog announcements. Please note, these will be primarily for customers using Managed Disputes; customers on Chargebacks will continue to operate in the /v1 namespace.

Network Support

The new API supports Visa and Mastercard disputes only. Support for American Express is on the way.

Learn More

• Managed Disputes - All things Managed Disputes
• List Disputes - API reference for listing disputes
• Retrieve Dispute - API reference for retrieving individual disputes
• Settlement Reporting - Use this to reconcile dispute financial impact with network settlement

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.