Beta Release
This is pre-release documentation for an API in public beta and is subject to change.
Disputes API

Process Disputes

This section provides an overview on how to use the Disputes API to access dispute data, accept a dispute, or submit evidence to challenge a dispute.

Access Dispute information
Permalink Get a link to this section

After a cardholder initiates a dispute, the cardholder’s bank notifies Square of the claim. Square stores dispute information by creating a Dispute object. The following is an example Dispute instance:

{
   "dispute_id":"QQa9GkoZNFhBKPYWYgRq4B",
   "amount_money":{
      "amount":8815,
      "currency":"USD"
   },
   "reason":"AMOUNT_DIFFERS",
   "state":"EVIDENCE_REQUIRED",
   "due_at":"2019-12-30T00:00:00.000Z",
   "disputed_payment":{
      "payment_id":"ScM5CtZGuU9r2fZdRpOXlZe4uaB"
   },
   "card_brand":"VISA",
   "created_at":"2019-12-16T01:26:07.184Z",
   "updated_at":"2019-12-16T01:26:07.184Z",
   "brand_dispute_id":"CD8CQF_PS26LwjySZbUoAw",
   "reported_date":"2019-12-16T00:00:00.000Z",
   "location_id":"S8GWD5R9QB376"
}

Among other things, the Dispute object provides the dispute reason, the current state of the dispute, and the due_at deadline indicating when you need to respond to the dispute (accept or challenge).

Important

If you don’t respond by the due_at the deadline, the dispute state changes from evidence_required to processing and you cannot take further action on the dispute.

You have the following options to get Dispute data:

  • Subscribe to dispute.created webhook. Upon receiving a bank notification, Square creates a dispute and sends this event notification. The event notification includes dispute information as shown:

    {
  "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": {
      … <information the Dispute object provides>
    }
  }
}

    For a list of dispute related webhooks and subscription information, see Subscribe to Events.

  • Use the ListDisputes endpoint. The access token in the Authorization header identifies the specific Square seller account for which to return the dispute list.

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

    The following is a sample response. It shows a dispute having EVIDENCE_REQUIRED as the state.

    {
   "disputes":[
      { 
         "dispute_id":"ty2li14gPpMjEjpzDrH1fD",
         "amount_money":{ 
            "amount":8801,
            "currency":"USD"
         },
         "reason":"AMOUNT_DIFFERS",
         "state":"PROCESSING",
         "due_at":"2019-12-30T00:00:00.000Z",
         "disputed_payment":{ 
            "payment_id":"aqzsteNctof09YaYw221GxvtvaB"
         },
         "evidence_ids":[ 
            "avDDMzWFA9TESvDCTHkrg"
         ],
         "card_brand":"VISA",
         "created_at":"2019-12-16T18:07:57.373Z",
         "updated_at":"2019-12-17T01:38:51.767Z",
         "brand_dispute_id":"JVhxqiFNQ3eAJCJ_yBmAgg",
         "reported_date":"2019-12-16T00:00:00.000Z",
         "version":3,
         "location_id":"S8GWD5R9QB376"
      }
    …
   ]
}

Dispute reason
Permalink Get a link to this section

When a dispute state indicates evidence is required, you can either accept or challenge the dispute. If the seller wants to challenge the dispute, then they should submit evidence that directly addresses the dispute reason type. For a list of dispute reasons and related explanations, see the reason field of the Dispute type.

Challenge a dispute
Permalink Get a link to this section

When you challenge a dispute, your likelihood of winning depends on the evidence you provide. Ultimately, the card issuing bank determines who wins, however, the better evidence you provide, the better chances you have of winning the dispute. Challenging a dispute using the Disputes API is a two-step process:

  1. Upload evidence — You provide one or more pieces of evidence to Square. Note that Square automatically includes information on your behalf, when available, to supplement the evidence you provide.

  2. Submit the evidence — You direct Square to submit the evidence to the bank.

Step 1: Upload evidence
Permalink Get a link to this section

When uploading evidence you provide both the evidence and the evidence type. The key things about the evidence are:

  • You can provide general evidence and dispute-specific evidence (addressing the cardholder’s specific claim). General information refers to information the card networks find important regardless of the dispute reason.

  • You can upload evidence as a file ( CreateDisputeEvidenceFile) or a string ( CreateDisputeEvidenceText). For example, you might upload a PDF of an email thread with the customer as evidence or you might upload a shipment tracking number directly in the request body.

    Square supports these file types: image/tiff, application/pdf, image/jpeg, image/png, image/heif. The file you upload can be up to 5 MB in size.

    Each piece of evidence must be uploaded individually using the CreateDisputeEvidence request.

Evidence type
Permalink Get a link to this section

When you upload a piece of evidence, you can also specify what type of evidence it is. Square provides a set of predefined evidence types. For a list of evidence types and related explanations, see the evidence_type field described in one of these endpoints: CreateDisputeEvidenceFile or CreateDisputeEvidenceText.

Choosing the correct evidence type is important; it helps you make the best case to the bank and increases your chances of winning a dispute. The following are related guidelines:

  • Suggested evidence types for all disputes, regardless of the reason. You can upload one or more of these general evidence types.

    Dispute Reason Suggested Evidence Types
    Upload these evidence types for any dispute reason cardholder_communication
    cardholder_information
    purchase_acknowledgement
    product_or_service_description
    receipt
    service_received_documentation
    proof_of_delivery_documentation
    rebuttal_explanation

  • 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 you make your best case when challenging a dispute.

    Dispute Reason Suggested Evidence Types
    NO_KNOWLEDGE authorization_documentation, online_or_app_access_log, related_transaction_documentation
    NOT_RECEIVED online_or_app_access_log, service_received_documentation, proof_of_delivery_documentation, tracking_number
    NOT_AS_DESCRIBED cancellation_or_refund_documentation, service_received_documentation, proof_of_delivery_documentation, tracking_number
    CUSTOMER_REQUESTS_CREDIT OR PAID_BY_OTHER_MEANS cancellation_or_refund_documentation, service_received_documentation, proof_of_delivery_documentation, tracking_number
    DUPLICATE duplicate_charge_documentation, related_transaction_documentation
    CANCELLED cancellation_or_refund_documentation, service_received_documentation, proof_of_delivery_documentation, tracking_number
    AMOUNT_DIFFERS authorization_documentation

Example: Upload evidence
Permalink Get a link to this section

The following CreateDisputeEvidenceFile request is an example of a tiff file submitted (for example, a scanned receipt) as evidence. The request includes:

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

  • 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 -X POST \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
-H 'Content-Type: multipart/form-data' \
-F 'evidence=@/path/to/file/filename.tiff' \
-F 'request={ "idempotency_key":"{{UNIQUE_KEY}}", "evidence_type":"{{EVIDENCE_TYPE}}", "content_type":"image/tiff" }' \
'https://connect.squareupsandbox.com/v2/disputes/{{DISPUTE_ID}}/evidence_file'

The following is a sample response:

{
   "evidence":{
      "evidence_id":"avDDMzWFA9TESvDCTHkrg",
      "dispute_id":"ty2li14gPpMjEjpzDrH1fD",
      "evidence_file":{
         "filename":"samplePDF.pdf",
         "filetype":"application/pdf",
         "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 -X POST \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
-H 'Content-Type: application/json' \
-d '{ "idempotency_key":"{{UNIQUE_KEY}}", "evidence_type":"{{EVIDENCE_TYPE}}", "evidence_text":"{{STRING_TO_UPLOAD}}" }' \
'https://connect.squareupsandbox.com/v2/disputes/{{DISPUTE_ID}}/evidence_text'

Important

You must maintain a copy of the evidence uploaded if you want to reference it later. There is no way for you to download the evidence after you upload it.

Helper endpoints to manage evidence
Permalink Get a link to this section

You can use the ListDisputeEvidence and RemoveDisputeEvidence endpoints to manage your dispute evidence. It is important to note that after you call SubmitEvidence, you cannot remove any of the evidence submitted.

Square provided evidence
Permalink Get a link to this section

When available, Square automatically includes the following information on your behalf to supplement the evidence you provide.

Evidence Description
Business information The name of the business, address, and phone number for the entity that is receiving the dispute. This will automatically be populated if available.
Cardholder information The cardholder name, email address, and phone number for the cardholder filing the dispute. This will automatically be populated if available.
Shipping address This will be automatically populated if available.
Receipt Any receipt/proof of purchase sent to the cardholder at the time of purchase confirming the details of the charge. This will automatically be populated if available (e.g. Square receipt).
Related transactions Square receipts for up to 5 related transactions made by the cardholder prior to the dispute, that remain undisputed.

Step 2: Submit evidence
Permalink Get a link to this section

After you upload all pieces of evidence, direct Square to submit the evidence to the bank by sending a SubmitEvidence request as shown.

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

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":{
      "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"
         }
      ],
      "evidence_ids":[
         "frWAgRJ94luIfWt0pDsXXD"
      ],
      "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_date":"2019-05-20T00:00:00.000Z",
      "version":3
   }
}

The response shows Square changed the dispute state from EVIDENCE_REQUIRED to PROCESSING. Square also updates the dispute state based on the response from the cardholder's bank. The state can change to either WON, LOST, or EVIDENCE_REQUIRED if the bank requests more information.

There is no endpoint to explicitly challenge a dispute. Instead, when you call SubmitEvidence, Square compiles all of the evidence and then submits it to the bank. In other words, calling SubmitEvidence triggers the dispute challenge process. You should only call SubmitEvidence after you have finished uploading all pieces of evidence individually, using the CreateDisputeEvidence endpoint. You should not call SubmitEvidence for each piece of evidence uploaded. Remember, after you call SubmitEvidence, you will no longer be able to remove any evidence.

Accept a dispute
Permalink Get a link to this section

If you choose to accept a dispute, send a POST request to the AcceptDispute endpoint. This is not reversible; once you accept a dispute, you cannot go back and challenge it later. The following is an example request.

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

In the example:

  • dispute_id in the endpoint URL identifies the dispute being accepted.

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

Upon accepting the dispute, Square debits the disputed amount from the balance of your Square account. If your Square balance does not have sufficient funds, Square debits the funds from your associated bank account. The following is a sample response.

{
   "dispute":{
      "dispute_id":"OZWi9TqDBSgqSrLexample",
      "amount_money":{
         "amount":100,
         "currency":"USD"
      },
      "reason":"FRAUD",
      "state":"ACCEPTED",
      "due_at":"2019-06-03T00:00:00.000Z",
      "disputed_payments":[
         {
            "payment_id":"OK8JwPxVnkUVThdvgPAY6xLwuaB"
         }
      ],
      "card_brand":"american_express",
      "created_at":"2019-05-21T17:45:16.284Z",
      "updated_at":"2019-05-21T23:07:13.782Z",
      "brand_dispute_id":"100000294534",
      "reported_date":"2019-05-20T00:00:00.000Z",
      "version":2
   }
}

The state value ACCEPTED indicates that you have accepted the dispute.

Next steps

The following sections provide an example walkthrough in which you use cURL commands to test the Disputes API.