# 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](/content/contact/index.html) | | 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

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

```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