Disputes

​

Keep track of and act on your open disputes (also known as chargebacks) to submit the best possible response.

Disputes Operations

Get disputes

​

Returns a list of all disputes against your business. The results 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 optional parameters below to skip or limit results.

Query Parameters
  • limit
    Type: integer
    min:  
    1
    max:  
    250

    The numbers of results to return

  • skip
    Type: integer
    min:  
    0

    The number of results to skip

  • from
    Type: string Format: date-time

    The date and time from which to filter disputes, based on the dispute's last_update field

  • to
    Type: string Format: date-time

    The date and time until which to filter disputes, based on the dispute's last_update field

  • id
    Type: string

    The unique identifier of the dispute

  • entity_ids
    Type: string

    One or more comma-separated client entities. This works like a logical OR operator

  • sub_entity_ids
    Type: string

    One or more comma-separated sub-entities. This works like a logical OR operator

  • processing_channel_ids
    Type: string

    One or more comma-separated processing channels. This works like a logical OR operator.

  • segment_ids
    Type: string

    One or more comma-separated segments. This works like a logical OR operator.

  • statuses
    Type: string

    One or more comma-separated statuses. This works like a logical OR operator

  • payment_id
    Type: string

    The unique identifier of the payment

  • payment_reference
    Type: string

    An optional reference (such as an order ID) that you can use later to identify the payment. Previously known as TrackId

  • payment_arn
    Type: string

    The acquirer reference number (ARN) that you can use to query the issuing bank

  • payment_mcc
    Type: string

    The merchant category code (MCC) of the payment (ISO 18245)

  • this_channel_only
    Type: boolean

    If true, only returns disputes of the specific channel that the secret key is associated with. Otherwise, returns all disputes for that business

Responses
  • application/json
  • 401

    Unauthorized

  • application/json
Request Example for get/disputes
curl 'https://{prefix}.api.sandbox.checkout.com/disputes' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "limit": 10,
  "skip": 10,
  "from": "2018-08-12T01:15:56Z",
  "to": "2018-08-13T11:09:01Z",
  "id": "dsp_rbhwd2qrg13uhrp2newfcd",
  "entity_ids": "ent_wxglze3wwywujg4nna5fb7ldli,ent_vkb5zcy64zoe3cwfmaqvqyqyku",
  "sub_entity_ids": "ent_uzm3uxtssvmuxnyrfdffcyjxeu,ent_hy5wtzwzeuwefmsnjtdhw4scfi",
  "processing_channel_ids": "pc_uzm3uxtssvmuxnyrfdffcyjxeu,pc_hy5wtzwzeuwefmsnjtdhw4scfi",
  "segment_ids": "string",
  "statuses": "evidence_required,evidence_under_review",
  "payment_id": "pay_lzmo6p0i3612judj754w1ngtil",
  "payment_reference": "th7zxa1kcnqmes8",
  "payment_arn": "74548998294293193445538",
  "payment_mcc": "5021",
  "this_channel_only": true,
  "total_count": 1,
  "data": [
    {
      "id": "dsp_rbhwd2qrg13uhrp2newfafreds",
      "entity_id": "ent_wxglze3wwywujg4nna5fb7ldli",
      "sub_entity_id": "ent_uzm3uxtssvmuxnyrfdffcyjxeu",
      "processing_channel": "pc_uzm3uxtssvmuxnyrfdffcyjxeu",
      "segment_id": "string",
      "category": "fraudulent",
      "status": "evidence_required",
      "amount": 999,
      "currency": "GBP",
      "reason_code": "10.4",
      "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",
      "resolved_reason": "already_refunded",
      "is_ce_candidate": true,
      "_links": {
        "self": {
          "href": "https://{prefix}.api.checkout.com/disputes/dsp_rbhwd2qrg13uhrp2newf"
        }
      }
    }
  ]
}

Disputes retrieved successfully

Get dispute details

​

Returns all the details of a dispute using the dispute identifier.

Path Parameters
  • dispute_id
    Type: string Pattern: ^(dsp)_(\\w{22,26})$
    required

    The dispute identifier

Responses
  • application/json
  • 401

    Unauthorized

  • 404

    Dispute not found

Request Example for get/disputes/{dispute_id}
curl 'https://{prefix}.api.sandbox.checkout.com/disputes/{dispute_id}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "id": "dsp_rbhwd2qrg13uhrp2newfarfder",
  "entity_id": "ent_wxglze3wwywujg4nna5fb7ldli",
  "sub_entity_id": "ent_uzm3uxtssvmuxnyrfdffcyjxeu",
  "reference": "dispute-09",
  "category": "fraudulent",
  "amount": 999,
  "currency": "GBP",
  "reason_code": "10.4",
  "status": "evidence_required",
  "resolved_reason": "already_refunded",
  "relevant_evidence": [
    [
      "proof_of_delivery_or_service",
      "compelling_evidence"
    ]
  ],
  "evidence_required_by": "2018-08-21T00:00:00Z",
  "received_on": "2018-08-01T04:00:10Z",
  "last_update": "2018-08-04T10:53:13Z",
  "is_ce_candidate": true,
  "payment": {
    "id": "pay_mbabizu24mvu3mela5njyhpit4",
    "action_id": "act_mbabizu24mvu3mela5njyhpit4",
    "processing_channel_id": "pc_q4dbxom5jbgudnjzjpz7j2z6uq",
    "amount": 999,
    "currency": "GBP",
    "reference": "string",
    "method": "Visa",
    "acquirer_reference_number": "AA246873253573571073808",
    "mcc": "5021",
    "3ds": {
      "version": "2.1.0",
      "enrolled": "Y"
    },
    "eci": "06",
    "has_refund": true,
    "processed_on": "2018-08-01T08:18:10Z"
  },
  "evidence_list": [
    {
      "file": "string",
      "text": "string",
      "type": "proof_of_delivery_or_service",
      "dispute_id": "string"
    }
  ],
  "evidence_bundle": [
    {
      "dispute_id": "dsp_rbhwd2qrg13uhrp2newfab",
      "filename": "string",
      "file_size": 1,
      "is_file_oversized": true,
      "created_at": "2026-09-23T13:52:07.856Z",
      "modified_at": "2026-09-23T13:52:07.856Z"
    }
  ],
  "segment_id": "string",
  "_links": {
    "self": {
      "href": "https://{prefix}.api.checkout.com/disputes/dsp_rbhwd2qrg13uhrp2newf"
    },
    "evidence": {
      "href": "https://{prefix}.api.checkout.com/disputes/dsp_rbhwd2qrg13uhrp2newf/evidence"
    }
  }
}

Dispute retrieved successfully

Accept dispute

​

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

Path Parameters
  • dispute_id
    Type: string Pattern: ^(dsp)_(\w{26})$
    required

    The dispute identifier

Responses
  • 204

    Dispute accepted successfully

  • 401

    Unauthorized

  • 404

    Dispute not found

Request Example for post/disputes/{dispute_id}/accept
curl 'https://{prefix}.api.sandbox.checkout.com/disputes/{dispute_id}/accept' \
  --request POST \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
No Body

Dispute accepted successfully

Provide dispute evidence

​

Adds supporting evidence to a dispute. Before using this endpoint, you first need to upload your files using the file uploader. You will receive a file id (prefixed by file_) which you can then use in your request. 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. You must provide at least one evidence type in the body of your request.

Path Parameters
  • dispute_id
    Type: string Pattern: ^(dsp)_(\w{26})$
    required

    The dispute identifier.

Body·
application/json
  • proof_of_delivery_or_service_file
    Type: string

    A file containing proof of delivery of goods or services.

  • proof_of_delivery_or_service_text
    Type: string

    A brief description of the file provided in proof_of_delivery_or_service_file.

    Alternatively, you can provide a link to an externally-hosted file containing the description.

  • proof_of_delivery_or_service_date_file
    Type: string

    A file showing the delivery date of the provided service or merchandise.

  • proof_of_delivery_or_service_date_text
    Type: string

    A brief description of the file provided in proof_of_delivery_or_service_date_file.

    Alternatively, you can provide a link to an externally-hosted file containing the description.

  • invoice_or_receipt_file
    Type: string

    A file containing an invoice or receipt.

  • invoice_or_receipt_text
    Type: string

    A brief description of the file provided in invoice_or_receipt_file.

    Alternatively, you can provide a link to an externally-hosted file containing the description.

  • invoice_showing_distinct_transactions_file
    Type: string

    A file containing invoice showing two distinct transactions.

  • invoice_showing_distinct_transactions_text
    Type: string

    A brief description of the file provided in invoice_showing_distinct_transactions_file.

    Alternatively, you can provide a link to an externally-hosted file containing the description.

  • customer_communication_file
    Type: string

    A file containing customer communication.

  • customer_communication_text
    Type: string

    A brief description of the file provided in customer_communication_file.

    Alternatively, you can provide a link to an externally-hosted file containing the description.

  • refund_or_cancellation_policy_file
    Type: string

    A file containing refund/cancellation policy

  • refund_or_cancellation_policy_text
    Type: string

    A brief description of the file provided in refund_or_cancellation_policy_file.

    Alternatively, you can provide a link to an externally-hosted file containing the description.

Responses
  • 204

    Dispute evidence provided successfully

  • 400

    Unprocessable

  • 401

    Unauthorized

  • 404

    Dispute not found

  • application/json
Request Example for put/disputes/{dispute_id}/evidence
curl 'https://{prefix}.api.sandbox.checkout.com/disputes/{dispute_id}/evidence' \
  --request PUT \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "proof_of_delivery_or_service_file": "file_jmbfgkjromvcrn9t4qu4",
  "proof_of_delivery_or_service_text": "Description of evidence available at: http://checkout.com/evidenceDocument.pdf",
  "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",
  "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",
  "arbitration_no_review_files": [
    "file_jmbfgkjromvcrn9t4qu4",
    "file_kmbfgkjromvcrn9t4qu5"
  ],
  "arbitration_no_review_text": "Evidence for arbitration",
  "arbitration_review_required_files": [
    "file_jmbfgkjromvcrn9t4qu4",
    "file_kmbfgkjromvcrn9t4qu5"
  ],
  "arbitration_review_required_text": "Evidence for arbitration",
  "compelling_evidence": {
    "merchandise_or_service": "Merchandise",
    "merchandise_or_service_desc": "Subscription payment",
    "merchandise_or_service_provided_date": "2024-07-25T11:23:06Z",
    "shipping_delivery_status": "shipped",
    "tracking_information": "129481229312",
    "user_id": "user@cko.com",
    "ip_address": "192.168.1.150",
    "device_id": "device_123_x_1220",
    "shipping_address": {
      "address": "",
      "address2": "",
      "city": "",
      "state_region": "",
      "postal_code": "",
      "country": "826"
    },
    "historical_transactions": [
      {
        "historical_arn": "",
        "merchandise_or_service_desc": ""
      }
    ]
  },
  "_links": {
    "self": {
      "href": "https://{prefix}.api.checkout.com/disputes/dsp_rbhwd2qrg13uhrp2newf12/evidence"
    },
    "parent": {
      "href": "https://{prefix}.api.checkout.com/disputes/dsp_rbhwd2qrg13uhrp2newf12"
    }
  }
}'
No Body

Dispute evidence provided successfully

Get dispute evidence

​

Retrieves a list of the evidence submitted in response to a specific dispute.

Path Parameters
  • dispute_id
    Type: string Pattern: ^(dsp)_(\w{26})$
    required

    The dispute identifier.

Responses
  • application/json
  • 401

    Unauthorized

  • 404

    Dispute not found

Request Example for get/disputes/{dispute_id}/evidence
curl 'https://{prefix}.api.sandbox.checkout.com/disputes/{dispute_id}/evidence' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "proof_of_delivery_or_service_file": "file_jmbfgkjromvcrn9t4qu4",
  "proof_of_delivery_or_service_text": "Description of evidence available at: http://checkout.com/evidenceDocument.pdf",
  "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",
  "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",
  "arbitration_no_review_files": [
    "file_jmbfgkjromvcrn9t4qu4",
    "file_kmbfgkjromvcrn9t4qu5"
  ],
  "arbitration_no_review_text": "Evidence for arbitration",
  "arbitration_review_required_files": [
    "file_jmbfgkjromvcrn9t4qu4",
    "file_kmbfgkjromvcrn9t4qu5"
  ],
  "arbitration_review_required_text": "Evidence for arbitration",
  "compelling_evidence": {
    "merchandise_or_service": "Merchandise",
    "merchandise_or_service_desc": "Subscription payment",
    "merchandise_or_service_provided_date": "2024-07-25T11:23:06Z",
    "shipping_delivery_status": "shipped",
    "tracking_information": "129481229312",
    "user_id": "user@cko.com",
    "ip_address": "192.168.1.150",
    "device_id": "device_123_x_1220",
    "shipping_address": {
      "address": "string",
      "address2": "string",
      "city": "string",
      "state_region": "string",
      "postal_code": "string",
      "country": "826"
    },
    "historical_transactions": [
      {
        "historical_arn": "string",
        "merchandise_or_service_desc": "string"
      }
    ]
  }
}

Dispute evidence retrieved successfully

Submit dispute evidence

​

With this final request, you can submit the evidence that you have previously provided. Make sure you have provided all the relevant information before using this request. You will not be able to amend your evidence once you have submitted it.

Path Parameters
  • dispute_id
    Type: string Pattern: ^(dsp)_(\w{26})$
    required

    The dispute identifier.

Responses
  • 204

    Dispute evidence submitted successfully

  • 401

    Unauthorized

  • 404

    Dispute not found

  • application/json
Request Example for post/disputes/{dispute_id}/evidence
curl 'https://{prefix}.api.sandbox.checkout.com/disputes/{dispute_id}/evidence' \
  --request POST \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
No Body

Dispute evidence submitted successfully

Submit dispute arbitration evidence

​

Submits the previously provided arbitration evidence to the scheme.

You cannot amend evidence after you submit with this endpoint. Ensure you have provided all of the required information.

Path Parameters
  • dispute_id
    Type: string Pattern: ^(dsp)_(\w{26})$
    required

    The dispute identifier.

Responses
  • 204

    Dispute arbitration evidence submitted successfully

  • 401

    Unauthorized

  • 404

    Dispute not found

  • application/json
Request Example for post/disputes/{dispute_id}/evidence/arbitration
curl 'https://{prefix}.api.sandbox.checkout.com/disputes/{dispute_id}/evidence/arbitration' \
  --request POST \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
No Body

Dispute arbitration evidence submitted successfully

Get dispute submitted arbitration evidence

​

Retrieves the unique identifier of the PDF file containing all of the evidence submitted to escalate the dispute to arbitration.

To retrieve the file's download link, call the GET /files/{file_id} endpoint with the returned file ID.

Path Parameters
  • dispute_id
    Type: string Pattern: ^(dsp)_(\w{22,26})$
    required

    The dispute identifier.

Responses
  • application/json
  • 403

    Forbidden

  • 404

    Resource not found

  • 500

    Internal error

Request Example for get/disputes/{dispute_id}/evidence/arbitration/submitted
Shell Curl
curl 'https://{prefix}.api.sandbox.checkout.com/disputes/{dispute_id}/evidence/arbitration/submitted' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "file_id": "file_iweu3nxyt6zund3gwhg7wo4fhq",
  "_links": {
    "self": {
      "href": "https://{prefix}.api.checkout.com/disputes/dsp_f28bcafe073z72ad4a18/evidence/submitted"
    }
  }
}

Dispute retrieved successfully

Get dispute submitted evidence

​

Retrieves the unique identifier of the PDF file containing all the evidence submitted to represent the dispute case.

To retrieve the file's download link, call the GET /files/{file_id} endpoint with the returned file ID.

Evidence submitted before February 2024 cannot be retrieved using this endpoint.

Path Parameters
  • dispute_id
    Type: string Pattern: ^(dsp)_(\w{22,26})$
    required

    The dispute identifier.

Responses
  • application/json
  • 403

    Forbidden

  • 404

    Resource not found

  • 500

    Internal error

Request Example for get/disputes/{dispute_id}/evidence/submitted
Shell Curl
curl 'https://{prefix}.api.sandbox.checkout.com/disputes/{dispute_id}/evidence/submitted' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "file_id": "file_iweu3nxyt6zund3gwhg7wo4fhq",
  "_links": {
    "self": {
      "href": "https://{prefix}.api.checkout.com/disputes/dsp_f28bcafe073z72ad4a18/evidence/submitted"
    }
  }
}

Dispute retrieved successfully

Get dispute scheme files

​

Returns all of the scheme files of a dispute using the dispute identifier. Currently available only for VISA disputes.

Path Parameters
  • dispute_id
    Type: string Pattern: ^(dsp)_(\w{22,26})$
    required

    The dispute identifier

Responses
  • application/json
  • 401

    Unauthorized

  • 404

    Dispute not found

Request Example for get/disputes/{dispute_id}/schemefiles
curl 'https://{prefix}.api.sandbox.checkout.com/disputes/{dispute_id}/schemefiles' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "id": "dsp_rbhwd2qrg13uhrp2newfab",
  "files": [
    {
      "dispute_status": "dispute_lost",
      "file": "file_6lbss42ezvoufcb2beo76rvwly"
    }
  ],
  "_links": {
    "self": {
      "href": "https://{prefix}.api.checkout.com/disputes/dsp_rbhwd2qrg13uhrp2newf/schemefiles"
    }
  }
}

Dispute retrieved successfully

Upload file

​

Upload a file to use as evidence in a dispute. Your file must be in either JPEG/JPG, PNG or PDF format, and be no larger than 4MB.

Body
application/json
Responses
  • application/json
  • 401

    Unauthorized

  • 422

    Unprocessable

  • 429

    Too many requests

Request Example for post/files
curl 'https://{prefix}.api.sandbox.checkout.com/files' \
  --request POST \
  --header 'Content-Type: multipart/form-data' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --form 'file=file=@/path/receipt.png;type=image/png' \
  --form 'purpose=dispute_evidence'

{
  "id": "file_6lbss42ezvoufcb2beo76rvwly",
  "_links": {
    "self": {
      "href": "https://{prefix}.api.checkout.com/files/file_6lbss42ezvoufcb2beo76rvwly"
    }
  }
}

File uploaded successfully

Get file information

​

Retrieve information about a file that was previously uploaded.

Path Parameters
  • file_id
    Type: string
    required

    The file identifier. It is always prefixed by file_.

Responses
  • application/json
  • 401

    Unauthorized

  • 404

    File not found

  • 429

    Too many requests or duplicate request detected

Request Example for get/files/{file_id}
curl 'https://{prefix}.api.sandbox.checkout.com/files/{file_id}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

{
  "id": "file_6lbss42ezvoufcb2beo76rvwly",
  "filename": "receipt.jpg",
  "purpose": "dispute_evidence",
  "size": 1024,
  "uploaded_on": "2019-05-17T16:48:52Z",
  "_links": {
    "self": {
      "href": "https://{prefix}.api.checkout.com/files/file_6lbss42ezvoufcb2beo76rvwly"
    },
    "download": {
      "href": "https://file-bucket.s3.eu-west-1.amazonaws.com/ucdac/ucdac/6lbss42ezvoufcb2beo76rvwly?X-Amz-Expires=3600&x-amz-security-token=FQoDYXdzENL%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEa"
    }
  }
}

File information retrieved successfully