Disputes API

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:

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.

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.

View a dispute accepted webhook example.

View a dispute arbitration lost webhook example.

View a dispute arbitration sent to scheme webhook example.

View a dispute arbitration won webhook example.

View a dispute canceled webhook example.

View a dispute expired webhook example.

View a dispute lost webhook example.

View a dispute resolved webhook example.

View a dispute won webhook example.

View a dispute evidence acknowledged by the scheme webhook example.

View a dispute evidence required webhook example.

View a dispute received webhook example.

View a request for information received webhook example.

View a dispute evidence submitted webhook example.

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

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.

For the full API specification, see the API reference.

import { Checkout } from 'checkout-node-sdk';

const cko = new Checkout('sk_XXXX');

const disputes = await cko.disputes.get({
  limit: 5,
  id: 'dsp_bc94ebda8d275i461229',
});

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

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

For the full API specification, see the API reference.

import { Checkout } from 'checkout-node-sdk';

const cko = new Checkout('sk_XXXX');

const disputeDetails = await cko.disputes.getDetails('dsp_bc94ebda8d275i461229');

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

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.

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.

For the full API specification, see the API reference.

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).

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

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.

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

For the full API specification, see the API reference.

import { Checkout } from 'checkout-node-sdk';

const cko = new Checkout('sk_XXXX');

const getEvidence = await cko.disputes.getEvidence('dsp_bc94ebda8d275i461229');

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

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

import { Checkout } from 'checkout-node-sdk';

const cko = new Checkout('sk_XXXX');

const submitEvidence = await cko.disputes.submit('dsp_bc94ebda8d275i461229');

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.

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.

import { Checkout } from 'checkout-node-sdk';

const cko = new Checkout('sk_XXXX');

const accept = await cko.disputes.accept('dsp_bc94ebda8d275i461229');

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.