/ /

Disputes API

Last updated: April 29, 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:

Information

If you want 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 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.

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.

Disputes API flow

Using the Disputes API

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 parameters to skip or limit results.

Endpoints

For the full specification, as well as complete request and response examples, see our API Reference

get

https://api.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` optional string	The number of items to return.
`skip` optional integer	The number of items to skip before starting to collect the result set.
`from` optional string	Filter by 'last update' after the provided value (formatted in ISO 8601).
`to` optional string	Filter by 'last update' before the provided value (formatted in ISO 8601).
`statuses` optional string	One or more statuses, separated by commas, e.g. `evidence_required` and `evidence_under_review`.

Request example

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

Response example

1{
2      "limit": 10,
3      "skip": 10,
4      "from": "2018-01-01T00:00:00Z",
5      "to": "2018-01-02T00:00:00Z",
6      "total_count": 1,
7      "data": [
8        {
9          "id": "dsp_bd69ed775Z1e5df940d3",
10          "category": "product_or_service_not_received",
11          "status": "evidence_required",
12          "amount": 999,
13          "currency": "GBP",
14          "payment_id": "pay_88cb4e671m1da22e9bbbyx",
15          "payment_reference": "th7zxa1kcnqmes8",
16          "payment_arn": "74548998294293193445538",
17          "payment_method": "Visa",
18          "evidence_required_by": "2018-08-22T00:00:00Z",
19          "received_on": "2018-08-12T00:00:00Z",
20          "last_update": "2018-08-12T00:00:00Z",
21          "_links": {
22            "self": {
23              "href": "https://api.sandbox.checkout.com/disputes/dsp_bd69ed775Z1e5df940d3"
24            }
25          }
26        }
27      ]
28    }

Get details about a dispute

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

Endpoints

For the full specification, as well as complete request and response examples, see our API Reference

get

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

Request example

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

Response example

1{
2      "id": "dsp_bd69ed775Z1e5df940d3",
3      "category": "product_or_service_not_received",
4      "amount": 999,
5      "reason_code": "13.1",
6      "status": "evidence_required",
7      "relevant_evidence": [
8        "proof_of_delivery_or_service, invoice_or_receipt, customer_communication, additional_evidence"
9      ],
10      "evidence_required_by": "2018-08-16T00:00:00Z",
11      "received_on": "2018-08-12T00:00:00Z",
12      "last_update": "2018-08-12T00:00:00Z",
13      "payment": {
14        "id": "pay_c8daae073p1e4b5b8a4ayx",
15        "reference": "04100ab2110f66e4",
16        "amount": 999,
17        "currency": "GBP",
18        "arn": "24687325357357107380887",
19        "method": "Visa",
20        "processed_on": "2018-08-01T00:00:00Z"
21      },
22      "_links": {
23        "self": {
24          "href": "https://api.sandbox.checkout.com/disputes/dsp_bd69ed775z1e5df940d3"
25        },
26        "evidence": {
27          "href": "https://api.sandbox.checkout.com/disputes/dsp_bd69ed775z1e5df940d3/evidence"
28        }
29      }
30    }

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.

Information

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

Note

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 specification, as well as complete request and response examples, see our API reference.

put

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

Note

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

Information

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

Evidence type	Description
`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

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

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.

Possible error codes

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 specification, as well as complete request and response examples, see our API reference.

get

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

Request example

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

Response example

1{
2      "proof_of_delivery_or_service_file": "file_bd69ed775z1e5df940d3",
3      "proof_of_delivery_or_service_text": "a brief description of the file",
4      "customer_communication": "file_iw68oe795o1e5xc940s9"
5    }

Submit evidence

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

Note

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

For the full specification, as well as complete request and response examples, see our API Reference

post

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

Request example

1curl https://api.sandbox.checkout.com/disputes/dsp_BD69ED775Z1E5DF940D3/evidence
2        -H "Authorization: sk_test_55aedccc-7f53-4ccc-b0a6-d943decc3c31"
3        -H "Content-Type:application/json;charset=UTF-8"
4        -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 codes below to find out why.

Possible error codes

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

For the full specification, as well as complete request and response examples, see our API Reference

post

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

Request example

1curl https://api.sandbox.checkout.com/disputes/dsp_BD69ED775Z1E5DF940D3/accept
2        -H "Authorization: sk_test_55aedccc-7f53-4ccc-b0a6-d943decc3c31"
3        -H "Content-Type:application/json;charset=UTF-8"
4        -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 codes below to find out why.

Possible error codes

dispute_already_under_review
dispute_already_resolved
dispute_already_expired
dispute_already_won
dispute_already_lost
dispute_already_canceled
dispute_already_accepted

Information

Dispute reasons

Dispute statuses

Disputes API flow

Using the Disputes API

View disputes and dispute details

Get a list of disputes

Endpoints

Additional parameters

Request example

Response example

Get details about a dispute

Endpoints

Request example

Response example

Respond to a dispute

Provide evidence

Information

Note

Endpoints

Note

Additional parameters

Information

Request example

The response

Retrieve evidence

Endpoints

Request example

Response example

Submit evidence

Note

Endpoints

Request example

The response

Accept a dispute

Endpoints

Request example

The response

On this page