Process Disputes

Applies to: Disputes API

Use the Disputes API to access disputes, accept a dispute, or challenge a dispute by uploading and submitting evidence.

Link to section

Overview

Dispute objects are created by Square when a bank sends a notification that a cardholder is initiating a chargeback. Your application gets new Dispute objects by listening for dispute webhook events, polling the Disputes API periodically by calling ListDisputes, or calling RetrieveDispute if the dispute ID is known.

The Dispute object provides important details, including the reason for the dispute, the current state of the dispute, and the due_at deadline by which the seller must respond (by accepting or challenging the dispute). This information should be provided to the seller using your application so that they can make the most appropriate decision regarding the dispute.

Link to section

Accepting the Dispute

To accept a dispute, call the AcceptDispute endpoint. Square returns the disputed amount to the cardholder and updates the dispute state to ACCEPTED. The dispute is now closed.

Accept dispute

Link to section

Challenging the dispute

When a seller challenges a dispute, they must provide evidence that the payment was valid. Ultimately, the card-issuing bank determines the outcome of the dispute. However, the better evidence provided by the seller, the better chance they have of winning the dispute. Challenging a dispute using the Disputes API is a two-step process:

  1. Upload evidence - Your application provides one or more pieces of evidence related to the payment. These can be images, PDFs, or text. If available, Square automatically includes information such as business and cardholder details or receipts to supplement this evidence.
  2. Submit the evidence - Your application calls the SubmitEvidence endpoint to submit the provided evidence to the bank. Square changes the dispute state to PROCESSING.

Important

Link to section

Evidence types

Before a seller can challenge a dispute, they need to see the reason. Your application must display the Dispute.reason, which lets the seller decide what evidence to provide to support the validity of the transaction. Your application can upload evidence of any DisputeEvidenceType for a dispute regardless of the reason, but choosing the most appropriate evidence type helps the seller make the best case to the bank, which increases their chances of winning a dispute. If no evidence type is provided, Square assigns the GENERIC_EVIDENCE type.

The following table lists suggested evidence types to submit for each dispute reason. These suggestions are based on card network rules to help the seller make their best case when challenging a dispute.

Dispute reasonSuggested evidence type
AMOUNT_DIFFERSAUTHORIZATION_DOCUMENTATION
CANCELLEDCANCELLATION_OR_REFUND_DOCUMENTATION
SERVICE_RECEIVED_DOCUMENTATION
PROOF_OF_DELIVERY_DOCUMENTATION
TRACKING_NUMBER
CUSTOMER_REQUESTS_CREDIT
PAID_BY_OTHER_MEANS
CANCELLATION_OR_REFUND_DOCUMENTATION
SERVICE_RECEIVED_DOCUMENTATION
PROOF_OF_DELIVERY_DOCUMENTATION
TRACKING_NUMBER
DUPLICATEDUPLICATE_CHARGE_DOCUMENTATION
RELATED_TRANSACTION_DOCUMENTATION
NO_KNOWLEDGEAUTHORIZATION_DOCUMENTATION
ONLINE_OR_APP_ACCESS_LOG
RELATED_TRANSACTION_DOCUMENTATION
NOT_RECEIVEDAUTHORIZATION_DOCUMENTATION
ONLINE_OR_APP_ACCESS_LOG
RELATED_TRANSACTION_DOCUMENTATION
NOT_AS_DESCRIBEDCANCELLATION_OR_REFUND_DOCUMENTATION
SERVICE_RECEIVED_DOCUMENTATION
PROOF_OF_DELIVERY_DOCUMENTATION
TRACKING_NUMBER
Link to section

Uploading evidence

Call the CreateDisputeEvidenceFile or CreateDisputeEvidenceText endpoint to provide evidence to start challenging the request.

  • Use CreateDisputeEvidenceText for evidence such as tracking numbers, explanations, product descriptions, or any information that can be conveyed in a string with a maximum length of 500 characters.
  • Use CreateDisputeEvidenceFile for evidence such as receipts, screenshots of email threads with customers, or any evidence in image or PDF format.
  • Square supports these file types: image/tiff, application/pdf, image/jpeg, image/png, and image/heif. The file you upload can be up to 5 MB.

The following example shows a call to the CreateDisputeEvidenceFile endpoint, using a receipt scanned as a .tiff file as the evidence. In the request:

  • The dispute_id is provided in the endpoint URL.
  • The Authorization header specifies the access token of the seller responsible for the dispute.
  • The request includes the path of the file to upload.
  • The request body provides the evidence_type and idempotency_key. For more information, see Idempotency.

Create dispute evidence file

The following is an example response:

{ "evidence":{ "dispute_id": "bVTprrwk0gygTLZ96VX1oB", "evidence_file": { "filename": "receipt.tiff", "filetype": "image/tiff" }, "uploaded_at": "2022-03-03T15:30:39.000Z", "id": "Xi2jwjEmqW7LlGAWyylaUB" } }

Important

The seller must maintain a copy of the uploaded evidence if they want to reference it later. The evidence itself cannot be downloaded after it's been uploaded. The ListDisputeEvidence endpoint returns metadata about uploaded evidence, rather than the evidence itself.

To upload text evidence as a string, use the CreateDisputeEvidenceText endpoint as shown:

Create dispute evidence text

Link to section

Managing evidence

Prior to submission, your application can display a list of evidence provided for a dispute by calling the ListDisputeEvidence endpoint. If you know the evidence_id, you can call RetrieveDisputeEvidence. Note that these endpoints don't return the evidence itself, only metadata about the uploaded evidence. Sellers should retain copies of any evidence submitted in case they want to reference it later.

If you need to remove a piece of evidence, call DeleteDisputeEvidence with the dispute_id and evidence_id for the evidence you want to remove. Square doesn't send the bank any evidence that is removed. Note that you cannot remove evidence after submitting it to the bank using SubmitEvidence.

Link to section

Submitting evidence

After uploading all relevant evidence for the dispute, call SubmitEvidence to submit the provided evidence to the card-issuing bank. Square changes the dispute state to PROCESSING. At this point, the evidence for this dispute can no longer be removed or changed.

Submit evidence

The following is an example response:

Important

Don't call SubmitEvidence for each piece of uploaded evidence. Call the endpoint after the complete body of evidence has been uploaded to Square. By calling SubmitEvidence, the challenge process starts and you can no longer add or remove any evidence.

When available, Square automatically provides information to the card-issuing bank on a seller’s behalf to supplement the other evidence provided. This information might be business or cardholder details (name, address, phone number), Square receipts, related transactions, or tracking numbers.

Link to section

Dispute outcomes

When the seller challenges a dispute, there are three possible outcomes:

  • Win - The bank accepts the evidence as sufficient proof of a legitimate payment. Square updates the dispute state to WON and releases the held funds back to the seller’s bank account.
  • Lose - The bank rejects the evidence as insufficient proof. Square updates the dispute state to LOST and the cardholder is refunded.
  • Bank asks for more information - The bank is still deliberating and is requesting additional evidence. Square updates the dispute state to EVIDENCE_REQUIRED. In this case, the seller can upload more evidence or accept the cardholder's dispute.
Link to section

Webhook notifications

To receive the most timely information about disputes, subscribe to the dispute.created and dispute.state.updated webhooks. When a bank notifies Square of a new payment dispute, Square creates a dispute and sends the dispute.created webhook event notification, which includes the entire dispute object in its data.

The Disputes API supports the following webhooks:

EventDescription
dispute.createdA cardholder has initiated a chargeback and a dispute was created.
dispute.state.updatedThe state of a dispute has been updated. When the bank reaches a dispute resolution, the state changes to either WON or LOST. During the dispute process, the state can also change to PROCESSING or EVIDENCE_REQUIRED. The event data includes details about what was updated. This replaces the deprecated dispute.state.changed webhook.
dispute.evidence.createdEvidence was added to a dispute from the Disputes Dashboard in the Seller Dashboard, in the Square Point of Sale application, or by uploading evidence with the Disputes API. This replaces the deprecated dispute.evidence.added webhook.
dispute.evidence.deletedEvidence was removed from a dispute in the Disputes Dashboard in the Seller Dashboard, in the Square Point of Sale application, or by calling DeleteDisputeEvidence in the Disputes API. This replaces the deprecated dispute.evidence.removed webhook.

Note

Some webhooks have been deprecated in the V2 Disputes API. For a complete list of all Disputes API webhooks, including deprecated ones, see Disputes API. For more information about using webhooks, see Square Webhooks.