Disputes API

Disputes Overview

A payment dispute (also known as a chargeback) occurs when a card holder contacts the card-issuing bank to request a charge reversal. Card holders request a reversal when they believe a charge is not valid for a specific reason. These reason types correspond to the dispute types a seller needs to address.

The dispute resolution process allows a seller to provide evidence that a payment was valid. To help a seller make the best case possible to the bank, Square provides guidance on which evidence types the seller should submit for each dispute reason.

The Disputes API allows a seller to use your application to complete the steps of the disputes process. The seller might also access disputes information manually through the Square Dispute Dashboard.

Did you know?

A payment and a charge are the same thing. From the seller's point of view, a payment is made with a card. From the card holder's point of view, a card is charged to make a payment. When using the term charge, Square is discussing a dispute from the card holder's point of view.

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

When a card holder requests a charge reversal with the issuing bank, the bank notifies Square of the request. Square then adds a dispute to the seller Dispute Dashboard and notifies your application using a webhook.

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

  1. Square notifies the seller of a dispute.

  2. The seller responds within the specified deadline.

  3. The seller waits for the bank to determine the dispute resolution.

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

Did you know?

Square provides webhook notifications for each step of the dispute process. Your application can provide the correct and timely response to dispute process events when it is configured to listen for Square Webhooks.

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

The seller has two options to address a dispute:

  • Accept the buyer chargeback request. Call the AcceptDispute endpoint and Square returns the disputed amount to the card holder and updates the dispute state to ACCEPTED. The dispute is closed at this point.

  • Challenge (dispute) the chargeback request. Before a seller can challenge a request, they need to see the chargeback 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 calls the CreateDisputeEvidenceFile or CreateDisputeEvidenceText endpoint to provide evidence to start challenging the request. The evidence can be general or specific to the payment in dispute. The more evidence the seller provides to address the card holder's dispute reason, the better chance they have of winning the dispute. Your application can display a list of evidence provided in a dispute by calling the ListDisputeEvidence endpoint to show the evidence that has been uploaded to support a dispute prior to submission.

    When the seller is ready, your application calls the SubmitEvidence endpoint to submit the provided evidence to the bank and Square changes the dispute state to PROCESSING.

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

    • Win. The bank has accepted the evidence as sufficient proof. Square updates the dispute state to WON and releases the held funds back to the seller bank account.

    • Lose. The bank rejects the evidence as insufficient proof. Square updates the dispute state to LOST and the funds remain refunded to the card holder.

    • 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 just accept the card holder's dispute.

If the seller challenges a chargeback request, their chances of winning depend on the submitted evidence. 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 ( DisputeEvidenceType). The seller can provide multiple pieces of evidence for each dispute. When the seller uploads evidence to Square, they set the evidence type. After the evidence is uploaded, Square packages the evidence, might add helpful information of its own, and awaits the seller's request to submit the package to the bank.

Requirements and limitations Permalink Get a link to this section

  • Required OAuth permissions: DISPUTES_WRITE and DISPUTES_READ.

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

Related topics Permalink Get a link to this section