Disputes API

Applies to: Disputes API

Learn how to use the Disputes API to processing payment disputes.

Link to section


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.

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

Link to section

Requirements and limitations

  • Required OAuth permissions: DISPUTES_WRITE and DISPUTES_READ.
  • Square doesn't 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.
Link to section

How the dispute process works

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 doesn't 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 Strong Customer Authentication 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 isn't created.

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

Link to section

See also