You're viewing our new Unified Payments API documentation. Click here to access our Classic API docs.

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:

If you wish to simulate a dispute for testing purposes, you can do so in the sandbox environment. Simply create a payment with one of the test cards and specify the amount as documented here.

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.

Status
Description
Webhook event type

evidence_required

An action on your side is required (you need to respond to the dispute). At this stage, your account gets debited the disputed amount.

dispute_evidence_required
View a dispute evidence required webhook example

resolved

We automatically resolve the dispute because it had already been refunded previously. There are no further financial implications.

dispute_resolved
View a dispute resolved webhook example

canceled

The dispute is canceled by the issuing bank and your account is credited back of the amount of the dispute. You don’t need to take any further action.

dispute_canceled
View a dispute canceled webhook example

evidence_under_review

You have submitted evidence to defend against the dispute. Your evidence is now under review by our Disputes team. Once reviewed, the team will send it to the card scheme for review. No further action is required on your side.

There is no equivalent webhook because your action triggered the status change.

lost

The issuing bank has rejected your evidence and you have lost the dispute. There are no further financial implications.

dispute_lost
View a dispute lost webhook example

won

The issuing bank has accepted your evidence and you have won the dispute. Your account has been credited back of the amount of the dispute.

dispute_won
View a dispute won webhook example

expired

The time limit to take action is met. There is no further implication and you can’t respond to the dispute anymore.

dispute_expired
View a dispute expired webhook example

accepted

You have accepted the dispute. There is no further implication or action required.

There is no equivalent webhook because your action triggered the status change.

Using the disputes API

Header and path parameters

You should use the following header parameters for all dispute-related requests.

Header
Value

Authorization
Required

secret key

Use the valid secret key of your Checkout.com account. You can find this in the Hub.

Content-Type
Required

application/json

Additionally, some of the requests associated with disputes include a path as described below.

Path
Value

dispute_id
Required

The dispute identifier. It is prefixed by dsp_.

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

Retrieve a list of disputes against your business. These will be returned in chronological order, showing the latest updates first. You can use the additional parameters to skip or limit results.

The request

Dispute queries are created using a GET request. Use the details below to set up your request.

Endpoint live

GEThttps://api.checkout.com/disputes/

Endpoint sandbox

GEThttps://api.sandbox.checkout.com/disputes/

Additional parameters

You can use the following additional parameters to specify results. Simply add them to the end of the endpoint URL.

Parameter
Description

limit
Integer
Optional

The number of items to return.

skip
Integer
Optional

The number of items to skip before starting to collect the result set.

from
String
Optional

Filter by 'last update' after the provided value (formatted in ISO 8601). Do not specify the exact time here, as it will return an error.

to
String
Optional

Filter by 'last update' before the provided value (formatted in ISO 8601). Do not specify the exact time here, as it will return an error.

statuses
String
Optional

One or more comma separated statuses, e.g. evidence_required and evidence_under_review.

Request example

curl https://api.sandbox.checkout.com/disputes/?limit=10&skip=10&from=2017-08-12&to=2017-08-13
  -H "Authorization: sk_test_55aedccc-7f53-4ccc-b0a6-d943decc3c31"
  -H "Content-Type:application/json;charset=UTF-8"
  -X GET

The response

If a dispute object returns, then your request was successful. It will look something like this:

{
  "limit": 10,
  "skip": 10,
  "from": "2017-08-12",
  "to": "2017-08-13",
  "total_count": 1,
  "data": [
    {
      "id": "dsp_bd69ed775Z1e5df940d3",
      "category": "product_or_service_not_received",
      "status": "evidence_required",
      "amount": 999,
      "currency": "GBP", 
      "payment_id": "pay_88cb4e671m1da22e9bbb",
      "payment_reference": "th7zxa1kcnqmes8",
      "payment_arn": "74548998294293193445538",
      "payment_method": "Visa",
      "evidence_required_by": "2018-08-22T00:00:00Z",
      "received_on": "2018-08-12",
      "last_update": "2018-08-12",
      "_links": {
        "self": {
          "href": "https://api.sandbox.checkout.com/disputes/dsp_bd69ed775Z1e5df940d3"
        }
      }
    }
  ]
}

Get details about a dispute

Retrieve all information relating to a specific dispute.

The request

Dispute queries are created using a GET request. Use the details below to set up your request.

Endpoint live

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

Endpoint sandbox

GEThttps://api.sandbox.checkout.com/disputes/{dispute_id}

Request example

curl https://api.sandbox.checkout.com/disputes/dsp_BD69ED775Z1E5DF940D3
    -H "Authorization: sk_test_55aedccc-7f53-4ccc-b0a6-d943decc3c31"
    -H "Content-Type:application/json;charset=UTF-8"
    -X GET

The response

If a dispute object returns, then your request was successful. It will look something like this:

{
  "id": "dsp_bd69ed775Z1e5df940d3",
  "category": "product_or_service_not_received",
  "amount": 999,
  "reason_code": "13.1",
  "status": "evidence_required",
  "relevant_evidence": [
    "proof_of_delivery_or_service, invoice_or_receipt, customer_communication, additional_evidence"
  ],
  "evidence_required_by": "2018-08-16",
  "received_on": "2018-08-12",
  "last_update": "2018-08-12",
  "payment": {
    "id": "pay_c8daae073p1e4b5b8a4a",
    "reference": "04100ab2110f66e4",
    "amount": 999,
    "currency": "GBP",
    "arn": "24687325357357107380887",
    "method": "Visa",
    "processed_on": "2018-08-01"
  },
  "_links": {
    "self": {
      "href": "https://api.sandbox.checkout.com/disputes/dsp_bd69ed775z1e5df940d3"
    },
    "evidence": {
      "href": "https://api.sandbox.checkout.com/disputes/dsp_bd69ed775z1e5df940d3/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

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. Click here to find out more.

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.

The request

A request to provide evidence is created using a PUT request. Use the details below to set up your request.

Endpoint live

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

Endpoint sandbox

PUThttps://api.sandbox.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).

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

Evidence type
Description

proof_of_delivery_or_service
String
Optional

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

invoice_or_receipt
String
Optional

The invoice or receipt of the payment.

invoice_showing_distinct_transactions
String
Optional

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

customer_communication
String
Optional

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

refund_or_cancellation_policy
String
Optional

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

recurring_transaction_agreement
String
Optional

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

additional_evidence
String
Optional

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

Request example

curl https://api.sandbox.checkout.com/disputes/dsp_BD69ED775Z1E5DF940D3
    -H "Authorization: sk_test_55aedccc-7f53-4ccc-b0a6-d943decc3c31"
    -H "Content-Type:application/json;charset=UTF-8"
    -X PUT
    -d {
  	  "proof_of_delivery_or_service_file": "file_bd69ed775z1e5df940d3",
  	  "proof_of_delivery_or_service_text": "a brief description of the file",
  	  "customer_communication_file": "file_iw68oe795o1e5xc940s9"
}

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 code 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 this API to view a list of the evidence that was provided for a specific dispute.

The request

Evidence can be retrieved using a GET request. Use the details below to set up your request.

Endpoint live

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

Endpoint sandbox

GEThttps://sandbox.checkout.com/disputes/{dispute_id}/evidence

Request example

curl https://api.sandbox.checkout.com/disputes/dsp_BD69ED775Z1E5DF940D3/evidence
    -H "Authorization: sk_test_55aedccc-7f53-4ccc-b0a6-d943decc3c31"
    -H "Content-Type:application/json;charset=UTF-8"
    -X GET

The response

Response example

If you receive a response containing a dispute object, then your request was successful. It will look something like this:

{
  "proof_of_delivery_or_service_file": "file_bd69ed775z1e5df940d3",
  "proof_of_delivery_or_service_text": "a brief description of the file",
  "customer_communication": "file_iw68oe795o1e5xc940s9"
}

Submit evidence

With this final request, you can submit the evidence that you have previously 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.

The request

Evidence submissions are created using a POST request. Use the details below to set up your request.

Endpoint live

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

Endpoint sandbox

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

Request example

curl https://api.sandbox.checkout.com/disputes/dsp_BD69ED775Z1E5DF940D3/evidence
    -H "Authorization: sk_test_55aedccc-7f53-4ccc-b0a6-d943decc3c31"
    -H "Content-Type:application/json;charset=UTF-8"
    -X POST

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

The request

Disputes are accepted via a POST request. Use the details below to set up your request.

Endpoint live

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

Endpoint sandbox

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

Request example

curl https://api.sandbox.checkout.com/disputes/dsp_BD69ED775Z1E5DF940D3/accept
    -H "Authorization: sk_test_55aedccc-7f53-4ccc-b0a6-d943decc3c31"
    -H "Content-Type:application/json;charset=UTF-8"
    -X POST

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 code 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

Can we help?

Thanks for using Checkout.com. If you need any help or support, then message our support team at support@checkout.com.

Disputes API


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.