dispute_token

uuid

required
Token of the dispute to retrieve.

200 OK

object
The Dispute object tracks the progression of a dispute throughout its lifecycle.

case_id

string | null
required
Identifier assigned by the network for this dispute.

token

uuid
required
Token assigned by Lithic for the dispute, in UUID format.

card_token

uuid
required
Token for the card used in the dispute, in UUID format.

account_token

uuid
required
Token for the account associated with the dispute, in UUID format.

network

string
enum
required
Card network handling the dispute.
VISA``MASTERCARD

currency

string
required
^[A-Z]{3}$
Three-letter ISO 4217 currency code.

created

date-time
required
When the dispute was created.

updated

date-time
required
When the dispute was last updated.

merchant

object
required

acceptor_id

string
required
Unique alphanumeric identifier for the payment card acceptor (merchant).

acquiring_institution_id

string
required
Unique numeric identifier of the acquiring institution.

city

string
required
City of card acceptor. Note that in many cases, particularly in card-not-present transactions, merchants may send through a phone number or URL in this field.

country

string
required
Country or entity of card acceptor. Possible values are: (1) all ISO 3166-1 alpha-3 country codes, (2) QZZ for Kosovo, and (3) ANT for Netherlands Antilles.

descriptor

string
required
Short description of card acceptor.

mcc

string
required
Merchant category code (MCC). A four-digit number listed in ISO 18245. An MCC is used to classify a business by the types of goods or services it provides.

state

string
required
Geographic state of card acceptor.

transaction_series

required

Transaction Series

null
Transaction Series object

liability_allocation

object
required
Current breakdown of how liability is allocated for the disputed amount

original_amount

integer
required
The initial amount disputed

recovered_amount

integer
required
The amount that has been recovered from the merchant through the dispute process

written_off_amount

integer
required
The amount the issuer has chosen to write off

denied_amount

integer
required
The amount that has been denied to the cardholder

remaining_amount

integer
required
Any disputed amount that is still outstanding, i.e. has not been recovered, written off, or denied

status

string | null
enum
required
Current status of the dispute.

OPEN``CLOSED``null

disposition

string | null
enum
required
Dispute resolution outcome

WON``LOST``PARTIALLY_WON``WITHDRAWN``DENIED``null

events

array of objects
required
Chronological list of events that have occurred in the dispute lifecycle

events*

object
Event that occurred in the dispute lifecycle

token

uuid
required
Unique identifier for the event, in UUID format

type

string
enum
required
Type of event

WORKFLOW``FINANCIAL``CARDHOLDER_LIABILITY

created

date-time
required
When the event occurred

data

required
Details specific to the event type

Workflow Event Data

Financial Event Data Cardholder Liability Event Data

Workflow Event Data object

`400 A parameter in the query given in the request does not match the valid queries for the endpoint.

`401 | | | | --- | --- | | User has not been authenticated | Invalid or missing API key | | API key is not active | The API key used is no longer active | | Could not find API key | The API key provided is not associated with any user | | Please provide API key in Authorization header | The Authorization header is not in the request | | Please provide API key in the form Authorization: [api-key] | The Authorization header is not formatted properly | | Insufficient privileges. Issuing API key required | Write access requires an Issuing API key. Reach out at lithic.com/contact | | Insufficient privileges to create virtual cards. | Creating virtual cards requires an additional privilege |

`404 The specified resource was not found.

`422 Unprocessable entity.

`429 Client has exceeded the number of allowed requests in a given time period. | | | | --- | --- | | Rate limited, too many requests per second | User has exceeded their per second rate limit | | Rate limited, reached daily limit | User has exceeded their daily rate limit | | Rate limited, too many keys tried | One IP has queried too many different API keys |

Updated 3 months ago

curl --request GET \
     --url https://sandbox.lithic.com/v2/disputes/dispute_token \
     --header 'accept: application/json'

{
  "case_id": "string",
  "token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "card_token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "account_token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "network": "VISA",
  "currency": "string",
  "created": "2026-07-17T22:19:57.340Z",
  "updated": "2026-07-17T22:19:57.340Z",
  "merchant": {
    "acceptor_id": "333301802529120",
    "acquiring_institution_id": "191231",
    "city": "NEW YORK",
    "country": "USA",
    "descriptor": "COFFEE SHOP",
    "mcc": "5812",
    "state": "NY"
  },
  "transaction_series": {
    "type": "DISPUTE",
    "related_transaction_token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "related_transaction_event_token": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  },
  "liability_allocation": {
    "original_amount": 0,
    "recovered_amount": 0,
    "written_off_amount": 0,
    "denied_amount": 0,
    "remaining_amount": 0
  },
  "status": "OPEN",
  "disposition": "WON",
  "events": [
    {
      "token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "type": "WORKFLOW",
      "created": "2026-07-17T22:19:57.340Z",
      "data": {
        "type": "string",
        "stage": "CLAIM",
        "action": "OPENED",
        "reason": "string",
        "amount": 0,
        "disposition": "WON"
      }
    }
  ]
}

Updated 3 months ago