--- updatedAt: 2026-07-17T17:09:53.000Z --- Fetch the complete documentation index at: https://docs.lithic.com/llms.txt. Use this file to discover all available pages before exploring further. Append .md to any documentation page URL to get its markdown version. # Chargebacks Learn how to use Lithic's Chargebacks offering to simplify your dispute process. Lithic can help power your cardholders' disputes by handling networking filing for chargebacks and representment responses. You provide the dispute details (e.g. amount and reason) as well as supporting documents, and Lithic submits the chargeback to the network on your behalf. Lithic then escalates to prearbitration or arbitration for you depending on the acquirer's response. If you are considering using Lithic Chargebacks, we encourage you to explore our [Managed Disputes](https://docs.lithic.com/docs/managed-disputes) service which offers end-to-end dispute management tailored to your program's needs. # Schema ## Dispute Schema ```json { "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_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\_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 ```json { "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 ```http Request GET https://api.lithic.com/v1/disputes ``` **Sample Request** ```bash curl https://api.lithic.com/v1/disputes \ -H "Authorization: YOUR_API_KEY" ``` **Sample Response** ```json { "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_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:** | Parameter | Description | | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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 ```http Request GET https://api.lithic.com/v1/disputes/{dispute_token} ``` Get details for a specific dispute. **Sample Request** ```bash curl https://api.lithic.com/v1/disputes/3fa85f64-5717-4562-b3fc-2c963f66afa6 \ -H "Authorization: YOUR_API_KEY" ``` **Sample Response** ```json { "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_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 ```http Request 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](https://docs.lithic.com/docs/transactions#transactionstatus) is SETTLED) can be disputed. Any request to dispute a transaction that has not settled will be rejected. **Sample Request** ```bash 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** ```json { "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_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 ```http Request 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** ```bash 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** ```json { "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_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 ```http Request 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** ```bash 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 ```http Request GET https://api.lithic.com/v1/disputes/{dispute_token}/evidences ``` List evidences for a specific dispute **Sample Request** ```bash curl https://api.lithic.com/v1/disputes/3fa85f64-5717-4562-b3fc-2c963f66afa6/evidences \ -H "Authorization: YOUR_API_KEY" ``` **Sample Response** ```json { "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 } ``` | Parameter | Description | | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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 ```bash 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** ```bash 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** ```json { "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 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 ```http Request 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** ```bash 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** ```json { "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 ```http Request 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 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 created or updated. Both are delivered as `dispute.updated` events. A `dispute_evidence.upload_failed` event is emitted when an evidence upload fails. These events cover disputes filed through the Chargebacks API only. Disputes handled through [Managed Disputes](https://docs.lithic.com/docs/managed-disputes) emit `dispute_transaction.created` and `dispute_transaction.updated` instead; see [Tracking Disputes](https://docs.lithic.com/docs/tracking-disputes). ```curl 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](https://docs.lithic.com/docs/events-api). # Dispute Enumerations ## Status Enumerations ![Flowchart showing dispute status progression from NEW through ARBITRATION with possible outcomes at each stage.](https://d1jvjlrimvr0n9.cloudfront.net/stable/c8ecebdffcda26a8_dispute-status-workflow-diagram.png) | | | | ----------------- | -------------------------------------------------------------------------------------------------------- | | 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 |