Learn how to process disputes using the Square Disputes API.
Disputes API

Process Disputes

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

Dispute objects are created by Square when a bank sends a notification that a cardholder is initiating a chargeback. Your application gets new Dispute objects by listening for dispute webhook events, polling the Disputes API periodically by calling ListDisputes, or calling RetrieveDispute if the dispute ID is known.

The Dispute object provides important details, including the reason for the dispute, the current state of the dispute, and the due_at deadline by which the seller must respond (by accepting or challenging the dispute). This information should be provided to the seller using your application so that they can make the most appropriate decision regarding the dispute.

To accept a dispute, call the AcceptDispute endpoint. Square returns the disputed amount to the cardholder and updates the dispute state to ACCEPTED. The dispute is now closed.

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

When a seller challenges a dispute, they must provide evidence that the payment was valid. Ultimately, the card-issuing bank determines the outcome of the dispute. However, the better evidence provided by the seller, 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 evidence related to the payment. These can be images, PDFs, or text. If available, Square automatically includes information such as business and cardholder details or receipts to supplement this evidence.

  2. Submit the evidence. Your application calls the SubmitEvidence endpoint to submit the provided evidence to the bank. Square changes the dispute state to PROCESSING.

Important

Before a seller can challenge a dispute, they need to see the reason. Your application must display the Dispute.reason, which lets the seller decide what evidence to provide to support the validity of the transaction. Your application can upload evidence of any DisputeEvidenceType for a dispute regardless of the reason, but choosing the most appropriate evidence type helps the seller make the best case to the bank, which increases their chances of winning a dispute. If no evidence type is provided, Square assigns the GENERIC_EVIDENCE type.

The following table lists 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

Call the CreateDisputeEvidenceFile or CreateDisputeEvidenceText endpoint to provide evidence to start challenging the request.

  • Use CreateDisputeEvidenceText for evidence such as tracking numbers, explanations, product descriptions, or any information that can be conveyed in a string with a maximum length of 500 characters.

  • Use CreateDisputeEvidenceFile for evidence such as receipts, screenshots of email threads with customers, or any evidence in image or PDF format.

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

The following example shows a call to the CreateDisputeEvidenceFile endpoint, using a receipt scanned as a .tiff file as the evidence. In the request:

  • The dispute_id is provided in the endpoint URL.

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

  • The request includes the path of the file to upload.

  • 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/bVTprrwk0gygTLZ96VX1oB/evidence-files \
  -X POST \
  -H 'Square-Version: 2022-09-21' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Accept: application/json' \
  -F 'file=@/path/to/file/receipt.tiff' \
  -F 'request={
    "idempotency_key": "3fee30ce-e0a0-4152-b53b-13aa1533b0a3",
    "evidence_type": "RECEIPT",
    "content_type": "image/tiff"
  }'

The following is an example response:

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 metadata about uploaded evidence, rather than the evidence itself.

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

Create Dispute Evidence Text
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
curl https://connect.squareupsandbox.com/v2/disputes/bVTprrwk0gygTLZ96VX1oB/evidence-text \
  -X POST \
  -H 'Square-Version: 2022-09-21' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "evidence_text": "The customer purchased the item twice, on Feb 28 and March 1",
    "idempotency_key": "11d4dc7a-b83e-486b-8875-426b7e520f4a",
    "evidence_type": "REBUTTAL_EXPLANATION"
  }'

Prior to submission, your application can display a list of evidence provided for a dispute by calling the ListDisputeEvidence endpoint. If you know the evidence_id, you can call RetrieveDisputeEvidence. Note that these endpoints do not return the evidence itself, only metadata about the uploaded evidence. Sellers should retain copies of any evidence submitted in case they want to reference it later.

If you need to remove a piece of evidence, call DeleteDisputeEvidence with the dispute_id and evidence_id for the evidence you want to remove. Square does not send the bank any evidence that is removed. Note that you cannot remove evidence after submitting it to the bank using SubmitEvidence.

After uploading all relevant evidence for the dispute, call SubmitEvidence to submit the provided evidence to the card-issuing bank. Square changes the dispute state to PROCESSING. At this point, the evidence for this dispute can no longer be removed or changed.

Submit Evidence
  • 1
  • 2
  • 3
  • 4
  • 5
curl https://connect.squareupsandbox.com/v2/disputes/bVTprrwk0gygTLZ96VX1oB/submit-evidence \
  -X POST \
  -H 'Square-Version: 2022-09-21' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json'

The following is an example response:

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. By calling SubmitEvidence, the challenge process starts and you can no longer add or remove any evidence.

When available, Square automatically provides information to the card-issuing bank on a seller’s behalf to supplement the other evidence provided. This information may be business or cardholder details (name, address, phone number), Square receipts, related transactions, or tracking numbers.

When the seller challenges a dispute, there are three possible outcomes:

  • Win. The bank accepts the evidence as sufficient proof of a legitimate payment. Square updates the dispute state to WON and releases the held funds back to the seller’s bank account.

  • Lose. The bank rejects the evidence as insufficient proof. Square updates the dispute state to LOST and the cardholder is refunded.

  • Bank asks for more information. The bank is still deliberating and is requesting additional evidence. Square updates the dispute state to EVIDENCE_REQUIRED. In this case, the seller can upload more evidence or accept the cardholder's dispute.

To receive the most timely information about disputes, subscribe to the dispute.created and dispute.state.updated webhooks. When a bank notifies Square of a new payment dispute, Square creates a dispute and sends the dispute.created webhook event notification, which includes the entire dispute object in its data.

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
  • 26
  • 27
  • 28
  • 29
  • 30
  • 31
  • 32
 {
  "merchant_id": "MLFG72TMMXMCQ",
  "location_id": "L1HN3ZMTZEB87",
  "type": "dispute.created",
  "event_id": "3ad92963-cddd-4f80-9c87-9fd75b4954e5",
  "created_at": "2022-03-02T16:38:37.46Z",
  "data": {
    "type": "dispute",
    "id": "bVTprrwk0gygTLZ96VX1oB",
    "object": {
      "dispute": {
        "amount_money": {
          "amount": 2273,
          "currency": "USD"
        },
        "brand_dispute_id": "P9td9draSX6ACrUO3KEI6Q",
        "card_brand": "VISA",
        "created_at": "2022-03-02T16:38:37.460Z",
        "disputed_payment": {
          "payment_id": "BqzL87eLnz9gJRuoiIYSY44p9ORZY"
        },
        "due_at": "2022-03-16T00:00:00.000Z",
        "id": "OWo09e15R49UrfXjG5Bod",
        "location_id": "L1HN3ZMTZEB87",
        "reason": "DUPLICATE",
        "reported_at": "2022-03-02T00:00:00.000Z",
        "state": "EVIDENCE_REQUIRED",
        "updated_at": "2022-03-02T16:38:37.460Z"
      }
    }
  }
}

The Disputes API supports the following webhooks:

EventDescription
dispute.createdA cardholder has initiated a chargeback and a dispute was created.
dispute.state.updatedThe state of a dispute has been updated. When the bank reaches a dispute resolution, the state changes to either WON or LOST. During the dispute process, the state can also change to PROCESSING or EVIDENCE_REQUIRED. The event data includes details about what was updated. This replaces the deprecated dispute.state.changed webhook.
dispute.evidence.createdEvidence was added to a dispute from the Disputes Dashboard in the Seller Dashboard, in the Square Point of Sale application, or by uploading evidence with the Disputes API. This replaces the deprecated dispute.evidence.added webhook.
dispute.evidence.deletedEvidence was removed from a dispute in the Disputes Dashboard in the Seller Dashboard, in the Square Point of Sale application, or by calling DeleteDisputeEvidence. in the Disputes API. This replaces the deprecated dispute.evidence.removed webhook.

Note: Some webhooks have been deprecated in the V2 Disputes API. For a complete list of all Disputes API webhooks, including deprecated ones, see the V2 Webhook Events Reference. For more information about using webhooks, see Square Webhooks Overview.

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.