Disputes
How disputes are processed within Blackthorn | Payments (v 5.1+)
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, fees associated, and what to submit please review Stripe's documentation.
Setup
- Create a Webhook between Stripe and Salesforce.
Testing Disputes
- In order to test disputes you will need to use a specific test card created for dispute simulation. See here.
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 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 thePayment Gateway Fee
field on the refund transaction.


Disputed Transaction


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. -
Dispute
Reason
is what the cardholder defined the disputed payment as.
Dispute reasons -
The
Past Due, Has Evidence and Refundable
fields are for tracking 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 theStatus
= "Under Review".
It has now been submitted to Stripe's financial partner 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 (for users in the United States) by the card network. If you win the 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 the Dispute
Status
= "Lost" and the original Transaction'sPayment 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 Types for Dispute Evidence. Record Types 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


Creating a New Dispute Evidence Record
- Navigate to the Dispute Evidence object.
Lightning/Classic: Navigate to the Dispute record, under Related Lists click "New" for Dispute Evidence.
-
Select a Record Type and click "Next."
-
Product Description
,Customer Name
,Customer Email
,Billing Address
, andCustomer IP Address
are general fields for all Product Categories and should be filled out unless they are not applicable. -
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 evidence record. Stripe provides best practice recommendations for preparing suitable responses. Click here.
Upload Documentation
Documentation can be uploaded through the "Upload Files" button under the Dispute Evidence Related List.
- Click on "Upload Files."
- Upload all relevant documentation.
- Click on the
Title
link of all uploaded file(s). - Click on
Go To Content Page
(classic UI-located in the top right of the page) or clickEdit 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.


- Under Content Details, click edit, and select
Edit Content Details
(Classic UI). - Click
Type
and select the available type for your uploaded documentation.
Can't see theType
field in Lightning? Edit the Content Version Page Layout to include theType
field. - Click Save.
Do this 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.
When you have uploaded and defined the Type
of your documentation you are ready to Submit
your evidence.
Submit Dispute Evidence
- Navigate to your Dispute Evidence record.
- Click the
Submit
button.
Once you click this 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 can no longer edit, delete, or add anything to the record.
- Dispute
Status
= "Under Review". - Dispute
Submission Count
= 1. - Dispute
Has Evidence
is checked.
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.
-
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 particularType
.
`


Note
- Learn more about evidence submission.
Accept, Withdraw, and Refund Disputes
Accept
Closing the Dispute for a charge indicates that you do not have any evidence to submit and are essentially ‘dismissing’ the Dispute, acknowledging it as lost. The disputed amount and $15 fee will not be reimbursed to you.
Steps to Accept a Dispute:
-
Navigate to the Dispute record.
-
Click
Accept Dispute
button.
Status will update to "Lost".
Losing a Dispute will update the original Transactions
Payment Status` = "Refunded."
Withdrawn
If your customer has created a Dispute in error and plans to withdraw it, 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 your 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:
- Once the Dispute
Status
= "Won", navigate back to the original Transaction and clickRefund
at the top of the page (Classic UI) or click the drop-down arrow and selectRefund
(Lightning UI).
Additional information on refunding a withdrawn Dispute.
Troubleshooting/FAQ
If you have received an error with Disputes or have a question, please view our Troubleshooting and Frequently Asked Questions.
Updated 11 months ago