Skip to content

Disputes API

Last updated: 16th September 2022

Our disputes API helps you find out about and act on all of your open disputes within the required timeframe. Together with our webhooks, which help you keep track of each status change of a dispute, you'll be well equipped to handle any disputes that arise.

With our disputes API, you can:


Dispute reasons

Most of the time, customers dispute a payment because of fraudulent charges. However, there are many other possible reasons. You can tell why a dispute was raised by looking at the category field of the response.

Learn more about the reasons for disputes and the type of evidence we suggest submitting when responding.


Dispute statuses

Each dispute has an associated status that describes which stage of the dispute process it has reached.

If you would like to be notified when the status of a dispute changes, you can use our webhooks.

disputes api flow
Event typeDisplay nameDescription

dispute_accepted

Dispute accepted

Occurs when you have accepted a dispute. No further action is required.

dispute_arbitration_lost

Dispute arbitration lost

Occurs when an arbitration has been lost. Your account will be debited any additional arbitration-related fees.

dispute_arbitration_sent_to_scheme

Dispute arbitration sent to scheme

Occurs when the documentation for an arbitration has been sent to the scheme.

dispute_arbitration_won

Dispute arbitration won

Occurs when the arbitration has been won. Your account will be credited the disputed amount.

dispute_canceled

Dispute canceled

Occurs when a dispute is canceled by the issuing bank. If previously debited, the disputed amount has been credited back to you.

dispute_expired

Dispute expired

Occurs when the time limit to take action against a dispute has been exceeded. No further action is possible.

dispute_lost

Dispute lost

Occurs when the issuing bank has rejected your evidence and you have lost the dispute.

dispute_resolved

Dispute resolved

Occurs when a dispute is received but no further actions is required from you.

dispute_won

Dispute won

Occurs when the issuing bank has accepted your evidence and you have won the dispute. If previously debited, the amount of the dispute has been credited back to you.

dispute_evidence_acknowledged_by_scheme

Dispute evidence acknowledged by the scheme

Occurs when the supporting documents you sent us have been forwarded to the scheme.

dispute_evidence_required

Dispute evidence required

Occurs when a dispute has been received for which evidence is required.

dispute_received

Dispute received

Sent when a dispute notification has been received from the scheme before knowing if further action is possible.

request_for_information_received

Request for Information Received

Occurs when additional information has been requested for a given payment.

dispute_evidence_submitted

Dispute evidence submitted

Occurs once you have submitted evidence for a given dispute. No further action is required from you.


View disputes and dispute details

You can use our API to view a list of disputes or to retrieve information about a specific dispute.

Get a list of disputes

Use the endpoint below to retrieve a list of disputes against your business. These will be returned in reverse chronological order, showing the last modified dispute (for example, where you've recently added a piece of evidence) first. You can use the additional body parameters to skip or limit results.

Endpoints

For the full API specification, see the API reference.

    get

    https://api.checkout.com/disputes

    Request example

      1
      2
      3
      4
      5
      6
      7
      8
      import { Checkout } from 'checkout-node-sdk';
      const cko = new Checkout('sk_XXXX');
      const disputes = await cko.disputes.get({
      limit: 5,
      id: 'dsp_bc94ebda8d275i461229',
      });

      Response example

      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      15
      16
      17
      18
      19
      20
      21
      22
      23
      24
      25
      26
      27
      28
      29
      30
      31
      32
      33
      34
      35
      36
      37
      38
      39
      40
      {
      "limit": 10,
      "skip": 10,
      "from": "2018-08-12T01:15:56Z",
      "to": "2018-08-13T11:09:01Z",
      "id": "dsp_rbhwd2qrg13uhrp2newf",
      "entity_ids": "ent_wxglze3wwywujg4nna5fb7ldli,ent_vkb5zcy64zoe3cwfmaqvqyqyku",
      "sub_entity_ids": "ent_uzm3uxtssvmuxnyrfdffcyjxeu,ent_hy5wtzwzeuwefmsnjtdhw4scfi",
      "statuses": "evidence_required,evidence_under_review",
      "payment_id": "pay_88cb4e671m1da22e9bbbyx",
      "payment_reference": "th7zxa1kcnqmes8",
      "payment_arn": "74548998294293193445538",
      "payment_mcc": "5021",
      "total_count": 1,
      "data": [
      {
      "id": "dsp_rbhwd2qrg13uhrp2newf",
      "entity_id": "ent_wxglze3wwywujg4nna5fb7ldli",
      "sub_entity_id": "ent_uzm3uxtssvmuxnyrfdffcyjxeu",
      "category": "fraudulent",
      "status": "evidence_required",
      "amount": 999,
      "currency": "GBP",
      "payment_id": "pay_88cb4e671m1da22e9bbbyx",
      "payment_action_id": "act_mbabizu24mvu3mela5njyhpit4",
      "payment_reference": "th7zxa1kcnqmes8",
      "payment_arn": "74548998294293193445538",
      "payment_mcc": "5021",
      "payment_method": "VISA",
      "evidence_required_by": "2018-08-22T00:00:00Z",
      "received_on": "2018-08-01T01:15:56Z",
      "last_update": "2018-08-12T04:15:56Z",
      "_links": {
      "self": {
      "href": "https://api.checkout.com/disputes/dsp_rbhwd2qrg13uhrp2newf"
      }
      }
      }
      ]
      }

      Get details about a dispute

      Use the following endpoint to retrieve all the information relating to a specific dispute.

      Endpoints

      For the full API specification, see the API reference.

        get

        https://api.checkout.com/disputes/{dispute_id}

        Request example

          1
          2
          3
          4
          5
          import { Checkout } from 'checkout-node-sdk';
          const cko = new Checkout('sk_XXXX');
          const disputeDetails = await cko.disputes.getDetails('dsp_bc94ebda8d275i461229');

          Response example

          1
          2
          3
          4
          5
          6
          7
          8
          9
          10
          11
          12
          13
          14
          15
          16
          17
          18
          19
          20
          21
          22
          23
          24
          25
          26
          27
          28
          29
          30
          31
          32
          33
          34
          35
          36
          37
          38
          39
          40
          {
          "id": "dsp_rbhwd2qrg13uhrp2newf",
          "entity_id": "ent_wxglze3wwywujg4nna5fb7ldli",
          "sub_entity_id": "ent_uzm3uxtssvmuxnyrfdffcyjxeu",
          "category": "fraudulent",
          "amount": 999,
          "currency": "GBP",
          "reason_code": "C42",
          "status": "evidence_required",
          "resolved_reason": "already_refunded",
          "relevant_evidence": ["proof_of_delivery_or_service"],
          "evidence_required_by": "2018-08-21T00:00:00Z",
          "received_on": "2018-08-01T04:00:10Z",
          "last_update": "2018-08-04T10:53:13Z",
          "payment": {
          "id": "pay_mbabizu24mvu3mela5njyhpit4",
          "action_id": "act_mbabizu24mvu3mela5njyhpit4",
          "processing_channel_id": "mer_q4dbxom5jbgudnjzjpz7j2z6uq",
          "amount": 999,
          "currency": "GBP",
          "method": "Visa",
          "arn": "AA246873253573571073808",
          "mcc": "5021",
          "3ds": {
          "enrolled": "Y",
          "version": "2.1.0"
          },
          "eci": "06",
          "has_refund": true,
          "processed_on": "2018-08-01T08:18:10Z"
          },
          "_links": {
          "self": {
          "href": "https://api.checkout.com/disputes/dsp_rbhwd2qrg13uhrp2newf"
          },
          "evidence": {
          "href": "https://api.checkout.com/disputes/dsp_rbhwd2qrg13uhrp2newf/evidence"
          }
          }
          }

          Respond to a dispute

          In order to win a dispute, you will need to provide relevant evidence to your case. This could be the invoice, the proof of delivery, or even customer communication regarding the payment that was charged back. You can use our API to upload evidence, review this evidence, and submit it when you're ready.

          Provide evidence

          Use the endpoint below to add supporting evidence to a dispute. Note that this only attaches the evidence to the dispute, it does not send it to us. Once ready, you will need to submit it to us.

          The type of evidence we recommend submitting depends on the reason for the dispute.

          If you wish to submit files as evidence, you will first need to upload them using the file uploader API. This will give you a file id (prefixed by file_) which you can then use in your request.

          Endpoints

          For the full API specification, see the API reference.

            put

            https://api.checkout.com/disputes/{dispute_id}/evidence

            If you run this request more than once, you will overwrite the previous request.

            Additional parameters

            You must provide at least one of the evidence types listed below in the body of your request. Each of the following can be provided as either a text string and/or a file ID previously uploaded. Simply specify it in your request as {evidence_type}_file or {evidence_type}_text (e.g., proof_of_delivery_or_service_file).

            Text strings are limited to 500 characters because they should typically be used only as an addition to a file.

            Evidence typeDescription

            proof_of_delivery_or_service

            optional
            string

            Your proof of delivery or service. Please make sure to add the date of delivery here too.

            invoice_or_receipt

            optional
            string

            The invoice or receipt of the payment.

            invoice_showing_distinct_transactions

            optional
            string
            Your invoice showing two distinct transactions. This is relevant in case the cardholder claims a payment was charged twice (duplicate).

            customer_communication

            optional
            string

            Customer communication relevant to the case which proves that the payment was valid.

            refund_or_cancellation_policy

            optional
            string

            Your refund or cancellation policy. Please always just upload the part of the document that is relevant to this case.

            `recurring_transaction_agreement`
            optional
            string

            Your recurring transaction agreement. Please always just upload the part of the document that is relevant to this case.

            additional_evidence

            optional
            string

            Additional evidence supporting your case that does not fall under the above categories.

            Request example

              1
              2
              3
              4
              5
              6
              7
              8
              9
              10
              11
              12
              13
              14
              15
              16
              17
              18
              {
              "proof_of_delivery_or_service_file": "file_jmbfgkjromvcrn9t4qu4",
              "proof_of_delivery_or_service_text": "http://checkout.com/document.pdf",
              "invoice_or_receipt_file": "file_jmbfgkjromvcrn9t4qu4",
              "invoice_or_receipt_text": "Copy of the invoice",
              "invoice_showing_distinct_transactions_file": "file_jmbfgkjromvcrn9t4qu4",
              "invoice_showing_distinct_transactions_text": "Copy of invoice #1244 showing two transactions",
              "customer_communication_file": "file_jmbfgkjromvcrn9t4qu4",
              "customer_communication_text": "Copy of an email exchange with the cardholder",
              "refund_or_cancellation_policy_file": "file_jmbfgkjromvcrn9t4qu4",
              "refund_or_cancellation_policy_text": "Copy of the refund policy",
              "recurring_transaction_agreement_file": "file_jmbfgkjromvcrn9t4qu4",
              "recurring_transaction_agreement_text": "Copy of the recurring transaction agreement",
              "additional_evidence_file": "file_jmbfgkjromvcrn9t4qu4",
              "additional_evidence_text": "Scanned document",
              "proof_of_delivery_or_service_date_file": "file_jmbfgkjromvcrn9t4qu4",
              "proof_of_delivery_or_service_date_text": "Copy of the customer receipt showing the merchandise was delivered on 2018-12-20"
              }

              The response

              If you receive a 2XX response, then your dispute evidence was successfully provided. You can submit it when ready.

              If you receive a 4XX response, then something went wrong. Check the error codes below to find out why.

              no_evidence_provided

              dispute_already_under_review

              dispute_already_resolved

              dispute_already_expired

              dispute_already_won

              dispute_already_lost

              dispute_already_canceled

              dispute_already_accepted

              Retrieve evidence

              Use the following endpoint to view a list of the evidence you provided for a specific dispute.

              Endpoints

              For the full API specification, see the API reference.

                get

                https://api.checkout.com/disputes/{dispute_id}/evidence

                Request example

                  1
                  2
                  3
                  4
                  5
                  import { Checkout } from 'checkout-node-sdk';
                  const cko = new Checkout('sk_XXXX');
                  const getEvidence = await cko.disputes.getEvidence('dsp_bc94ebda8d275i461229');

                  Response example

                  1
                  2
                  3
                  4
                  5
                  {
                  "proof_of_delivery_or_service_file": "file_jmbfgkjromvcrn9t4qu4",
                  "proof_of_delivery_or_service_text": "Delivery slip signed by the customer",
                  "proof_of_delivery_or_service_date_text": "Merchandise was delivered on 2018-12-30"
                  }

                  Submit evidence

                  Use the following endpoint to submit the evidence that you've provided.

                  You will not be able to amend your evidence once you have submitted it. Make sure you have provided all the relevant information before using this request.

                  Endpoints

                    post

                    https://api.checkout.com/disputes/{dispute_id}/evidence

                    Request example

                      1
                      2
                      3
                      4
                      5
                      import { Checkout } from 'checkout-node-sdk';
                      const cko = new Checkout('sk_XXXX');
                      const submitEvidence = await cko.disputes.submit('dsp_bc94ebda8d275i461229');

                      The response

                      If you receive a 2XX response, then your dispute evidence was successfully submitted. We will pass it on to the card scheme.

                      If you receive a 4XX response, then something went wrong. Check the error codes below to find out why.

                      no_evidence_provided

                      dispute_already_under_review

                      dispute_already_resolved

                      dispute_already_expired

                      dispute_already_won

                      dispute_already_lost

                      dispute_already_canceled

                      dispute_already_accepted

                      Accept a dispute

                      If a dispute is legitimate, you can use the following endpoint to accept it. This will close it for you and remove it from your list of open disputes. There are no further financial implications.

                      Endpoints

                        post

                        https://api.checkout.com/disputes/{dispute_id}/accept

                        Request example

                          1
                          2
                          3
                          4
                          5
                          import { Checkout } from 'checkout-node-sdk';
                          const cko = new Checkout('sk_XXXX');
                          const accept = await cko.disputes.accept('dsp_bc94ebda8d275i461229');

                          The response

                          If you receive a 2XX response, then you successfully accepted the dispute.

                          If you receive a 4XX response, then something went wrong. Check the error codes below to find out why.

                          dispute_already_under_review

                          dispute_already_resolved

                          dispute_already_expired

                          dispute_already_won

                          dispute_already_lost

                          dispute_already_canceled

                          dispute_already_accepted