📘
Disputes API is an Enterprise product. Please contact [email protected] if you are interested in using our disputes services.

Schema

Dispute Schema

{
	"amount": Integer,
	"created": String,
	"customer_filed_date": String,
	"customer_note": String,
	"primary_claim_id": String,
	"network_claim_ids": [String],
	"network_filed_date": String,
	"network_reason_code": String,
	"reason": String,
	"representment_date": String,
	"resolution_amount": String,
	"resolution_date": String,
	"resolution_note": String,
	"resolution_reason": String,
	"prearbitration_date": String,
	"status": String,
	"token": String,
	"transaction_token": String
}


amount	Amount under dispute in the currency’s smallest unit (e.g., cents for USD). Only positive values are accepted. May be different from the original transaction amount.
created	Timestamp of when the dispute was first reported to Lithic via the API or Dashboard
customer_filed_date	Date that you received the dispute request from your end-user
customer_note	End customer description of the reason for the dispute; max character length of 5,000
primary_claim_id	Unique identifier for the dispute from the network. This will be the first claim ID set by the network.
network_claim_ids	List of secondary network claim IDs generated by the network for a given dispute
network_filed_date	Date that the dispute was first submitted to the networks by Lithic
network_reason_code	Network reason code used to file the dispute
reason	Reason for dispute. See enumerations below
representment_date	Date the representment was received.
resolution_amount	Net amount in absolute value of dispute total minus network fees.
resolution_date	Date that the dispute was resolved
resolution_note	Note by Lithic’s dispute team on the case resolution
resolution_reason	Reason for resolution. See enumerations below
status	Status of the dispute. See enumerations below
token	Globally unique identifier for a dispute
transaction_token	Globally unique identifier for the transaction under dispute
prearbitration_date	Date that the prearbitration was submitted

Dispute Evidence Schema

{
	"created": String,
	"dispute_token": String,
	"upload_status": String,
	"upload_url": String,
	"token": String
}


created	Timestamp of when the dispute evidence was uploaded
dispute_token	Globally unique identifier for the dispute that is associated with this evidence
download_url	URL to download evidence. Only shown when `upload_status` is `UPLOADED`.
upload_status	Status of your uploaded file. See enumerations below
upload_url	URL to upload dispute evidence to. Will only be present if file status is `PENDING`.
token	Globally unique identifier for the dispute evidence

Dispute API Reference

List Disputes

GET https://api.lithic.com/v1/disputes

Sample Request

curl https://api.lithic.com/v1/disputes \
  -H "Authorization: YOUR_API_KEY"

Sample Response

{
  "data": [
    {
      "amount": 1000,
      "arbitration_date": "2023-04-28T16:22:24.674Z",
      "created": "2023-04-28T16:22:24.674Z",
      "customer_filed_date": "2023-04-28T16:22:24.674Z",
      "customer_note": "string",
      "network_claim_ids": [
        "11000000"
      ],
      "primary_claim_id": "2000000",
      "network_filed_date": "2023-04-28T16:22:24.674Z",
      "network_reason_code": "4859",
      "prearbitration_date": "2023-04-28T16:22:24.674Z",
      "reason": "ATM_CASH_MISDISPENSE",
      "representment_date": "2023-04-28T16:22:24.674Z",
      "resolution_amount": 1000,
      "resolution_date": "2023-04-28T16:22:24.674Z",
      "resolution_note": "string",
      "resolution_reason": "WON_PREARBITRATION",
      "status": "CASE_WON",
      "token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "transaction_token": "12345624-aa69-4cbc-a946-30d90181b621"
    }
  ],
  "has_more": true
}

Query Parameters:


transaction_tokens (optional)	Filter for disputes associated with a specific transactions. You must supply the query parameter as a comma-separated list. String. Permitted values: 36-digit version 4 UUID (including hyphens).
status (optional)	List disputes with a specific status. String. See enumerations below.
begin (optional)	Only entries created after the specified date will be included. String. Permitted Values: Date string in RFC 3339 format. UTC time zone.
end (optional)	Only entries created before the specified date will be included. String. Permitted Values: Date string in RFC 3339 format. UTC time zone.
page_size (optional)	For cursor-based pagination - specifies the number of entries to be included on each page in the response. Integer. Default value: 50. Maximum value: 100.
starting_after (optional)	For cursor-based pagination - specifies the first object in a list to be returned. Requests can only use either starting_after or ending_before. For example, you have a list of 100 Disputes 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)	For cursor-based pagination - specifies the last object in a list to be returned. Requests can only use either starting_after or ending_before. For example, you have a list of 100 Disputes 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 100. String. Permitted values: 36-digit version 4 UUID (including hyphens)

Get Dispute

GET https://api.lithic.com/v1/disputes/{dispute_token}

Get details for a specific dispute.

Sample Request

curl https://api.lithic.com/v1/disputes/3fa85f64-5717-4562-b3fc-2c963f66afa6 \
  -H "Authorization: YOUR_API_KEY"

Sample Response

{
  "amount": 1000,
  "arbitration_date": "2023-04-28T16:22:24.674Z",
  "created": "2023-04-28T16:22:24.674Z",
  "customer_filed_date": "2023-04-28T16:22:24.674Z",
  "customer_note": "string",
  "network_claim_ids": [
    "11000000"
  ],
  "primary_claim_id": "2000000",
  "network_filed_date": "2023-04-28T16:22:24.674Z",
  "network_reason_code": "4859",
  "prearbitration_date": "2023-04-28T16:22:24.674Z",
  "reason": "ATM_CASH_MISDISPENSE",
  "representment_date": "2023-04-28T16:22:24.674Z",
  "resolution_amount": 1000,
  "resolution_date": "2023-04-28T16:22:24.674Z",
  "resolution_note": "string",
  "resolution_reason": "WON_PREARBITRATION",
  "status": "CASE_WON",
  "token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "transaction_token": "12345624-aa69-4cbc-a946-30d90181b621"
}


dispute_token (required, path parameter)	Globally unique identifier for the dispute. String. Permitted values: 36-digit version 4 UUID (including hyphens)

Initiate Dispute

POST https://api.lithic.com/v1/disputes/

Use this endpoint to submit a dispute to Lithic. Only transactions that have settled (status in the transaction object is SETTLED) can be disputed. Any request to dispute a transaction that has not settled will be rejected.

Sample Request

curl https://api.lithic.com/v1/disputes \
  -X POST \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '
{
     "transaction_token": "12345624-aa69-4cbc-a946-30d90181b621",
     "amount": 10000,
     "reason": "ATM_CASH_MISDISPENSE"
}

Sample Response

{
  "amount": 1000,
  "arbitration_date": null,
  "created": "2023-04-28T16:22:24.674Z",
  "customer_filed_date": "2023-04-28T16:22:24.674Z",
  "customer_note": null,
  "network_claim_ids": [
    null
  ],
  "primary_claim_id": null,
  "network_filed_date": null,
  "network_reason_code": null,
  "prearbitration_date": null,
  "reason": "ATM_CASH_MISDISPENSE",
  "representment_date": null,
  "resolution_amount": null,
  "resolution_date": null,
  "resolution_note": null,
  "resolution_reason": null,
  "status": "NEW",
  "token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "transaction_token": "12345624-aa69-4cbc-a946-30d90181b621"
}


transaction_token (required)	Globally unique identifier for the transaction that is being disputed. String. Permitted values: 36-digit version 4 UUID (including hyphens)
amount (required)	Amount disputed (in cents). Integer. Permitted values: positive numbers.
reason (required)	Reason for dispute. String. Permitted values: see enumerations below.
customer_filed_date (optional)	Date that your end-user submitted the dispute to you. String. Permitted values: Date string in 8601 format. UTC time zone.
customer_note (optional)	End customer description of the reason for the dispute. String. Permitted values: Less than 5,000 characters.

Update Dispute

PATCH https://api.lithic.com/v1/disputes/{dispute_token}

Update an existing dispute; can only be updated if not already submitted to card network.

Sample Request

curl https://api.lithic.com/v1/disputes/3fa85f64-5717-4562-b3fc-2c963f66afa6 \
  -X PATCH \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '
{
     "transaction_token": "12345624-aa69-4cbc-a946-30d90181b621",
     "amount": 15000,
     "reason": "ATM_CASH_MISDISPENSE"
}

Sample Response

{
  "amount": 15000,
  "arbitration_date": null,
  "created": "2023-04-28T16:22:24.674Z",
  "customer_filed_date": "2023-04-28T16:22:24.674Z",
  "customer_note": null,
  "network_claim_ids": [
    null
  ],
  "primary_claim_id": null,
  "network_filed_date": null,
  "network_reason_code": null,
  "prearbitration_date": null,
  "reason": "ATM_CASH_MISDISPENSE",
  "representment_date": null,
  "resolution_amount": null,
  "resolution_date": null,
  "resolution_note": null,
  "resolution_reason": null,
  "status": "NEW",
  "token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "transaction_token": "12345624-aa69-4cbc-a946-30d90181b621"
}


dispute_token (required, path parameter)	Globally unique identifier for the dispute. String. Permitted values: 36-digit version 4 UUID (including hyphens)
amount (optional)	Amount disputed (in cents). Integer. Permitted values: positive numbers.
reason (optional)	Reason for dispute. String. Permitted values: see enumerations below.
customer_filed_date (optional)	Date that your end-user submitted the dispute to you. String. Permitted values: Date string in 8601 format. UTC time zone.
customer_note (optional)	End customer description of the reason for the dispute. String. Permitted values: Less than 5,000 characters.

Withdraw Dispute

DELETE https://api.lithic.com/v1/disputes/{dispute_token}

Withdraw a dispute and its associated evidences; can only be withdrawn if not already submitted to card network.

Sample Request

curl https://api.lithic.com/v1/disputes/3fa85f64-5717-4562-b3fc-2c963f66afa6 \
  -X DELETE \
  -H "Authorization: YOUR_API_KEY"


dispute_token (required, path parameter)	Globally unique identifier for the dispute. String. Permitted values: 36-digit version 4 UUID (including hyphens)

Dispute Evidence API Reference

List Dispute Evidences

GET https://api.lithic.com/v1/disputes/{dispute_token}/evidences

List evidences for a specific dispute

Sample Request

curl https://api.lithic.com/v1/disputes/3fa85f64-5717-4562-b3fc-2c963f66afa6/evidences \
  -H "Authorization: YOUR_API_KEY"

Sample Response

{
  "data": [
    {
      "created": "2023-04-28T16:22:24.674Z",
      "dispute_token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "download_url": "string",
      "token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "upload_status": "UPLOADED",
      "upload_url": "string"
    }
  ],
  "has_more": true
}


dispute_token (required, path parameter)	Globally unique identifier for the dispute. String. Permitted values: 36-digit version 4 UUID (including hyphens)
begin (optional)	Only entries created after the specified date will be included. String. Permitted Values: Date string in 8601 format. UTC time zone.
end (optional)	Only entries created before the specified date will be included. String. Permitted Values: Date string in 8601 format. UTC time zone.
page_size (optional)	For cursor-based pagination - specifies the number of entries to be included on each page in the response. Integer. Default value: 50. Maximum value: 100.
starting_after (optional)	For cursor-based pagination - specifies the first object in a list to be returned. Requests can only use either starting_after or ending_before. For example, you have a list of 100 Disputes 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)	For cursor-based pagination - specifies the last object in a list to be returned. Requests can only use either starting_after or ending_before. For example, you have a list of 100 Disputes 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 100. String. Permitted values: 36-digit version 4 UUID (including hyphens)

Initiate Dispute Evidence Upload

POST https://api.lithic.com/v1/disputes/{dispute_token}/evidences

Use this endpoint to upload evidences for a dispute. It will return a URL to upload your documents to. Uploaded documents must either be a jpg, png or pdf file, and each must be less than 250 MB. URL will expire after 30 minutes. You can call the GET endpoint using the token to refresh the upload URL.

Sample Request

curl https://api.lithic.com/v1/disputes/3fa85f64-5717-4562-b3fc-2c963f66afa6i/evidences \
  -X POST \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Sample Response

{
  "created": "2023-04-28T16:22:24.674Z",
  "dispute_token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "download_url": "string",
  "token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "upload_status": "PENDING",
  "upload_url": "https://disputes-evidence-uploads..."
}

Upload

curl -X PUT --upload-file your-file.pdf https://disputes-evidence-uploads...


dispute_token (required, path parameter)	Globally unique identifier for the dispute. String. Permitted values: 36-digit version 4 UUID (including hyphens)
filename	File name of dispute evidence. When downloading the file, or viewing it in the dashboard, it will appear with this filename.

Get Dispute Evidence

GET https://api.lithic.com/v1/disputes/{dispute_token}/evidences/{evidence_token}

Get a specific evidence for a dispute. If the dispute evidence was not uploaded, the endpoint will return an upload_url as part of the response.

Sample Request

curl https://api.lithic.com/v1/disputes/3fa85f64-5717-4562-b3fc-2c963f66afa6/evidences/3fa85f64-5717-4562-b3fc-2c963f66afa6 \
  -H "Authorization: YOUR_API_KEY"

Sample Response

{
  "created": "2023-04-28T16:22:24.674Z",
  "dispute_token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "download_url": "string",
  "token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "upload_status": "UPLOADED",
  "upload_url": "string"
}


dispute_token (required, path parameter)	Globally unique identifier for the dispute. String. Permitted values: 36-digit version 4 UUID (including hyphens)
evidence_token (required, path parameter)	Globally unique identifier for the dispute evidence. String. Permitted values: 36-digit version 4 UUID (including hyphens)

Delete Dispute Evidence

DELETE https://api.lithic.com/v1/disputes/{dispute_token}/evidences/{evidence_token}

Delete an existing dispute evidence; this will be “soft deleted” and not reviewed or submitted by Lithic; it will be kept in accordance to Lithic’s data retention policies for compliance.

Sample Request

curl https://api.lithic.com/v1/disputes/3fa85f64-5717-4562-b3fc-2c963f66afa6/evidences/3fa85f64-5717-4562-b3fc-2c963f66afa6 \
  -X DELETE \
  -H "Authorization: YOUR_API_KEY"


dispute_token (required, path parameter)	Globally unique identifier for the dispute. String. Permitted values: 36-digit version 4 UUID (including hyphens)
evidence_token (required, path parameter)	Globally unique identifier for the dispute evidence. String. Permitted values: 36-digit version 4 UUID (including hyphens)

Dispute Webhooks

You can register an endpoint to subscribe to receive webhooks whenever a dispute is updated.

curl https://api.lithic.com/v1/event_subscriptions \
	-X POST \
	-H 'Authorization: YOUR_API_KEY' \
	-H 'accept: application/json' \
	-H 'content-type: application/json' \
	-d '  
{  
	"url": "https://www.lithic.com/webhooks",
	"description": "Subscription to dispute updates",
	"event_types": ["dispute.updated"]
}  
'

The payload of each webhook will be the dispute schema of the updated dispute.

For more information on how to manage events and subscriptions, as well as validate webhooks, please refer to our Events API docs.

Dispute Enumerations

Status Enumerations


ARBITRATION	Merchant responded to pre-arbitration and the case has entered final arbitration by Mastercard
CASE_CLOSED	Case was closed by Lithic, the network, or the customer, or the case was lost to the merchant
CASE_WON	Case was won and credit will be issued
NEW	Lithic has opened a new dispute case but not yet submitted it to the network
PENDING_CUSTOMER	Lithic has requested from the customer more info about the dispute, before submitting it to the networks
PREARBITRATION	Lithic has submitted additional evidence to the networks
REPRESENTMENT	Merchant has responded to the dispute
SUBMITTED	Lithic has submitted the dispute to the networks

Reason Enumerations


ATM_CASH_MISDISPENSE	ATM did not dispense correct cash amount
CANCELLED	Transaction was cancelled by the cardholder or merchant
DUPLICATED	Transaction was a duplicate
FRAUD_CARD_NOT_PRESENT	Suspected fraud on a card-not-present transaction (e.g., orders made on the Internet, phone orders, mail orders, etc.)
FRAUD_CARD_PRESENT	Suspected fraud on a card-present transaction where the card used was counterfeit or was valid but lost/stolen/not received
FRAUD_OTHER	Other types of fraud such as questionable merchant activity
GOODS_SERVICES_NOT_AS_DESCRIBED	The merchandise received was not as described
GOODS_SERVICES_NOT_RECEIVED	The merchandise was not received
INCORRECT_AMOUNT	The transaction amount was incorrect
MISSING_AUTH	Required authorization was not properly obtained
OTHER	Other reason
PROCESSING_ERROR	Other errors with the transaction data including incorrect currency and late clearings
RECURRING_TRANSACTION_NOT_CANCELLED	Merchant continued to bill for a cancelled recurring transaction
REFUND_NOT_PROCESSED	Merchant did not process refund

Resolution Reason Enumerations


CASE_LOST	Case was lost
NETWORK_REJECTED	Card network rejected the case prior to reaching first chargeback
NO_DISPUTE_RIGHTS_3DS	No grounds for dispute because the transaction is Mastercard Secure
NO_DISPUTE_RIGHTS_BELOW_THRESHOLD	No grounds for dispute because the transaction amount is below a threshold (e.g., $25/$50 for Quick Pay Service merchants)
NO_DISPUTE_RIGHTS_CONTACTLESS	No grounds for dispute because the transaction is contactless
NO_DISPUTE_RIGHTS_HYBRID	No grounds for dispute because the transaction occurred at a hybrid terminal (i.e., PIN preferred terminal) but a PIN was not used
NO_DISPUTE_RIGHTS_MAX_CHARGEBACKS	No grounds for dispute because the maximum number of disputes on this card has been reached
NO_DISPUTE_RIGHTS_OTHER	Rejected by Lithic due to other lack of dispute right reasons
PAST_FILING_DATE	Dispute not filed to network due to missed deadline
PREARBITRATION_REJECTED	Dispute went through prearbitration and was rejected.
PROCESSOR_REJECTED_OTHER	Rejected by Lithic due to other reasons
REFUNDED	Merchant refunded the customer prior to first chargeback
REFUNDED_AFTER_CHARGEBACK	Merchant refunded the customer after the first chargeback
WITHDRAWN	Dispute was withdrawn by the customer
WON_ARBITRATION	Dispute won after arbitration
WON_FIRST_CHARGEBACK	Dispute won after first chargeback
WON_PREARBITRATION	Dispute won after pre-arbitration

Dispute Evidence Enumerations

Upload Status Enumerations


DELETED	Deleted by customer
ERROR	File upload failed
PENDING	File upload is pending
REJECTED	File upload was rejected by Lithic (e.g. failed vulnerability scan)
UPLOADED	File upload is complete