Disputes API

Customer disputes can be frustrating for sellers. Sellers may have to manage numerous chargebacks at once, or need to submit multiple forms of evidence to challenge disputes. Until recently, sellers had to do this manually through their Square Disputes Dashboard, which can be time-consuming and resource-intensive for those with high chargeback volumes.

We’re excited to announce Disputes API to help automate the process of retrieving and challenging disputes. With this new API, you can build solutions that programmatically send dispute notifications to sellers (using webhooks) and automatically submit evidence to help sellers improve their win-rate.

Plus, you can enable sellers to get insights into the items that are most frequently disputed, the most common reasons for customer disputes, and the financial impact disputes have on their business.

Submitting Evidence

The most critical factor in winning a dispute is finding the right evidence to support a case. That’s why Square makes it easy with a set of predefined evidence types (evidence_type) based on what the customer’s bank requires.

Here’s an example of the REBUTTAL_EXPLANATION evidence type:

curl -X POST \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
-H 'Content-Type: application/json' \
-d '{
      "idempotency_key":"general_2_string",
      "evidence_type":"REBUTTAL_EXPLANATION",
      "evidence_text":"the customer ordered the item twice; on date-1 and date-2"
    }' \
'https://connect.squareupsandbox.com/v2/disputes/{{DISPUTE_ID}}/evidence_text'

And an example response:

{
   "evidence":{
      "evidence_id":"ny5BJ2JvzHZlNIReqkJAzC",
      "dispute_id":"QQa9GkoZNFhBKPYWYgRq4B",
      "evidence_text": "the customer ordered the item twice; on date-1 and date-2",
      "uploaded_at":"2021-06-07T17:52:35.000Z"
   }
}

After a seller uploads evidence, Square packages the evidence, adds helpful information of our own (when available), and submits it all to the bank.

Retrieving Disputes Status

Once a seller has submitted evidence, Square will keep them informed of the response from their customer’s bank (Square does not decide who wins or loses the dispute). Once the dispute status has been provided, Square will change the status to WON, LOST, or EVIDENCE_REQUIRED.

To verify the status, call RetrieveDispute.

curl -X GET \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
-H 'Content-Type: application/json' \
'https://connect.squareupsandbox.com/v2/disputes/{{DISPUTE_ID}}'

Here’s an example response, showing the state has been updated to “WON”.

{
   "type":"dispute",
   "id":"xe8rb2X4ifCcWd1xIjuaKB",
   "object":{
      "amount_money":{
         "amount":8803,
         "currency":"USD"
      },
      "brand_dispute_id":"6rjByNRfR5OpFZeJs_PNKw",
      "card_brand":"VISA",
      "created_at":"2019-12-16T01:21:59.983Z",
      "dispute_id":"xe8rb2X4ifCcWd1xIjuaKB",
      "disputed_payment":{
         "payment_id":"0dG0pUTlY5bYMr2CJbttiLByvaB"
      },
      "due_at":"2019-12-30T00:00:00.000Z",
      "evidence_ids":[
         "Ri6eRTG3xjT0nnUfN0SoQ",
         "WKoZd9VlUEZSfI6Q4lu0cD"
      ],
      "location_id":"S8GWD5R9QB376",
      "reason":"DUPLICATE",
      "reported_date":"2019-12-16T00:00:00.000Z",
      "state":"WON",
      "updated_at":"2019-12-23T02:41:38.024Z",
      "version":5
   }
}

Get Started

Disputes API is available in the U.S., Canada, UK, Ireland, Australia, and Japan for all developers building a payment integration with Square. Check out the docs site and technical references to learn how to get started.

As always, please share your feedback in our community Slack channel or Square Developer Forums. If you want to keep up to date with the rest of our content, be sure to follow this blog and our Twitter account!