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


Disputes API

A payment dispute (also referred to as a chargeback) occurs when the cardholder contacts their card issuing bank to reverse a payment. Cardholders request a payment reversal when they believe the charge is not valid for a specific reason. These reasons represent the type of disputes you may 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, we provide 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 their 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 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 our own (when available) and submit it all to the bank.

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

Requirements and Limitations Permalink Get a link to this section

  • Required OAuth permissionsPAYMENTS_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.