Disputes API

Last updated: November 20, 2024

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.

Event type	Display name	Description
`dispute_accepted` View a dispute accepted webhook example.	Dispute accepted	Occurs when you have accepted a dispute. No further action is required.
`dispute_arbitration_evidence_submitted` View a dispute arbitration evidence submitted webhook example.	Dispute arbitration evidence submitted	Occurs when you submit evidence to support an arbitration.
`dispute_arbitration_lost` View a dispute arbitration lost webhook example.	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` View a dispute arbitration sent to scheme webhook example.	Dispute arbitration sent to scheme	Occurs when the documentation for an arbitration has been sent to the scheme.
`dispute_arbitration_won` View a dispute arbitration won webhook example.	Dispute arbitration won	Occurs when the arbitration has been won. Your account will be credited the disputed amount.
`dispute_canceled` View a dispute canceled webhook example.	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` View a dispute expired webhook example.	Dispute expired	Occurs when the time limit to take action against a dispute has been exceeded. No further action is possible.
`dispute_lost` View a dispute lost webhook example.	Dispute lost	Occurs when the issuing bank has rejected your evidence and you have lost the dispute.
`dispute_resolved` View a dispute resolved webhook example.	Dispute resolved	Occurs when a dispute is received but no further actions is required from you.
`dispute_won` View a dispute won webhook example.	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` View a dispute evidence acknowledged by the scheme webhook example.	Dispute evidence acknowledged by the scheme	Occurs when the supporting documents you sent us have been forwarded to the scheme.
`dispute_evidence_required` View a dispute evidence required webhook example.	Dispute evidence required	Occurs when a dispute has been received for which evidence is required.
`dispute_received` View a dispute received webhook example.	Dispute received	Sent when a dispute notification has been received from the scheme before knowing if further action is possible.
`request_for_information_received` View a request for information received webhook example.	Request for Information Received	Occurs when additional information has been requested for a given payment.
`dispute_evidence_submitted` View a dispute evidence submitted webhook example.	Dispute evidence submitted	Occurs once you have submitted evidence for a given dispute. No further action is required from you.

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.

get

https://api.checkout.com/disputes


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


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

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

For the full API specification, see the API reference.

get

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


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


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

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.

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.

For the full API specification, see the 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.

You must provide at least one of the evidence types listed below in the body of your request. Provide each of the following as either a text string and/or a file ID you've previously uploaded. In your request, specify {evidence_type}_text or {evidence_type}_file. For example, 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

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.
`arbitration_review_required` optional string	The evidence to submit to the Checkout.com Dispute Resolution team. You'll be advised on the likelihood of success if you choose to escalate the dispute to arbitration. Only applies to arbitrations.
`arbitration_no_review` optional string	The evidence to submit directly to the scheme when you escalate the dispute to arbitration. Only applies to arbitrations.

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.

arbitration_review_required

optional

string

The evidence to submit to the Checkout.com Dispute Resolution team. You'll be advised on the likelihood of success if you choose to escalate the dispute to arbitration.

Only applies to arbitrations.

arbitration_no_review

optional

string

The evidence to submit directly to the scheme when you escalate the dispute to arbitration.

Only applies to arbitrations.


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


1import { Checkout } from 'checkout-node-sdk';
2
3const cko = new Checkout('sk_XXXX');
4
5const evidence = await cko.disputes.provideEvidence('dsp_bc94ebda8d275i461229', {
6  proof_of_delivery_or_service_text: 'http://checkout.com/document.pdf',
7});


1{
2  "arbitration_no_review_text" : "Description of files",
3  "arbitration_no_review_files" : ["file_jmbfgkjromvcrn9t4qu1", "file_jmbfgkjromvcrn9t4qu2"],
4  "arbitration_review_required_text" : "Description of files",
5  "arbitration_review_required_files" : ["file_jmbfgkjromvcrn9t4qu3", "file_jmbfgkjromvcrn9t4qu4"]
6}

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.

get

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


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


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

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.

post

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


1import { Checkout } from 'checkout-node-sdk';
2
3const cko = new Checkout('sk_XXXX');
4
5const 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.

post

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


1import { Checkout } from 'checkout-node-sdk';
2
3const cko = new Checkout('sk_XXXX');
4
5const 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.

Disputes API

Dispute reasons

Dispute statuses

View disputes and dispute details

Get a list of disputes

Endpoints

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