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

Disputes Overview

A payment dispute (also called a chargeback) occurs when the cardholder contacts the card-issuing bank to reverse a payment. Cardholders can request a payment reversal when they believe the charge is not valid for a specific reason. These reasons represent the type of disputes you might receive.

The dispute resolution process allows you to make your case to the cardholder's bank that the payment was valid by providing evidence. To help you make the best case possible, Square provides guidance on which evidence types you should submit for each dispute reason.

How the dispute process works Permalink Get a link to this section

When a cardholder files a payment dispute with the issuing bank, the bank notifies Square of the dispute. Square then notifies you of the dispute and sets the dispute status to evidence required (evidence_required).

Square does not decide who wins or loses the dispute; that is up to the cardholder's bank. However, Square communicates with the bank on your behalf, provides you with updates, and helps you navigate the process. The steps in the dispute process are:

  1. Square notifies you of a dispute.

  2. You respond within the specified deadline.

  3. You wait for the bank to determine the dispute resolution.

When a dispute occurs, Square withholds the disputed funds from your Square account balance until the bank issues a final resolution on the case. If there are insufficient funds in your Square balance, the funds are debited from your most recently linked bank account.

How the resolution process works Permalink Get a link to this section

You have two options to address a dispute:

  • Accept the dispute. Square returns the disputed amount to the cardholder and updates the dispute state to ACCEPTED.

  • Challenge the dispute. If you believe that the claim is invalid, you can challenge the dispute. To challenge the dispute, you must first understand the dispute reason and submit any available supporting evidence about the transaction. The evidence can be general or specific to the payment in dispute. The more evidence you can provide to address the cardholder's dispute reason, the better chance you have of winning the dispute. After you submit evidence to the bank, Square changes the dispute state to PROCESSING.

    When you challenge a dispute, there are three possible outcomes:

    • Win. If the bank accepts the evidence, Square updates the dispute state to WON and releases the held funds back to your bank account.

    • Loss. If the bank rejects the evidence, Square updates the dispute state to LOST and the funds remain refunded to the cardholder.

    • Bank asks for more information. If the bank wants more information, Square updates the dispute state to EVIDENCE_REQUIRED. In this case, you can upload more evidence or choose to accept the dispute.

If you choose to challenge the dispute, your chances of winning depend on the evidence you submit. The specific evidence requirements and rules are established by the card networks for each dispute reason. Square simplifies the process by organizing these card network rules into a set of predefined evidence types (evidence_type). You can provide multiple pieces of evidence for each dispute. When you upload evidence to Square, you indicate the evidence type. After you upload evidence, Square packages your evidence, adds helpful information of its own (when available), and submits it all to the bank.

If you choose not to use the Disputes API, you can access disputes information manually through the Square Dispute Dashboard. For information about the manual dispute process, see Payment Disputes Walkthrough. This article explains processing disputes using the Disputes API.

Requirements and limitations Permalink Get a link to this section

  • Required OAuth permissions: PAYMENTS_WRITE and PAYMENTS_READ. Every dispute is related to a payment, so these permissions are required.

  • Square does not decide who wins or loses the dispute; that is up to the card-issuing bank of the cardholder.

Related topics Permalink Get a link to this section