Introducing the new Square Disputes API Beta

Automate the process of retrieving and challenging disputes to save sellers time and money

Reddit
LinkedIn

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 Square 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":"2020-01-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
   }
}

Beta Availability

Disputes API is available in beta in the U.S. and Canada, with international coverage coming soon. Check out the docs site and technical references to learn how to get started.

If you want to keep up to date with the rest of our content, be sure to follow this blog & our Twitter account, and sign up for our developer newsletter! We also have a Slack community for connecting with and talking to other developers implementing Square APIs.