Dispute API Objects

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

Disputes

A buyer's charge-back request is maintained, and adjudicated by a card issuing bank. A Dispute object is the interface that your application uses to take actions related to the charge-back requests. It is created by Square when a bank sends notification that a card holder is requesting a charge-back. Your application gets new Dispute objects by listening for disputes webhook events, polling the Disputes API periodically by calling ListDisputes, or calling RetrieveDispute if the dispute ID is known.

The Dispute object also provides the dispute reason, the current state of the dispute, and the due_at deadline by which you need to respond to the dispute (accept or challenge).

Dispute evidence

When a seller challenges a dispute, their likelihood of winning depends on the evidence they provide. Ultimately, the card-issuing bank determines who wins. However, the better evidence they provide, the better chance they have of winning the dispute. Challenging a dispute using the Disputes API is a two-step process:

Evidence type

Square provides an enumerated set of predefined evidence types. Choosing the correct evidence type is important because it helps the seller make the best case to the bank and increases their chances of winning a dispute. The following are related guidelines:

Your application can upload one or more pieces of evidence categorized by DisputeEvidenceType for all disputes, regardless of the reason. In addition to general evidence, the following table lists the 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.

Upload evidence examples

The following CreateDisputeEvidenceFile request is an example of a receipt scanned as a tiff file and submitted as evidence. The request includes the following:

• DISPUTE_ID in the endpoint URL identifies the dispute that the evidence file being uploaded for.

• Authorization header specifies the access token of the seller responsible for the dispute.

• evidence provides the path of the file to upload and the type of the evidence file.

• The request body provides the evidence_type and idempotency_key. For more information, see Idempotency.

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

The following is a sample response:

{
   "evidence":{
      "id":"avDDMzWFA9TESvDCTHkrg",
      "dispute_id":"ty2li14gPpMjEjpzDrH1fD",
      "evidence_file":{
         "filename":"sampleTFF.tiff",
         "filetype":"image/tiff",
         "evidence_type":"GENERIC_EVIDENCE"

      },
      "uploaded_at":"2019-12-17T01:36:48.000Z"
   }
}

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

curl https://connect.squareupsandbox.com/v2/disputes/DISPUTE_ID/evidence-text \
  -X POST \
  -H 'Square-Version: 2021-10-20' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{{UNIQUE_KEY}}",
    "evidence_type": "{{EVIDENCE_TYPE}}",
    "evidence_text": "{{STRING_TO_UPLOAD}}"
  }'

Dispute evidence endpoints

You can use the ListDisputeEvidence and DeleteDisputeEvidence endpoints to manage seller dispute evidence. It is important to note that after you call SubmitEvidence, the dispute state is PROCESSING and your application cannot add more evidence or delete any of the uploaded evidence.

Square-provided evidence

When available, Square automatically includes the following information on a seller's behalf to supplement the evidence they provide:

After you upload all of the seller evidence, order Square to submit the evidence to the bank by sending a SubmitEvidence request as shown:

curl https://connect.squareupsandbox.com/v2/disputes/DISPUTE_ID/submit-evidence \
  -X POST \
  -H 'Square-Version: 2021-10-20' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json'

In the request:

• DISPUTE_ID in the endpoint URL identifies the dispute for which the evidence is being submitted.

• access_token in the Authorization header identifies the seller responsible for the dispute.

The following is a sample response:

{
   "dispute":{
      "id":"WoaG8ihupXrqNYU6Xyu9f",
      "amount_money":{
         "amount":100,
         "currency":"USD"
      },
      "reason":"RETURNED",
      "state":"PROCESSING",
      "due_at":"2019-06-03T00:00:00.000Z",
      "disputed_payments":[
         {
            "payment_id":"ayTy9EDmrlEI3QWf9iLQXrPfuaB"
         }
      ],
      "card_brand":"american_express",
      "created_at":"2019-05-21T17:45:16.199Z",
      "updated_at":"2019-05-22T00:24:10.358Z",
      "brand_dispute_id":"100000415900",
      "reported_at":"2019-05-20T00:00:00.000Z",
      "version":3
   }
}

When you call SubmitEvidence, Square compiles all the evidence and submits it to the bank, starting the dispute challenge process.

Disputes webhook notifications

If you want your application to receive a notification when Square has responded to a bank by creating a dispute, subscribe to the dispute.created webhook. Square also updates the state of a dispute on further action by the bank or your application. For more information about using webhooks, see Webhooks Overview.

Subscribe to the dispute.state.updated to get notification when a bank responds to a dispute challenge or when your application has taken an action on a dispute.

When a bank notification is received, Square creates a dispute and sends this event notification. The event notification provides metadata describing the webhook event and also includes the new dispute object:

{
  "merchant_id": "GEF74Kexample",
    "location_id": "S8GWD5example",
  "type": "dispute.created",
  "event_id": "7c912a86-fffb-45e7-bfcb-8c7a7b16751b",
  "created_at": "2019-12-23T02:41:38.024Z",
  "data": {
    "type": "dispute",
    "id": "xe8rb2X4ifCcWd1example",
    "object": {
          … <The Dispute object>
    }
  }
}

Webhook events

The Disputes API supports the following webhooks:

As a dispute takes the next step through the resolution process, Square sends one of the following events:

• dispute.created. A card holder has requested a charge back and the issuing bank notifies Square of the dispute.

• dispute.state.updated. The state of the Dispute has been updated.

• dispute.evidence.added. Your application has uploaded a piece of evidence to the dispute.

• dispute.evidence.deleted. Your application has removed evidence from a dispute.

Event order