Process Disputes
You can use the Disputes API to access dispute data, accept a dispute, or submit evidence to challenge a dispute.
On this page
Access dispute information
After a cardholder initiates a dispute, the cardholder’s bank notifies Square of the claim. Square stores dispute information by creating a Dispute object. The following is an example Dispute instance:
{
"dispute_id":"QQa9GkoZNFhBKPYWYgRq4B",
"amount_money":{
"amount":8815,
"currency":"USD"
},
"reason":"AMOUNT_DIFFERS",
"state":"EVIDENCE_REQUIRED",
"due_at":"2019-12-30T00:00:00.000Z",
"disputed_payment":{
"payment_id":"ScM5CtZGuU9r2fZdRpOXlZe4uaB"
},
"card_brand":"VISA",
"created_at":"2019-12-16T01:26:07.184Z",
"updated_at":"2019-12-16T01:26:07.184Z",
"brand_dispute_id":"CD8CQF_PS26LwjySZbUoAw",
"reported_date":"2019-12-16T00:00:00.000Z",
"location_id":"S8GWD5R9QB376"
}
The Dispute object also provides the dispute reason, the current state of the dispute, and the due_at deadline by which you need to respond to the dispute (accept or challenge).
Important
If you do not respond by the due_at deadline, the dispute state changes from evidence_required to processing and you cannot take further action on the dispute.
You have the following options to get Dispute data:
Subscribe to the
dispute.createdwebhook.Use the ListDisputes endpoint.
Subscribe to the dispute.created webhook
When a bank notification is received, Square creates a dispute and sends this event notification. The event notification includes dispute information as shown:
{
"merchant_id": "GEF74Kexample",
"location_id": "S8GWD5example",
"type": "dispute.created",
"event_id": "7c912a86-fffb-45e7-bfcb-8c7a7b16751b",
"created_at": "2019-12-23T02:41:38.024Z",
"data": {
"type": "dispute",
"id": "xe8rb2X4ifCcWd1example",
"object": {
… <information the Dispute object provides>
}
}
}
For a list of dispute related webhooks and subscription information, see Subscribe to Events.
Use the ListDisputes endpoint
In the following example ListDisputes request, the access token in the Authorization header identifies the specific Square seller account for which to return the dispute list.
curl -X GET \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
-H 'Content-Type: application/json' \ 'https://connect.squareupsandbox.com/v2/disputes
The following is a sample response. It shows a dispute having EVIDENCE_REQUIRED as the state.
{
"disputes":[
{
"dispute_id":"ty2li14gPpMjEjpzDrH1fD",
"amount_money":{
"amount":8801,
"currency":"USD"
},
"reason":"AMOUNT_DIFFERS",
"state":"PROCESSING",
"due_at":"2019-12-30T00:00:00.000Z",
"disputed_payment":{
"payment_id":"aqzsteNctof09YaYw221GxvtvaB"
},
"evidence_ids":[
"avDDMzWFA9TESvDCTHkrg"
],
"card_brand":"VISA",
"created_at":"2019-12-16T18:07:57.373Z",
"updated_at":"2019-12-17T01:38:51.767Z",
"brand_dispute_id":"JVhxqiFNQ3eAJCJ_yBmAgg",
"reported_date":"2019-12-16T00:00:00.000Z",
"version":3,
"location_id":"S8GWD5R9QB376"
}
…
]
}
Dispute reason
When a dispute state indicates that evidence is required, you can accept or challenge the dispute. If the seller wants to challenge the dispute, the seller should submit evidence that directly addresses the dispute reason type. For a list of dispute reasons and related explanations, see the reason field of the Dispute type.
Challenge a dispute
When you challenge a dispute, your likelihood of winning depends on the evidence you provide. Ultimately, the card-issuing bank determines who wins. However, the better evidence you provide, the better chance you have of winning the dispute. Challenging a dispute using the Disputes API is a two-step process:
Upload evidence. You provide one or more pieces of evidence to Square. Note that Square automatically includes information on your behalf, when available, to supplement the evidence you provide.
Submit the evidence. You direct Square to submit the evidence to the bank.
Step 1: Upload evidence
When uploading evidence, you provide both the evidence and the evidence type. You can:
Provide general evidence and dispute-specific evidence (addressing the cardholder’s specific claim). General evidence refers to information that the card networks find important regardless of the dispute reason.
Upload evidence as a file ( CreateDisputeEvidenceFile) or a string ( CreateDisputeEvidenceText). For example, you might upload a PDF file of an email thread with the customer as evidence or you might upload a shipment tracking number directly in the request body.
Square supports these file types: image/tiff, application/pdf, image/jpeg, image/png, and image/heif. The file you upload can be up to 5 MB in size.
Each piece of evidence must be uploaded individually using the
CreateDisputeEvidencerequest.
Evidence type
When you upload a piece of evidence, you can specify what type of evidence it is. Square provides a set of predefined evidence types. For a list of evidence types and related explanations, see the evidence_type field described in one of these endpoints: CreateDisputeEvidenceFile or CreateDisputeEvidenceText.
Choosing the correct evidence type is important because it helps you make the best case to the bank and increases your chances of winning a dispute. The following are related guidelines:
You can upload one or more of these general evidence types for all disputes, regardless of the reason.
Dispute reason Suggested evidence type Upload these evidence types for any dispute reason cardholder_communication cardholder_information purchase_acknowledgement product_or_service_description receipt service_received_documentation proof_of_delivery_documentation rebuttal_explanation In addition to general evidence, the following table lists the suggested evidence types to submit for each dispute reason. These suggestions are based on card network rules to help you make your best case when challenging a dispute.
Dispute reason Suggested evidence type NO_KNOWLEDGE authorization_documentation, online_or_app_access_log, and related_transaction_documentation NOT_RECEIVED online_or_app_access_log, service_received_documentation, proof_of_delivery_documentation, and tracking_number NOT_AS_DESCRIBED cancellation_or_refund_documentation, service_received_documentation, proof_of_delivery_documentation, and tracking_number CUSTOMER_REQUESTS_CREDIT or PAID_BY_OTHER_MEANS cancellation_or_refund_documentation, service_received_documentation, proof_of_delivery_documentation, and tracking_number DUPLICATE duplicate_charge_documentation and related_transaction_documentation CANCELLED cancellation_or_refund_documentation, service_received_documentation, proof_of_delivery_documentation, and tracking_number AMOUNT_DIFFERS authorization_documentation
Example: Upload evidence
The following CreateDisputeEvidenceFile request is an example of a tiff file submitted (for example, a scanned receipt) as evidence. The request includes the following:
DISPUTE_IDin the endpoint URL identifies the dispute for the evidence file being uploaded.Authorizationheader specifies the access token of the seller responsible for the dispute.evidenceprovides the path of the file to upload and the type of the evidence file.The request body provides the
evidence_typeandidempotency_key. For more information, see Idempotency.
curl -X POST \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
-H 'Content-Type: multipart/form-data' \
-F 'evidence=@/path/to/file/filename.tiff' \
-F 'request={ "idempotency_key":"{{UNIQUE_KEY}}", "evidence_type":"{{EVIDENCE_TYPE}}", "content_type":"image/tiff" }' \
'https://connect.squareupsandbox.com/v2/disputes/{{DISPUTE_ID}}/evidence_file'
The following is a sample response:
{
"evidence":{
"evidence_id":"avDDMzWFA9TESvDCTHkrg",
"dispute_id":"ty2li14gPpMjEjpzDrH1fD",
"evidence_file":{
"filename":"samplePDF.pdf",
"filetype":"application/pdf",
"evidence_type":"GENERIC_EVIDENCE"
},
"uploaded_at":"2019-12-17T01:36:48.000Z"
}
}
To upload evidence as a string, use the CreateDisputeEvidenceText request as shown:
curl -X POST \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
-H 'Content-Type: application/json' \
-d '{ "idempotency_key":"{{UNIQUE_KEY}}", "evidence_type":"{{EVIDENCE_TYPE}}", "evidence_text":"{{STRING_TO_UPLOAD}}" }' \
'https://connect.squareupsandbox.com/v2/disputes/{{DISPUTE_ID}}/evidence_text'
Important
You must maintain a copy of the uploaded evidence if you want to reference it later. There is no way for you to download the evidence after you upload it.
Helper endpoints to manage evidence
You can use the ListDisputeEvidence and RemoveDisputeEvidence endpoints to manage your dispute evidence. It is important to note that after you call SubmitEvidence, you cannot remove any of the submitted evidence.
Square-provided evidence
When available, Square automatically includes the following information on your behalf to supplement the evidence you provide:
| Evidence | Description |
| Business information | The name of the business, address, and phone number for the entity that is receiving the dispute. This is automatically populated if available. |
| Cardholder information | The cardholder name, email address, and phone number for the cardholder filing the dispute. This is automatically populated if available. |
| Shipping address | This is automatically populated if available. |
| Receipt | Any receipt or proof of purchase (for example, a Square receipt) sent to the cardholder at the time of purchase confirming the details of the charge. This is automatically populated if available. |
| Related transactions | Square receipts for up to five related transactions made by the cardholder prior to the dispute and that remain undisputed. |
Step 2: Submit evidence
After you upload all your pieces of evidence, direct Square to submit the evidence to the bank by sending a SubmitEvidence request as shown:
curl -X POST \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
-H 'Content-Type: application/json' \
'https://connect.squareupsandbox.com/v2/disputes/{{DISPUTE_ID}}/submit-evidence'
In the request:
DISPUTE_IDin the endpoint URL identifies the dispute for which the evidence is being submitted.access_tokenin theAuthorizationheader identifies the seller responsible for the dispute.
The following is a sample response:
{
"dispute":{
"dispute_id":"WoaG8ihupXrqNYU6Xyu9f",
"amount_money":{
"amount":100,
"currency":"USD"
},
"reason":"RETURNED",
"state":"PROCESSING",
"due_at":"2019-06-03T00:00:00.000Z",
"disputed_payments":[
{
"payment_id":"ayTy9EDmrlEI3QWf9iLQXrPfuaB"
}
],
"evidence_ids":[
"frWAgRJ94luIfWt0pDsXXD"
],
"card_brand":"american_express",
"created_at":"2019-05-21T17:45:16.199Z",
"updated_at":"2019-05-22T00:24:10.358Z",
"brand_dispute_id":"100000415900",
"reported_date":"2019-05-20T00:00:00.000Z",
"version":3
}
}
The response shows that Square changed the dispute state from EVIDENCE_REQUIRED to PROCESSING. Square also updates the dispute state based on the response from the cardholder's bank. The state can change to WON, LOST, or EVIDENCE_REQUIRED if the bank requests more information.
There is no endpoint to explicitly challenge a dispute. Instead, when you call SubmitEvidence, Square compiles all the evidence and submits it to the bank. In other words, calling SubmitEvidence triggers the dispute challenge process. You should only call SubmitEvidence after you have finished uploading all pieces of evidence individually by using the CreateDisputeEvidence endpoint. You should not call SubmitEvidence for each piece of uploaded evidence. Remember, after you call SubmitEvidence, you are no longer able to remove any evidence.
Accept a dispute
If you choose to accept a dispute, send a POST request to the AcceptDispute endpoint. This is not reversible. When you accept a dispute, you cannot go back and challenge it later.
The following is an example request:
curl -X POST \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
-H 'Content-Type: application/json' \
'https://connect.squareupsandbox.com/v2/disputes/{{DISPUTE_ID}}/accept'
In the example:
dispute_idin the endpoint URL identifies the dispute being accepted.access_tokenin theAuthorizationheader identifies the seller who is responsible for managing the dispute.
When you accept the dispute, Square debits the disputed amount from the balance of your Square account. If your Square account balance does not have sufficient funds, Square debits the funds from your associated bank account. The following is a sample response:
{
"dispute":{
"dispute_id":"OZWi9TqDBSgqSrLexample",
"amount_money":{
"amount":100,
"currency":"USD"
},
"reason":"FRAUD",
"state":"ACCEPTED",
"due_at":"2019-06-03T00:00:00.000Z",
"disputed_payments":[
{
"payment_id":"OK8JwPxVnkUVThdvgPAY6xLwuaB"
}
],
"card_brand":"american_express",
"created_at":"2019-05-21T17:45:16.284Z",
"updated_at":"2019-05-21T23:07:13.782Z",
"brand_dispute_id":"100000294534",
"reported_date":"2019-05-20T00:00:00.000Z",
"version":2
}
}
The state value ACCEPTED indicates that you have accepted the dispute.