Disputes API

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.

Accept Dispute

curl https://connect.squareupsandbox.com/v2/disputes/XDgyFu7yo1E2S5lQGGpYn/accept \
  -X POST \
  -H 'Square-Version: 2023-03-15' \
  -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:

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.
Submit the evidence. Your application calls the SubmitEvidence endpoint to submit the provided evidence to the bank. Square changes the dispute state to PROCESSING.

After your application uploads dispute evidence to Square using the Disputes API, the seller can no longer challenge or accept the dispute using the Disputes Dashboard.
If the due_at deadline passes with no action from the seller, Square automatically challenges the dispute on the seller’s behalf.

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 reason	Suggested evidence type
`AMOUNT_DIFFERS`	`AUTHORIZATION_DOCUMENTATION`
`CANCELLED`	`CANCELLATION_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`
`DUPLICATE`	`DUPLICATE_CHARGE_DOCUMENTATION` `RELATED_TRANSACTION_DOCUMENTATION`
`NO_KNOWLEDGE`	`AUTHORIZATION_DOCUMENTATION` `ONLINE_OR_APP_ACCESS_LOG` `RELATED_TRANSACTION_DOCUMENTATION`
`NOT_RECEIVED`	`AUTHORIZATION_DOCUMENTATION` `ONLINE_OR_APP_ACCESS_LOG` `RELATED_TRANSACTION_DOCUMENTATION`
`NOT_AS_DESCRIBED`	`CANCELLATION_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

1
2
3
4
5
6
7
8
9
10
11

curl https://connect.squareupsandbox.com/v2/disputes/bVTprrwk0gygTLZ96VX1oB/evidence-files \
  -X POST \
  -H 'Square-Version: 2023-03-15' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Accept: application/json' \
  -F '[email protected]/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:

1
2
3
4
5
6
7
8
9
10
11

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

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 has 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

1
2
3
4
5
6
7
8
9
10

curl https://connect.squareupsandbox.com/v2/disputes/bVTprrwk0gygTLZ96VX1oB/evidence-text \
  -X POST \
  -H 'Square-Version: 2023-03-15' \
  -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.

Submit Evidence

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

The following is an example response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

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

Do not 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 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.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

 {
  "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:

Event	Description
dispute.created	A cardholder has initiated a chargeback and a dispute was created.
dispute.state.updated	The 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.created	Evidence 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.deleted	Evidence 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.

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

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.

Process Disputes

Link to section
Accepting the Dispute

Link to section
Challenging the dispute

Important

Link to section
Evidence types

Link to section
Uploading evidence

Important

Link to section
Managing evidence

Link to section
Submitting evidence

Important

Link to section
Dispute outcomes

Link to section
Webhook notifications

Note

On this page

Process Disputes

Link to section Accepting the Dispute

Link to section Challenging the dispute

Important

Link to section Evidence types

Link to section Uploading evidence

Important

Link to section Managing evidence

Link to section Submitting evidence

Important

Link to section Dispute outcomes

Link to section Webhook notifications

Note

On this page

Link to section
Accepting the Dispute

Link to section
Challenging the dispute

Link to section
Evidence types

Link to section
Uploading evidence

Link to section
Managing evidence

Link to section
Submitting evidence

Link to section
Dispute outcomes

Link to section
Webhook notifications