Disputes API

Dispute API Objects

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

Disputes Permalink Get a link to this section

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 Permalink Get a link to this section

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:

  1. Upload evidence. Your application provides one or more pieces of text (DisputeEvidence) or file (DisputeEvidenceFile) evidence to Square. Note that Square automatically includes information on the seller's behalf, when available, to supplement the evidence they provide.

  2. Submit the evidence. Your application direct Square to submit the evidence to the bank.

Important

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

Evidence type Permalink Get a link to this section

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.

Dispute reasonSuggested evidence type
AMOUNT_DIFFERSAUTHORIZATION_DOCUMENTATION
CANCELLEDCANCELLATION_OR_REFUND_DOCUMENTATION
SERVICE_RECEIVED_DOCUMENTATION
PROOF_OF_DELIVERY_DOCUMENTATION
TRACKING_NUMBER
CUSTOMER_REQUESTS_CREDIT
PAID_BY_OTHER_MEANS
CANCELLATION_OR_REFUND_DOCUMENTATION
SERVICE_RECEIVED_DOCUMENTATION
PROOF_OF_DELIVERY_DOCUMENTATION
TRACKING_NUMBER
DUPLICATEDUPLICATE_CHARGE_DOCUMENTATION
RELATED_TRANSACTION_DOCUMENTATION
NO_KNOWLEDGEAUTHORIZATION_DOCUMENTATION
ONLINE_OR_APP_ACCESS_LOG
RELATED_TRANSACTION_DOCUMENTATION
NOT_RECEIVEDAUTHORIZATION_DOCUMENTATION
ONLINE_OR_APP_ACCESS_LOG
RELATED_TRANSACTION_DOCUMENTATION
NOT_AS_DESCRIBEDCANCELLATION_OR_REFUND_DOCUMENTATION
SERVICE_RECEIVED_DOCUMENTATION
PROOF_OF_DELIVERY_DOCUMENTATION
TRACKING_NUMBER

Upload evidence examples Permalink Get a link to this section

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.

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-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:

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-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}}"
  }'

Important

The seller must maintain a copy of the uploaded evidence if they want to reference it later. The evidence itself cannot be downloaded after it has been uploaded. The ListDisputeEvidence endpoint returns the metadata about uploaded evidence rather than the evidence itself.

Dispute evidence endpoints Permalink Get a link to this section

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 Permalink Get a link to this section

When available, Square automatically includes the following information on a seller's behalf to supplement the evidence they 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.

After you upload all of the seller evidence, order 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-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.

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 add or remove any evidence.

Disputes webhook notifications Permalink Get a link to this section

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 Permalink Get a link to this section

The Disputes API supports the following webhooks:

EventDescription
dispute.createdA dispute was created.
dispute.state.changedThe state of a dispute changed. This includes the dispute resolution (WON or LOST) reported by the bank. The event data includes details about what changed.
dispute.evidence.addedEvidence was added to a dispute from the Disputes Dashboard in the Seller Dashboard, in the Square Point of Sale application, or by calling the Disputes API (CreateDisputeEvidenceFile or CreateDisputeEvidenceText).
dispute.evidence.deletedEvidence was removed from a dispute from the Disputes Dashboard in the Seller Dashboard, in the Square Point of Sale application, or by calling DeleteDisputeEvidence.

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 Permalink Get a link to this section

  1. On notification of a new dispute, Square sends the dispute.created notification with an initial state of EVIDENCE_REQUIRED or INQUIRY_EVIDENCE_REQUIRED.

  2. The seller provides evidence to your application which then uploads it to Square. A dispute.evidence.added notification is sent to confirm that the evidence was successfully uploaded.

  3. Your application awaits the seller's decision to proceed with the challenge. When the seller decides to proceed, your application calls the SubmitEvidence endpoint. The state of the dispute changes to PROCESSING and your application receives the dispute.state.updated notification.

  4. Finally, the bank acts on the evidence submitted and notifies Square. The state of the dispute changes to WON, LOST, or EVIDENCE_REQUIRED if the bank requests more information. Your application receives the dispute.state.updated notification.