Dispute API Objects
Use the Disputes API to access a dispute, accept a dispute, or challenge a dispute by uploading and submitting evidence.
Disputes
A buyer's charge-back request is maintained, and adjudicated by a card issuing bank. A Dispute object is the interface that your application uses to take actions related to the charge-back requests. It is created by Square when a bank sends notification that a card holder is requesting a charge-back. Your application gets new Dispute
objects by listening for disputes webhook events, polling the Disputes API periodically by calling ListDisputes, or calling RetrieveDispute if the dispute ID is known.
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).
Dispute evidence
When a seller challenges a dispute, their likelihood of winning depends on the evidence they provide. Ultimately, the card-issuing bank determines who wins. However, the better evidence they provide, the better chance they have of winning the dispute. Challenging a dispute using the Disputes API is a two-step process:
Upload evidence. Your application provides one or more pieces of text (DisputeEvidence) or file (DisputeEvidenceFile) evidence to Square. Note that Square automatically includes information on the seller's behalf, when available, to supplement the evidence they provide.
Submit the evidence. Your application direct Square to submit the evidence to the bank.
Important
Once your app has uploaded dispute evidence in text or file form to Square by using the Disputes API, the seller can no longer challenge or accept a dispute using the Disputes Dashboard.
Evidence type
Square provides an enumerated set of predefined evidence types. Choosing the correct evidence type is important because it helps the seller make the best case to the bank and increases their chances of winning a dispute. The following are related guidelines:
Your application can upload one or more pieces of evidence categorized by DisputeEvidenceType for all disputes, regardless of the reason. 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 the seller make their best case when challenging a dispute.
Dispute reason | Suggested evidence type |
---|---|
AMOUNT_DIFFERS | AUTHORIZATION_DOCUMENTATION |
CANCELLED | CANCELLATION_OR_REFUND_DOCUMENTATION SERVICE_RECEIVED_DOCUMENTATION PROOF_OF_DELIVERY_DOCUMENTATION TRACKING_NUMBER |
CUSTOMER_REQUESTS_CREDIT PAID_BY_OTHER_MEANS | CANCELLATION_OR_REFUND_DOCUMENTATION SERVICE_RECEIVED_DOCUMENTATION PROOF_OF_DELIVERY_DOCUMENTATION TRACKING_NUMBER |
DUPLICATE | DUPLICATE_CHARGE_DOCUMENTATION RELATED_TRANSACTION_DOCUMENTATION |
NO_KNOWLEDGE | AUTHORIZATION_DOCUMENTATION ONLINE_OR_APP_ACCESS_LOG RELATED_TRANSACTION_DOCUMENTATION |
NOT_RECEIVED | AUTHORIZATION_DOCUMENTATION ONLINE_OR_APP_ACCESS_LOG RELATED_TRANSACTION_DOCUMENTATION |
NOT_AS_DESCRIBED | CANCELLATION_OR_REFUND_DOCUMENTATION SERVICE_RECEIVED_DOCUMENTATION PROOF_OF_DELIVERY_DOCUMENTATION TRACKING_NUMBER |
Upload evidence examples
The following CreateDisputeEvidenceFile request is an example of a receipt scanned as a tiff file and submitted as evidence. The request includes the following:
DISPUTE_ID
in the endpoint URL identifies the dispute that the evidence file being uploaded for.Authorization
header specifies the access token of the seller responsible for the dispute.evidence
provides the path of the file to upload and the type of the evidence file.The request body provides the
evidence_type
andidempotency_key
. For more information, see Idempotency.
The following is a sample response:
To upload evidence as a string, use the CreateDisputeEvidenceText request as shown:
Important
The seller must maintain a copy of the uploaded evidence if they want to reference it later. The evidence itself cannot be downloaded after it has been uploaded. The ListDisputeEvidence endpoint returns the metadata about uploaded evidence rather than the evidence itself.
Dispute evidence endpoints
You can use theListDisputeEvidence and DeleteDisputeEvidence endpoints to manage seller dispute evidence. It is important to note that after you call SubmitEvidence, the dispute state is PROCESSING
and your application cannot add more evidence or delete any of the uploaded evidence.
Square-provided evidence
When available, Square automatically includes the following information on a seller's behalf to supplement the evidence they 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. |
After you upload all of the seller evidence, order Square to submit the evidence to the bank by sending a SubmitEvidence request as shown:
In the request:
DISPUTE_ID
in the endpoint URL identifies the dispute for which the evidence is being submitted.access_token
in theAuthorization
header identifies the seller responsible for the dispute.
The following is a sample response:
When you call SubmitEvidence, Square compiles all the evidence and submits it to the bank, starting the dispute challenge process.
Important
Do not call SubmitEvidence
for each piece of uploaded evidence. Call the endpoint after the complete body of evidence has been uploaded to Square. When you call SubmitEvidence
, the challenge process is started and you can no longer add or remove any evidence.
Disputes webhook notifications
If you want your application to receive a notification when Square has responded to a bank by creating a dispute
, subscribe to the dispute.created
webhook. Square also updates the state of a dispute on further action by the bank or your application. For more information about using webhooks, see Webhooks Overview.
Subscribe to the dispute.state.updated
to get notification when a bank responds to a dispute challenge or when your application has taken an action on a dispute.
When a bank notification is received, Square creates a dispute and sends this event notification. The event notification provides metadata describing the webhook event and also includes the new dispute
object:
Webhook events
The Disputes API supports the following webhooks:
Event | Description |
---|---|
dispute.created | A dispute was created. |
DEPRECATED: dispute.state.changed | The state of a dispute changed. This includes the dispute resolution (WON or LOST) reported by the bank. The event data includes details about what changed. |
dispute.state.updated | The state of a dispute changed. This includes the dispute resolution (WON or LOST) reported by the bank. The event data includes details about what changed. |
DEPRECATED: dispute.evidence.added | Evidence was added to a dispute from the Disputes Dashboard in the Seller Dashboard, in the Square Point of Sale application, or by calling the Disputes API (CreateDisputeEvidenceFile or CreateDisputeEvidenceText). |
dispute.evidence.created | Evidence was added to a dispute from the Disputes Dashboard in the Seller Dashboard, in the Square Point of Sale application, or by calling the Disputes API (CreateDisputeEvidenceFile or CreateDisputeEvidenceText). |
dispute.evidence.deleted | Evidence was removed from a dispute from the Disputes Dashboard in the Seller Dashboard, in the Square Point of Sale application, or by calling DeleteDisputeEvidence. |
DEPRECATED: dispute.evidence.removed | Evidence was removed from a dispute from the Disputes Dashboard in the Seller Dashboard, in the Square Point of Sale application, or by calling DeleteDisputeEvidence. |
As a dispute takes the next step through the resolution process, Square sends one of the following events:
dispute.created
. A card holder has requested a charge back and the issuing bank notifies Square of the dispute.dispute.state.updated
. The state of the Dispute has been updated.dispute.evidence.added
. Your application has uploaded a piece of evidence to the dispute.dispute.evidence.deleted
. Your application has removed evidence from a dispute.
Event order
On notification of a new dispute, Square sends the
dispute.created
notification with an initial state ofEVIDENCE_REQUIRED
orINQUIRY_EVIDENCE_REQUIRED
.The seller provides evidence to your application which then uploads it to Square. A
dispute.evidence.added
notification is sent to confirm that the evidence was successfully uploaded.Your application awaits the seller's decision to proceed with the challenge. When the seller decides to proceed, your application calls the SubmitEvidence endpoint. The state of the dispute changes to
PROCESSING
and your application receives thedispute.state.updated
notification.Finally, the bank acts on the evidence submitted and notifies Square. The state of the dispute changes to
WON
,LOST
, orEVIDENCE_REQUIRED
if the bank requests more information. Your application receives thedispute.state.updated
notification.
If you need more assistance, contact Developer Support or ask for help in the Developer Forums.