Walkthrough: Create, Challenge, and Review a Dispute Resolution
In this walkthrough, you test the Disputes API in the Square Sandbox.
On this page
Test the Disputes API in the Square Sandbox
You can use the Sandbox environment to test the Disputes API. Use the following guidelines to generate sample disputes, challenge disputes, and obtain resolutions:
Generate a dispute. To generate a dispute, you specify one of the following amounts in a CreatePayment request. Each payment amount maps to a specific dispute reason.
The amounts shown are in the lowest denomination of the currency you provide in the
CreatePayment
request. For example, USD is in cents.Charge amount Dispute reason 8801 AMOUNT_DIFFERS 8802 CANCELLED 8803 DUPLICATE 8804 NO_KNOWLEDGE 8805 NOT_AS_DESCRIBED 8806 NOT_RECEIVED 8807 PAID_BY_OTHER_MEANS 8808 CUSTOMER_REQUESTS_CREDIT 8809 EMV_LIABILITY_SHIFT Challenge a dispute. To challenge a dispute, upload one or more pieces of evidence. The last piece of sample evidence you upload should be a file with the name "evidence_won" or "evidence_lost". Square uses the last file name to automatically resolve the dispute accordingly.
Example walkthrough
In this walkthrough, the cURL commands specify the Sandbox domain in the endpoint URL (connect.squareupsandbox.com).
Prepare
To prepare for the walkthrough, complete the following steps:
Create two PDF documents (the content of the PDF documents does not matter in this testing example). Name the two documents samplePDF.pdf and evidence_won.pdf. You upload these test documents as evidence when you challenge the disputes in the Sandbox.
(optional) In the walkthrough, the
ListDisputes
endpoint is used to get a list of disputes. You can also subscribe to the webhook events to get notified when events occur. For more information, see Subscribe to Events.
Step 1: Create a dispute
Create a payment for the amount of 88.05 USD. Square automatically generates a dispute with the reason DUPLICATE.
Send a CreatePayment request.
The following is an example response:
{ "payment":{ "id":"0dG0pUTlY5bYMr2CJbttiLByvaB", "created_at":"2019-12-16T01:21:56.614Z", "updated_at":"2019-12-16T01:21:56.787Z", "amount_money":{ "amount":8803, "currency":"USD" }, "status":"COMPLETED", "source_type":"CARD", "card_details":{ "status":"CAPTURED", "card":{ "card_brand":"AMERICAN_EXPRESS", "last_4":"6550", "exp_month":12, "exp_year":2021, "fingerprint":"sq-1-Qo2zq6ihytSFS7jL8DaOro1sBUOfsv8o5rzl1uxie4KPd-gZcTxOJRj3moHXZ-f2CA", "bin":"371263" }, "entry_method":"KEYED", "cvv_status":"CVV_ACCEPTED", "avs_status":"AVS_ACCEPTED", "statement_description":"SQ *DEFAULT TEST ACCOUNT" }, "location_id":"S8GWD5R9QB376", "order_id":"6Sm73w9MK2YNqsnFOliz3S9VrRFZY", "total_money":{ "amount":8803, "currency":"USD" }, "receipt_number":"0dG0", "receipt_url":"https://squareup.com/receipt/preview/0dG0pUTlY5bYMr2CJbttiLByvaB" } }
Listen for the dispute.created webhook notification. If you are not subscribing for dispute events, you can call a ListDisputes request. The response contains all of the disputes Square has recorded for the seller. If you use
ListDisputes
, you should filter on the dispute states that are set for newly created disputes.
The following is an example response:
{
"disputes":[
{
"amount_money":{
"amount":8803,
"currency":"USD"
},
"brand_dispute_id":"6rjByNRfR5OpFZeJs_PNKw",
"card_brand":"VISA",
"created_at":"2019-12-16T01:21:59.983Z",
"dispute_id":"xe8rb2X4ifCcWd1xIjuaKB",
"disputed_payment":{
"payment_id":"0dG0pUTlY5bYMr2CJbttiLByvaB"
},
"due_at":"2019-12-30T00:00:00.000Z",
"location_id":"S8GWD5R9QB376",
"reason":"DUPLICATE",
"reported_date":"2019-12-16T00:00:00.000Z",
"state":"EVIDENCE_REQUIRED",
"updated_at":"2019-12-16T01:21:59.983Z"
}
]
}
The dispute reason is DUPLICATE and the state is EVIDENCE_REQUIRED. In the next step, upload evidence to challenge the dispute.
Step 2: Upload evidence
In this example, you upload the following three pieces of evidence:
Two pieces of general evidence. This includes:
An email from the customer that shows the customer ordered the item twice. You upload this evidence as samplePDF.pdf and choose
cardholder_communication
as theevidence_type
. For more information, see Challenge a dispute.An explanation that the customer ordered the item twice and therefore the cardholder’s dispute is invalid. You upload this evidence as a string (“the customer ordered the item twice; on date 1-and date-2”) and choose
rebuttal_explanation
as theevidence_type
.
One piece of dispute-specific evidence. The dispute reason in this example is DUPLICATE because the cardholder claims they were charged twice for the same purchase. Assume you have two separate receipts as evidence. You upload the receipts as a PDF file (evidence_won.pdf) and specify
duplicate_charge_documentation
as the suitableevidence_type
.
Step 2.1: Upload evidence file
Call CreateDisputeEvidenceFile to upload the samplePDF.pdf file with cardholder_communication
as the evidence_type
.
The following is an example response:
{
"evidence":{
"evidence_id":"Ri6eRTG3xjT0nnUfN0SoQ",
"dispute_id":"xe8rb2X4ifCcWd1xIjuaKB",
"evidence_file":{
"filename":"samplePDF.pdf",
"filetype":"application/pdf"
},
"uploaded_at":"2019-12-23T02:24:58.000Z"
}
}
Step 2.2: Upload evidence text
Call CreateDisputeEvidenceText to upload the string "the customer ordered the item twice; on date-1 and date-2" with REBUTTAL_EXPLANATION as the evidence_type
.
The following is an example response:
{
"evidence":{
"evidence_id":"ny5BJ2JvzHZlNIReqkJAzC",
"dispute_id":"QQa9GkoZNFhBKPYWYgRq4B",
"evidence_text": "the customer ordered the item twice; on date-1 and date-2",
"uploaded_at":"2020-01-07T17:52:35.000Z"
}
}
Step 2.3: Upload evidence 3 (dispute reason specific evidence, PDF file)
Call CreateDisputeEvidenceFile to upload the evidence_won.pdf file with duplicate_charge_documentation
as the evidence_type
.
The following is an example response:
{
"evidence":{
"evidence_id":"WKoZd9VlUEZSfI6Q4lu0cD",
"dispute_id":"xe8rb2X4ifCcWd1xIjuaKB",
"evidence_file":{
"filename":"evidence_won.pdf",
"filetype":"application/pdf"
},
"uploaded_at":"2019-12-23T02:40:01.000Z"
}
}
Step 3: Submit evidence
Call the SubmitEvidence endpoint to submit all the evidence to Square.
The following is an example response:
{
"dispute":{
"dispute_id":"xe8rb2X4ifCcWd1xIjuaKB",
"amount_money":{
"amount":8803,
"currency":"USD"
},
"reason":"DUPLICATE",
"state":"PROCESSING",
"due_at":"2019-12-30T00:00:00.000Z",
"disputed_payment":{
"payment_id":"0dG0pUTlY5bYMr2CJbttiLByvaB"
},
"evidence_ids":[
"Ri6eRTG3xjT0nnUfN0SoQ",
"WKoZd9VlUEZSfI6Q4lu0cD"
],
"card_brand":"VISA",
"created_at":"2019-12-16T01:21:59.983Z",
"updated_at":"2019-12-23T02:41:34.969Z",
"brand_dispute_id":"6rjByNRfR5OpFZeJs_PNKw",
"reported_date":"2019-12-16T00:00:00.000Z",
"version":4,
"location_id":"S8GWD5R9QB376"
}
}
After submitting all evidence, the bank determines who won the dispute and notifies Square. Square then sets the state of the dispute to either WON
or LOST
.
Did you know?
In the Square Sandbox, a dispute is WON
by setting the name of the last piece of uploaded evidence file to evidence_won.pdf
. There is no actual bank in the Sandbox to determine the final state of a dispute.
Step 4: Verify dispute state
Listen for the dispute.state.changed webhook notification which is sent when the state of the dispute changes. In production, your application should not poll the RetrieveDispute endpoint because the bank might require days to make a judgment on the dispute.
If you want your application to do limited polling of the Disputes API for a new dispute state, call RetrieveDispute and verify the dispute state.
The following is an example response:
{
"type":"dispute",
"id":"xe8rb2X4ifCcWd1xIjuaKB",
"object":{
"amount_money":{
"amount":8803,
"currency":"USD"
},
"brand_dispute_id":"6rjByNRfR5OpFZeJs_PNKw",
"card_brand":"VISA",
"created_at":"2019-12-16T01:21:59.983Z",
"dispute_id":"xe8rb2X4ifCcWd1xIjuaKB",
"disputed_payment":{
"payment_id":"0dG0pUTlY5bYMr2CJbttiLByvaB"
},
"due_at":"2019-12-30T00:00:00.000Z",
"evidence_ids":[
"Ri6eRTG3xjT0nnUfN0SoQ",
"WKoZd9VlUEZSfI6Q4lu0cD"
],
"location_id":"S8GWD5R9QB376",
"reason":"DUPLICATE",
"reported_date":"2019-12-16T00:00:00.000Z",
"state":"WON",
"updated_at":"2019-12-23T02:41:38.024Z",
"version":5
}
}
The response shows the dispute state as WON. If you configured webhooks, you get a notification with the same information.