Beta Release
This is pre-release documentation for an API in public beta and is subject to change.
Disputes API

Walkthrough: Create, Challenge, and Review Dispute Resolution

In this walkthrough you test the Disputes API in the Square sandbox.

Testing Disputes API in sandbox Permalink Get a link to this section

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 amountDispute reason
    8801AMOUNT_DIFFERS
    8802CANCELLED
    8803DUPLICATE
    8804NO_KNOWLEDGE
    8805NOT_AS_DESCRIBED
    8806NOT_RECEIVED
    8807PAID_BY_OTHER_MEANS
    8808CUSTOMER_REQUESTS_CREDIT
    8809EMV_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 Permalink Get a link to this section

In this walkthrough, the cURL commands specify sandbox domain in the endpoint URL (connect.squareupsandbox.com).

Prepare Permalink Get a link to this section

To prepare for the walkthrough, do the following:

  1. Create two PDF documents (content of the PDF does not matter in this testing). Name these documents: samplePDF.pdf and evidence_won.pdf. You will upload these test documents as evidence when you challenge the disputes in sandbox.

  2. (optional) In the walkthrough, we use ListDisputes endpoint 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 Permalink Get a link to this section

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 ListDisputes request to verify 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, we will upload evidence to challenge the dispute.

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

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 dispute-specific evidence. The dispute reason in this example is DUPLICATE (the cardholder claims they were charged twice for the same purchase). Let us assume you have two separate receipts as evidence. You upload the receipts as a PDF (evidence_won.pdf) and specify duplicate_charge_documentation as the suitable evidence type.

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

Call CreateDisputeEvidenceFile to upload samplePDF.pdf 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”) Permalink Get a link to this section

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) Permalink Get a link to this section

Call CreateDisputeEvidenceFile to upload evidence_won.pdf with duplicate_charge_documentation as the evidence_type.

Note

In sandbox, "evidence_won" or "evidence_lost" strings in the file name automatically sets 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 Permalink Get a link to this section

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 sandbox, the dispute resolution shows the dispute state WON because the last piece of evidence uploaded has the "evidence_won" string. In production, you will see a dispute resolution depending on the bank’s determination.

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

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 will get a notification with the same information.