Disputes API

Learn how to submit and monitor disputes.

📘

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
}
amountAmount 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.
createdTimestamp of when the dispute was first reported to Lithic via the API or Dashboard
customer_filed_dateDate that you received the dispute request from your end-user
customer_noteEnd customer description of the reason for the dispute; max character length of 5,000
primary_claim_idUnique identifier for the dispute from the network. This will be the first claim ID set by the network.
network_claim_idsList of secondary network claim IDs generated by the network for a given dispute
network_filed_dateDate that the dispute was first submitted to the networks by Lithic
network_reason_codeNetwork reason code used to file the dispute
reasonReason for dispute. See enumerations below
representment_dateDate the representment was received.
resolution_amountNet amount in absolute value of dispute total minus network fees.
resolution_dateDate that the dispute was resolved
resolution_noteNote by Lithic’s dispute team on the case resolution
resolution_reasonReason for resolution. See enumerations below
statusStatus of the dispute. See enumerations below
tokenGlobally unique identifier for a dispute
transaction_tokenGlobally unique identifier for the transaction under dispute
prearbitration_dateDate that the prearbitration was submitted

Dispute Evidence Schema

{
	"created": String,
	"dispute_token": String,
	"upload_status": String,
	"upload_url": String,
	"token": String
}
createdTimestamp of when the dispute evidence was uploaded
dispute_tokenGlobally unique identifier for the dispute that is associated with this evidence
download_urlURL to download evidence. Only shown when upload_status is UPLOADED.
upload_statusStatus of your uploaded file. See enumerations below
upload_urlURL to upload dispute evidence to. Will only be present if file status is PENDING.
tokenGlobally 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/

Submit a dispute to Lithic.

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-2c963f66afa6 \
  -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)
filenameFile 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

ARBITRATIONMerchant responded to pre-arbitration and the case has entered final arbitration by Mastercard
CASE_CLOSEDCase was closed by Lithic, the network, the customer or the case was lost to the merchant
CASE_WONCase was won and credit will be issued
NEWNew dispute case is opened with Lithic but not yet submitted to the network
PENDING_CUSTOMERLithic has request more info on a dispute from the customer prior to submission to the networks
PREARBITRATIONLithic has submitted additional evidence to the networks
REPRESENTMENTMerchant has responded to the dispute
SUBMITTEDLithic has submitted the dispute to the networks

Reason Enumerations

ATM_CASH_MISDISPENSEATM did not dispense correct cash amount
CANCELLEDTransaction was cancelled by the cardholder or merchant
DUPLICATEDTransaction was a duplicate
FRAUD_CARD_NOT_PRESENTSuspected fraud on a card-not-present transaction (e.g., orders made on the Internet, phone orders, mail orders, etc.)
FRAUD_CARD_PRESENTSuspected fraud on a card-present transaction where the card used was counterfeit or was valid but lost/stolen/not received
FRAUD_OTHEROther types of fraud such as questionable merchant activity
GOODS_SERVICES_NOT_AS_DESCRIBEDThe merchandise received was not as described
GOODS_SERVICES_NOT_RECEIVEDThe merchandise was not received
INCORRECT_AMOUNTThe transaction amount was incorrect
MISSING_AUTHRequired authorization was not properly obtained
OTHEROther reason
PROCESSING_ERROROther errors with the transaction data including incorrect currency and late clearings
RECURRING_TRANSACTION_NOT_CANCELLEDMerchant continued to bill for a cancelled recurring transaction
REFUND_NOT_PROCESSEDMerchant did not process refund

Resolution Reason Enumerations

CASE_LOSTCase was lost
NETWORK_REJECTEDCard network rejected the case prior to reaching first chargeback
NO_DISPUTE_RIGHTS_3DSNo grounds for dispute because the transaction is Mastercard Secure
NO_DISPUTE_RIGHTS_BELOW_THRESHOLDNo grounds for dispute because the transaction amount is below a threshold (e.g., $25/$50 for Quick Pay Service merchants)
NO_DISPUTE_RIGHTS_CONTACTLESSNo grounds for dispute because the transaction is contactless
NO_DISPUTE_RIGHTS_HYBRIDNo 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_CHARGEBACKSNo grounds for dispute because the maximum number of disputes on this card has been reached
NO_DISPUTE_RIGHTS_OTHERRejected by Lithic due to other lack of dispute right reasons
PAST_FILING_DATEDispute not filed to network due to missed deadline
PREARBITRATION_REJECTEDDispute went through prearbitration and was rejected.
PROCESSOR_REJECTED_OTHERRejected by Lithic due to other reasons
REFUNDEDMerchant refunded the customer prior to first chargeback
REFUNDED_AFTER_CHARGEBACKMerchant refunded the customer after the first chargeback
WITHDRAWNDispute was withdrawn by the customer
WON_ARBITRATIONDispute won after arbitration
WON_FIRST_CHARGEBACKDispute won after first chargeback
WON_PREARBITRATIONDispute won after pre-arbitration

Dispute Evidence Enumerations

Upload Status Enumerations

DELETEDDeleted by customer
ERRORFile upload failed
PENDINGFile upload is pending
REJECTEDFile upload was rejected by Lithic (e.g. failed vulnerability scan)
UPLOADEDFile upload is complete