Test the Disputes API

Developers use the Disputes API to programmatically complete the steps of the dispute process. To test your application without creating actual payment disputes with a bank, make calls to the Disputes API using the Square Sandbox. This topic walks through the following steps:

  1. Trigger a dispute in the Sandbox.
  2. Get new disputes.
  3. Respond by accepting or challenging the dispute.
  4. Verify the state of the dispute.

Important

Test disputes you create in the Square Sandbox aren't visible in the Developer Dashboard or Seller Dashboard. You can only access and manage them through the Disputes API. Actual payment disputes initiated by customers are visible to sellers in the Seller Dashboard.

Link to section

Outline of the dispute process

The following flowchart outlines the steps of the dispute process and possible outcomes, beginning with the customer's initial chargeback request. For more information about the seller’s role in the dispute process and details about the use of each Disputes API endpoint in a production application, see Process Disputes.

A diagram showing the dispute process from initiation through resolution.

Link to section

Trigger a dispute in the Sandbox

To trigger a test dispute in the Square Sandbox, send a CreatePayment request with one of the following charge amounts. The Sandbox creates a Dispute object whose reason corresponds to the charge amount set.

Charge amountDispute reason
8801AMOUNT_DIFFERS
8802CANCELLED
8803DUPLICATE
8804NO_KNOWLEDGE
8805NOT_AS_DESCRIBED
8806NOT_RECEIVED
8807PAID_BY_OTHER_MEANS
8808CUSTOMER_REQUESTS_CREDIT
8809EMV_LIABILITY_SHIFT

Note

The amounts shown are in the lowest denomination of the currency provided in the request. For example, USD is in cents.

The following Sandbox request creates a payment for the amount of $88.03 USD. This generates a Dispute with the reason of DUPLICATE. When testing payments in the Sandbox, you can use one of the test payment tokens as the source_id in the request.

Create payment

The following is an example response:

Link to section

Get new disputes

Your application receives new Dispute objects by listening for the dispute.created webhook or by calling the ListDisputes endpoint.

Link to section

Listen for the dispute.created notification

If you set up a subscription for disputes webhooks, your listening endpoint receives a dispute.created notification whenever a new dispute is created. The body of the notification contains the new Dispute object.

Link to section

Get a list of disputes

If you don't want to use webhook notifications, you can make periodic calls to ListDisputes. An unfiltered request returns all disputes, so it might be helpful to filter the request to only return disputes awaiting seller action.

Important

A seller typically has 14 days or less to respond to a new dispute. Depending on how often your application calls ListDisputes, information about disputes might be delayed getting to sellers. Consider implementing webhook notifications to receive dispute data as it is created.

The following ListDisputes request is filtered to return only open disputes in the EVIDENCE_REQUIRED state (that is, awaiting seller action):

List disputes

The following sample response shows two disputes: the DUPLICATE dispute created in the previous step and a dispute with the reason of NOT_RECEIVED. Both are awaiting action.

Important

  • If the due_at deadline passes with no action from the seller, Square automatically challenges the dispute on the seller’s behalf.
  • If a seller takes an initial action on a dispute by using the Disputes Dashboard, the dispute state changes to PROCESSING and your application cannot take further action.
Link to section

Respond to the dispute

Sellers respond by either accepting or challenging the dispute.

Link to section

Accepting the dispute

To accept the dispute on behalf of a seller, have your application call AcceptDispute. This isn't reversible. If a dispute is accepted, it cannot be challenged later.

Accept dispute

The following response shows that the state of the test dispute has changed to ACCEPTED:

Link to section

Challenging the dispute

Challenging a dispute using the Disputes API is a two-step process:

  1. Upload evidence - Your application provides one or more pieces of evidence related to the payment. These can be images, PDFs, or text. For more information about the requirements and best practices for uploading evidence, see Uploading evidence.
  2. Submit the evidence - Your application calls the SubmitEvidence endpoint to submit the provided evidence to the bank.
Link to section

Testing a dispute challenge

For testing purposes, disputes managed in the Square Sandbox can be WON or LOST by submitting a piece of evidence with the name evidence_won or evidence_lost. Submitting any of the allowed file types with either of these names causes an automatic WON or LOST state change.

Suppose you're testing a sample dispute in the Sandbox with the reason of NOT_RECEIVED. The following example call to CreateDisputeEvidenceFile uploads an image delivery-confirmation.png as PROOF_OF_DELIVERY_DOCUMENTATION.

Create dispute evidence file

To complete testing and trigger an automatic WON or LOST state for the dispute, make another call to CreateDisputeEvidenceFile and include a file of the application/pdf type named evidence_won.pdf (to test a winning dispute state) or evidence_lost.pdf (to test a losing dispute state).

Create dispute evidence file

Finally, submit the evidence using the SubmitEvidence endpoint. Don't call SubmitEvidence for each piece of uploaded evidence. Call the endpoint after the complete body of evidence has been uploaded to Square. By calling SubmitEvidence, the challenge process starts and you can no longer add or remove evidence.

Submit evidence

The following is an example response:

Link to section

Verify dispute state

After a seller submits evidence to challenge a dispute, the state changes to PROCESSING while the bank deliberates. Your application can listen for the dispute.state.updated webhook notification to receive the most timely notification when a bank responds to the dispute challenge.

When testing the Disputes API in the Square Sandbox, you can cause a dispute state change to WON or LOST by submitting a piece of evidence named evidence_won or evidence_lost, respectively. Because there is no bank involved in Sandbox disputes, if you submit a dispute without any evidence with these names, the state changes to PROCESSING, but doesn't resolve.

In the previous step, delivery-confirmation.png and evidence_won.pdf were submitted as evidence for a dispute. The state changes to WON, and the webhook notification contains the following data:

Another way to receive information about a dispute is to call RetrieveDispute with a dispute ID. Note that it might take a bank several days or more to respond to a dispute challenge. Therefore, if your application regularly queries for information about open disputes, it might take time to receive new information.

Retrieve dispute

The following is an example response: