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

Process Disputes

You can 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"
}

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).

Important

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

A seller may also take action on a dispute by using the Disputes Dashboard. If they start the process in the dashboard before action is taken in your application, the dispute state changes to processing and your application cannot take further action.

You have the following options to get Dispute data:

  • Subscribe to the dispute.created webhook.

  • Use the ListDisputes endpoint.

Subscribe to the dispute.created webhook Permalink Get a link to this section

When a bank notification is received, 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 Permalink Get a link to this section

In the following example ListDisputes request, the access token in the Authorization header identifies the specific Square seller account for which to return the dispute list.

List Disputes
  • 1
  • 2
  • 3
  • 4
curl https://connect.squareupsandbox.com/v2/disputes \
  -H 'Square-Version: 2021-03-17' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json'

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 that evidence is required, you can accept or challenge the dispute. If the seller wants to challenge the dispute, the seller 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 chance 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.

Important

Once your app has uploaded evidence in a dispute to Square by using the Disputes API, the seller can no longer challenge or accept a dispute using the Disputes Dashboard.

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

When uploading evidence, you provide both the evidence and the evidence type. You can:

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

  • Upload evidence as a file ( CreateDisputeEvidenceFile) or a string ( CreateDisputeEvidenceText). For example, you might upload a PDF file 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, and 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 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 because it helps you make the best case to the bank and increases your chances of winning a dispute. The following are related guidelines:

You can upload one or more of these general evidence types for all disputes, regardless of the 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 reasonSuggested evidence type
NO_KNOWLEDGEauthorization_documentation, online_or_app_access_log, and related_transaction_documentation
NOT_RECEIVEDauthorization_documentation, online_or_app_access_log, and related_transaction_documentation
NOT_AS_DESCRIBEDcancellation_or_refund_documentation, service_received_documentation, proof_of_delivery_documentation, and tracking_number
CUSTOMER_REQUESTS_CREDIT or PAID_BY_OTHER_MEANScancellation_or_refund_documentation, service_received_documentation, proof_of_delivery_documentation, and tracking_number
DUPLICATEduplicate_charge_documentation and related_transaction_documentation
CANCELLEDcancellation_or_refund_documentation, service_received_documentation, proof_of_delivery_documentation, and tracking_number
AMOUNT_DIFFERSauthorization_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 the following:

  • 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.

Create Dispute Evidence File
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
curl https://connect.squareupsandbox.com/v2/disputes/DISPUTE_ID/evidence_file \
  -X POST \
  -H 'Square-Version: 2021-03-17' \
  -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":{
      "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:

Create Dispute Evidence Text
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
curl https://connect.squareupsandbox.com/v2/disputes/DISPUTE_ID/evidence_text \
  -X POST \
  -H 'Square-Version: 2021-03-17' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{{UNIQUE_KEY}}",
    "evidence_type": "{{EVIDENCE_TYPE}}",
    "evidence_text": "{{STRING_TO_UPLOAD}}"
  }'

Important

You must maintain a copy of the uploaded evidence 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 submitted evidence.

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:

EvidenceDescription
Business informationThe name of the business, address, and phone number for the entity that is receiving the dispute. This is automatically populated if available.
Cardholder informationThe cardholder name, email address, and phone number for the cardholder filing the dispute. This is automatically populated if available.
Shipping addressThis is automatically populated if available.
ReceiptAny receipt or proof of purchase (for example, a Square receipt) sent to the cardholder at the time of purchase confirming the details of the charge. This is automatically populated if available.
Related transactionsSquare receipts for up to five related transactions made by the cardholder prior to the dispute and that remain undisputed.

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

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

Submit Evidence
  • 1
  • 2
  • 3
  • 4
  • 5
curl https://connect.squareupsandbox.com/v2/disputes/DISPUTE_ID/submit-evidence \
  -X POST \
  -H 'Square-Version: 2021-03-17' \
  -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":{
      "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 that 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 WON, LOST, or EVIDENCE_REQUIRED if the bank requests more information.

When you call SubmitEvidence, Square compiles all the evidence and submits it to the bank, starting the dispute challenge process. You should only call SubmitEvidence after you have finished uploading all pieces of evidence individually by using the CreateDisputeEvidence endpoint.

Important

Do not call SubmitEvidence for each piece of uploaded evidence. Call the endpoint after the complete body of evidence has been uploaded to Square. When you call SubmitEvidence, the challenge process is started and you can no longer 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. When you accept a dispute, you cannot go back and challenge it later.

The following is an example request:

Accept Dispute
  • 1
  • 2
  • 3
  • 4
  • 5
curl https://connect.squareupsandbox.com/v2/disputes/DISPUTE_ID/accept \
  -X POST \
  -H 'Square-Version: 2021-03-17' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json'

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.

When you accept the dispute, Square debits the disputed amount from the balance of your Square account. If your Square account 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.