An introduction to processing disputes using the Square Disputes API.
Disputes API

Disputes Overview

A payment dispute, or chargeback, occurs when a cardholder contacts their card-issuing bank to request a payment reversal when they believe a payment is not valid. For instance, if they were charged twice for the same item, the item was not delivered correctly, or the charge itself is fraudulent.

When a cardholder requests a charge reversal with their bank, the bank notifies Square of the request. Square then notifies the seller and adds the dispute to the seller's Disputes Dashboard. At this time, Square withholds the disputed funds from the seller's 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 removed (debited) from the seller's most recently linked bank account.

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

  1. Square notifies the seller of a dispute.

  2. The seller responds within the specified deadline, either accepting or challenging the chargeback request.

  3. If challenging the request, the seller provides evidence that the purchase was valid.

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

A diagram showing the dispute process from initiation through resolution

Did you know?

Some chargebacks are generated because of fraudulent activity. To reduce the possibility of fraudulent charges, sellers can use the Square Risk Manager to set up rules for online transactions, which can alert them or decline the payment if the transaction appears risky or is likely to result in a chargeback. Additionally, you can use Risk Manager with 3D Secure to require a card issuer to verify the buyer when a payment card is used. If the buyer is verified by the issuer, any chargebacks are the responsibility of the issuer and a dispute is not created.

Square sellers can access and respond to disputes using the Disputes Dashboard or through your application using the Disputes API.

The Disputes API allows a seller to use your application to complete the steps of the disputes process. To provide the most timely information about disputes, Square provides webhook notifications for each step of the dispute process. Your application should provide the seller with important information from the Dispute object, 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), so that the seller can make the most appropriate decision regarding the dispute.

  • Required OAuth permissions: DISPUTES_WRITE and DISPUTES_READ.

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

  • After your application uploads dispute evidence to Square using the Disputes API, the seller can no longer challenge or accept the dispute using the Disputes Dashboard.

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