---
title: "Disputes"
slug: "disputes"
tags: ["Payments"]
updated: 2025-12-01T16:13:02Z
published: 2025-12-01T16:13:02Z
canonical: "docs.blackthorn.io/disputes"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blackthorn.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Disputes

## What is a Dispute?

### Introduction

A Dispute is a situation in which a customer questions the validity of a Transaction that was registered to their account.

If you are unfamiliar with how Disputes are received, the associated fees, or what to submit, please review [Stripe's documentation](https://stripe.com/docs/disputes).

### Setup

Create a [webhook](/v1/docs/webhooks) between Stripe and Salesforce.

### Testing Disputes

In order to test Disputes you will need to use a specific test credit card created for a [dispute simulation](https://docs.blackthorn.io/docs/payments-test-stripe-payment-gateway#disputes).

### Receiving a Dispute

Navigate to the Dispute object.

```
* ***Lightning:** Navigate to app launcher > Under "All Items" select Dispute.*
* ***Classic:** Click "All Tabs" (The "+" icon in the top right corner) > select Dispute.*
```

- A Dispute record is created through [Webhook Events](/v1/docs/webhook-events) with the **Status** = "Needs Response."
- The disputed Transaction's **Payment Status** changes from "Captured" to "Disputed" and a refund Transaction is created for the captured amount. The Stripe fee for the dispute will also be populated on the **Payment Gateway Fee** field on the refund Transaction.

![H_01_05_Dispute 1](https://cdn.document360.io/f977eec0-500f-40a3-b663-724a51f78075/Images/Documentation/H_01_05_Dispute%201.png)

*Disputed Transaction*

---

![H_01_05_Dispute 2](https://cdn.document360.io/f977eec0-500f-40a3-b663-724a51f78075/Images/Documentation/H_01_05_Dispute%202.png)

If you notice that two refund Transactions are created when you receive a Dispute, this is because the old dispute logic operated in this manner. Please upgrade to the latest Payments package to see the most recent dispute logic.

- When receiving a Dispute, you have until the **Due By** date to formally respond and submit all supporting evidence.
- The Dispute **Reason** is what the cardholder defined the disputed payment as. *[Dispute reasons](https://stripe.com/docs/disputes/categories)*
- The **Refundable**, **Has Evidence**, and **Past Due** fields track where the disputed record is in the process.*These fields can be used as notification filters in a Workflow, Process Builder, or Reports to make sure Disputes are submitted before being past due.*
- After adding your Dispute Evidence and clicking **Submit**, the **Submission Count** = "1" and the **Status** = "Under Review". *It has now been submitted to [Stripe's financial partner](https://stripe.com/docs/disputes#how-evidence-submission-works) for review and no changes can be made.*
- If you won the Dispute, **Status** will update to "Won". If the card issuer won the Dispute, **Status** will update to "Lost". *Once a Dispute has been "Won" or "Lost", Stripe will send out an email with the Dispute information.*

**Notes**

- **Important note from Stripe:** If you receive a Dispute, try contacting your customer and discuss it before you respond. It’s possible that they simply did not recognize or remember the Transaction when they viewed their statement.
- Stripe will charge you a [$15.00 Dispute fee](https://stripe.com/docs/disputes#fees) (for users in the United States) by the card network. If you win the {{variable.Object_Dispute}}, the original amount will be refunded to you and a$15.00 adjustment Transaction will be created for you to cover the original Stripe fee.
- ACH disputes cannot be contested. If you receive an [ACH dispute](https://support.stripe.com/questions/accepting-ach-payments-with-stripe#ach-disputes) the Dispute **Status** = "Lost" and the original Transaction's **Payment Status** will update to "Refunded".

## Dispute Evidence

The purpose of the Dispute Evidence object is to submit evidence in defense of your Dispute that will push to Stripe. Review all evidence before clicking **Submit**, as you cannot update evidence once submitted.

There are four different **Record Type**s for Dispute Evidence. **Record Type**s are used because not all fields are relevant for all Dispute types (as is designed in the Stripe dashboard), however, if you do need access to other fields as part of the Dispute, you can add them to the Page Layout or update the same data set in the Stripe dashboard:

- Basic Response
- Physical Product
- Digital Product or Service
- Offline Service

![H_01_05_Dispute Evidence 1](https://cdn.document360.io/f977eec0-500f-40a3-b663-724a51f78075/Images/Documentation/H_01_05_Dispute%20Evidence%201.png)

### Creating a New Dispute Evidence Record

[Embedded content](https://www.youtube.com/embed/9l6thnrpjmU)

1. Navigate to the Dispute Evidence object.

*Lightning/Classic: Navigate to the Dispute record > under Related Lists, click **New** for Dispute Evidence.*

1. Select a **Record Type** and click **Next**.
2. **Product Description**, **Customer Name**, **Customer Email**, **Billing Address**, and **Customer IP Address** are general fields for all Product Categories and should be filled out unless they are not applicable.
3. Stripe Data fields will populate automatically once the Dispute Evidence has been submitted.

**Note**

Enter as much information as you can into all sections of the Dispute Evidence record. Stripe provides best practice recommendations for preparing suitable responses. Click [here](https://stripe.com/docs/disputes#what-to-submit).

### Upload Documentation

Documentation can be uploaded through the **Upload Files** button under the Dispute Evidence Related List. [Embedded content](https://www.youtube.com/embed/FaFgpLU2Ldc)

1. Click **Upload Files**.
2. Upload all relevant documentation.
3. Click the "Title" link of all uploaded file(s).
4. Click **Go To Content Page** (Classic UI - located in the top right of the page) or click **Edit File Details** (Lightning UI - pencil icon in the top right of the page).  

*Can't find the Go To Content Page link? You might not have "Salesforce CRM Content User" enabled on your user record.*

![H_01_05_Dispute Evidence 2](https://cdn.document360.io/f977eec0-500f-40a3-b663-724a51f78075/Images/Documentation/H_01_05_Dispute%20Evidence%202.png)

1. Under Content Details, click edit, and select **Edit Content Details** (Classic UI).
2. Click **Type** and select the available type for your uploaded documentation.*Can't see the **Type** field in Lightning? Edit the Content Version Page Layout to include the **Type** field.*
3. Click **Save**. *Perform this process for each uploaded file.*

**Notes** * There is no limit to the number of files you can upload. * Upload documents per **Type**, do not combine all documents into one file upload. * Evidence cannot be added to Lost Disputes.

1. When you have uploaded and defined the **Type** of your documentation you are ready to submit your evidence.

### Submit Dispute Evidence

[Embedded content](https://www.youtube.com/embed/dkqpVTF71Zo)

1. Navigate to your Dispute Evidence record.
2. Click the **Submit** button.  

*Once you click the **Submit** button, you can no longer edit, delete, or add anything to the record.*

What happens when you submit evidence?

- Evidence is submitted to Stripe's financial partner.
- No one can edit, delete, or add anything to the Dispute record.
- Dispute **Status** = "Under Review".
- Dispute **Submission Count** = "1".
- Dispute **Has Evidence** = "TRUE".

Then you wait...50-75 days for a response :)

Submitting Evidence in Stripe:

If you submit evidence in the Stripe Dashboard (as opposed to Salesforce), all evidence information will get created in Salesforce as [Webhook Events](/v1/docs/webhook-event).

- The Dispute Evidence record will relate to the open Dispute.
- **File ID** fields will populate with a Stripe Id if a document was uploaded for that particular **Type**.

![H_01_05_Dispute Evidence 3](https://cdn.document360.io/f977eec0-500f-40a3-b663-724a51f78075/Images/Documentation/H_01_05_Dispute%20Evidence%203.png)

**NOTE:** Learn more about [evidence submission](https://stripe.com/docs/disputes#how-evidence-submission-works).

## Accept, Withdraw, and Refund Disputes

### Accept

Closing the Dispute for a charge indicates that you do not have any evidence to submit and are dismissing the Dispute, or acknowledging it as lost. The disputed amount and $15 fee will not be reimbursed.

Steps to Accept a Dispute:

1. Navigate to the Dispute record.
2. Click **Accept Dispute** button.
3. The **Status** will be updated to "Lost".

Losing a Dispute will update the original Transaction's **Payment Status** to "Refunded".

### Withdrawn

If your customer has created a Dispute in error and plans to withdraw it, you will need to submit proof in Dispute Evidence that the customer made a mistake.

When a Dispute is withdrawn:

- The Dispute **Status** = "Won".
- The original Transaction **Amount** will be refunded to you.
- An adjustment Transaction for $15.00 will be created. This is Stripe reimbursing you for the Dispute fee.
- **Payment Status** on the original Transaction will update to "Captured."

### Refund

If you are refunding a customer that has withdrawn their Dispute, it can take up to 75 days to refund the payment because the disputed claim must close first.

*Trying to refund a Transaction before the Dispute is closed will result in a failed Transaction.*

Steps for refunding a withdrawn Dispute:

1. Once the Dispute **Status** = "Won", navigate back to the original Transaction.
2. Click **Refund** at the top of the page (Classic UI) or click the drop-down arrow and select "Refund" (Lightning UI).

Additional information on [refunding a withdrawn Dispute](https://stripe.com/docs/disputes#refunding-a-withdrawn-dispute).

## Troubleshooting

If you have received an error with Disputes or have a question, please view our [Troubleshooting](https://docs.blackthorn.io/docs/payments-troubleshooting) or [FAQ](https://docs.blackthorn.io/docs/payments-faq) page.