Process Disputes

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

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.

curl https://connect.squareupsandbox.com/v2/disputes/XDgyFu7yo1E2S5lQGGpYn/accept \
  -X POST \
  -H 'Square-Version: 2022-09-21' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json'

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:

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.

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.

curl https://connect.squareupsandbox.com/v2/disputes/bVTprrwk0gygTLZ96VX1oB/evidence-files \
  -X POST \
  -H 'Square-Version: 2022-09-21' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Accept: application/json' \
  -F 'file=@/path/to/file/receipt.tiff' \
  -F 'request={
    "idempotency_key": "3fee30ce-e0a0-4152-b53b-13aa1533b0a3",
    "evidence_type": "RECEIPT",
    "content_type": "image/tiff"
  }'

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"
  }
}

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

curl https://connect.squareupsandbox.com/v2/disputes/bVTprrwk0gygTLZ96VX1oB/evidence-text \
  -X POST \
  -H 'Square-Version: 2022-09-21' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "evidence_text": "The customer purchased the item twice, on Feb 28 and March 1",
    "idempotency_key": "11d4dc7a-b83e-486b-8875-426b7e520f4a",
    "evidence_type": "REBUTTAL_EXPLANATION"
  }'

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 do not 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 does not 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.

curl https://connect.squareupsandbox.com/v2/disputes/bVTprrwk0gygTLZ96VX1oB/submit-evidence \
  -X POST \
  -H 'Square-Version: 2022-09-21' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json'

The following is an example response:

{
  "dispute": {
    "amount_money": {
      "amount": 2273,
      "currency": "USD"
    },
    "reason": "DUPLICATE",
    "state": "PROCESSING",
    "due_at": "2022-03-16T00:00:00.000Z",
    "disputed_payment": {
      "payment_id": "BqzL87eLnz9gJRuoiIYSY44p9ORZY"
    },
    "card_brand": "VISA",
    "created_at": "2022-03-02T16:38:37.460Z",
    "updated_at": "2022-03-03T15:36:53.297Z",
    "brand_dispute_id": "P9td9draSX6ACrUO3KEI6Q",
    "version": 5,
    "location_id": "L1HN3ZMTZEB87",
    "id": "bVTprrwk0gygTLZ96VX1oB",
    "reported_at": "2022-03-02T00:00:00.000Z"
  }
}

When available, Square automatically provides information to the card-issuing bank on a seller’s behalf to supplement the other evidence provided. This information may 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.

 {
  "merchant_id": "MLFG72TMMXMCQ",
  "location_id": "L1HN3ZMTZEB87",
  "type": "dispute.created",
  "event_id": "3ad92963-cddd-4f80-9c87-9fd75b4954e5",
  "created_at": "2022-03-02T16:38:37.46Z",
  "data": {
    "type": "dispute",
    "id": "bVTprrwk0gygTLZ96VX1oB",
    "object": {
      "dispute": {
        "amount_money": {
          "amount": 2273,
          "currency": "USD"
        },
        "brand_dispute_id": "P9td9draSX6ACrUO3KEI6Q",
        "card_brand": "VISA",
        "created_at": "2022-03-02T16:38:37.460Z",
        "disputed_payment": {
          "payment_id": "BqzL87eLnz9gJRuoiIYSY44p9ORZY"
        },
        "due_at": "2022-03-16T00:00:00.000Z",
        "id": "OWo09e15R49UrfXjG5Bod",
        "location_id": "L1HN3ZMTZEB87",
        "reason": "DUPLICATE",
        "reported_at": "2022-03-02T00:00:00.000Z",
        "state": "EVIDENCE_REQUIRED",
        "updated_at": "2022-03-02T16:38:37.460Z"
      }
    }
  }
}

The Disputes API supports the following webhooks:

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