Disputes API

Walkthrough: Create, Challenge, and Review a Dispute Resolution

In this walkthrough, you test the Disputes API in the Square Sandbox.

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.

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

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.

curl -X POST \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
-H 'Content-Type: application/json' \
-d '{
    "idempotency_key": "payment1_dispute_reason_duplicate",
    "autocomplete": true,
    "amount_money": {
      "amount": 8803,
      "currency": "USD"
    },
    "source_id": "cnon:card-nonce-ok"
    }
}' \
'https://connect.squareupsandbox.com/v2/payments'

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"
   }
}

Call a ListDisputes request to verify that the payment now has a dispute.

 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 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, you 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 the evidence_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 the evidence_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 suitable evidence_type.

Step 2.1: Upload evidence 1 (general evidence, PDF file)

Call CreateDisputeEvidenceFile to upload the samplePDF.pdf file with cardholder_communication as the evidence_type.

curl -X POST \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
-H 'Content-Type: multipart/form-data' \
-F 'evidence=@{{FILE_PATH}}/samplePDF.pdf' \
-F 'request={ "idempotency_key":"general_1", "evidence_type":"cardholder_communication", "content_type":"application/pdf" }' \
'https://connect.squareupsandbox.com/v2/disputes/{{DISPUTE_ID}}/evidence_file'

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 2 (general evidence, string “customer ordered item twice; on date-1 and date-2”)

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.

curl -X POST \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
-H 'Content-Type: application/json' \
-d '{ "idempotency_key":"general_2_string", "evidence_type":"REBUTTAL_EXPLANATION", "evidence_text":"the customer ordered the item twice; on date-1 and date-2"  }' \
'https://connect.squareupsandbox.com/v2/disputes/{{DISPUTE_ID}}/evidence_text'

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.

In the Sandbox, the "evidence_won" or "evidence_lost" strings in the file name automatically set the dispute resolution accordingly. If the strings are not present, no automatic resolution occurs.

curl -X POST \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
-H 'Content-Type: multipart/form-data' \
-F 'evidence=@{{FILE_PATH}}/evidence_won.pdf' \
-F 'request={ "idempotency_key":"dispute_reason_specific_1", "evidence_type":"duplicate_charge_documentation", "content_typ":"application/pdf" }' \
'https://connect.squareupsandbox.com/v2/disputes/{{DISPUTE_ID}}/evidence_file'

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.

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'

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"
   }
}

In the Sandbox, the dispute resolution shows the dispute state WON because the last piece of evidence uploaded has the "evidence_won" string. In production, you see a dispute resolution depending on the bank's determination.

Step 4: Verify dispute status

Call RetrieveDispute and verify the dispute state.

curl -X GET \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
-H 'Content-Type: application/json' \
'https://connect.squareupsandbox.com/v2/disputes/{{DISPUTE_ID}}'

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.

Was this page helpful?

Still haven't found what you are looking for?

Contact Developer Support, or ask for help in the Developer Forums.

Walkthrough: Create, Challenge, and Review a Dispute Resolution

On this page

Test the Disputes API in the Square Sandbox

Example walkthrough

Prepare

Step 1: Create a dispute

Step 2: Upload evidence

Step 2.1: Upload evidence 1 (general evidence, PDF file)

Step 2.2: Upload evidence 2 (general evidence, string “customer ordered item twice; on date-1 and date-2”)

Step 2.3: Upload evidence 3 (dispute reason specific evidence, PDF file)

Note

Step 3: Submit evidence

Step 4: Verify dispute status

Still haven't found what you are looking for?

Walkthrough: Create, Challenge, and Review a Dispute Resolution

On this page

Test the Disputes API in the Square Sandbox Permalink Get a link to this section

Example walkthrough Permalink Get a link to this section

Prepare Permalink Get a link to this section

Step 1: Create a dispute Permalink Get a link to this section

Step 2: Upload evidence Permalink Get a link to this section

Step 2.1: Upload evidence 1 (general evidence, PDF file) Permalink Get a link to this section

Step 2.2: Upload evidence 2 (general evidence, string “customer ordered item twice; on date-1 and date-2”) Permalink Get a link to this section

Step 2.3: Upload evidence 3 (dispute reason specific evidence, PDF file) Permalink Get a link to this section

Note

Step 3: Submit evidence Permalink Get a link to this section

Step 4: Verify dispute status Permalink Get a link to this section

Still haven't found what you are looking for?

Test the Disputes API in the Square Sandbox

Example walkthrough

Prepare

Step 1: Create a dispute

Step 2: Upload evidence

Step 2.1: Upload evidence 1 (general evidence, PDF file)

Step 2.2: Upload evidence 2 (general evidence, string “customer ordered item twice; on date-1 and date-2”)

Step 2.3: Upload evidence 3 (dispute reason specific evidence, PDF file)

Step 3: Submit evidence

Step 4: Verify dispute status