# Disputes API
The 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:
1. [View a list of disputes](#Get_a_list_of_disputes)
1. [View information about a specific dispute](#Get_details_about_a_dispute)
1. [Provide evidence](#Provide_evidence)
1. [Accept a dispute](#Accept_a_dispute)
---
## 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](https://www.checkout.com/docs/risk-management/disputes.md) when responding.
---
## Dispute statuses
Each dispute has an associated `status` that describes which stage of the dispute process it has reached.
If you want to be notified when the status of a dispute changes, you can subscribe to [disputes webhooks](https://www.checkout.com/docs/developer-resources/event-notifications/event-types.md#Disputes).
| Event type | Display name | Description |
| --- | --- | --- |
| `dispute_accepted`
[See example](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/dispute_accepted.md) | Dispute accepted | Occurs when you accept a dispute.
No further action is required. |
| `dispute_arbitration_evidence_submitted`
[See example](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/dispute_arbitration_evidence_submitted.md) | Dispute arbitration evidence submitted | Occurs when you submit evidence to support an arbitration. |
| `dispute_arbitration_lost`
[See example](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/dispute_arbitration_lost.md) | Dispute arbitration lost | Occurs when you lose an arbitration.
Your account is debited any additional arbitration-related fees. |
| `dispute_arbitration_sent_to_scheme`
[See example](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/dispute_arbitration_sent_to_scheme.md) | Dispute arbitration sent to scheme | Occurs when the documentation for an arbitration is sent to the scheme. |
| `dispute_arbitration_won`
[See example](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/dispute_arbitration_won.md) | Dispute arbitration won | Occurs when you win an arbitration.
Your account is credited the disputed amount. |
| `dispute_canceled`
[See example](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/dispute_canceled.md) | Dispute canceled | Occurs when the issuer cancels a dispute.
If previously debited, the disputed amount is credited back to you. |
| `dispute_expired`
[See example](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/dispute_expired.md) | Dispute expired | Occurs when the time limit to take action against a dispute expires. No further action is possible. |
| `dispute_lost`
[See example](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/dispute_lost.md) | Dispute lost | Occurs when the issuer rejects your evidence and you lose the dispute. |
| `dispute_resolved`
[See example](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/dispute_resolved.md) | Dispute resolved | Occurs when a dispute is received but no further action is required. |
| `dispute_won`
[See example](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/dispute_won.md) | Dispute won | Occurs when the issuer accepts your evidence and you win the dispute.
If previously debited, the disputed amount is credited back to you. |
| `dispute_evidence_acknowledged_by_scheme`
[See example](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/dispute_evidence_acknowledged_by_scheme.md) | Dispute evidence acknowledged by the scheme | Occurs when the supporting documents you sent us are forwarded to the scheme. |
| `dispute_evidence_required`
[See example](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/dispute_evidence_required.md) | Dispute evidence required | Occurs when a dispute is received for which evidence is required. |
| `dispute_received`
[See example](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/dispute_received.md) | Dispute received | Occurs when a dispute notification is received from the scheme before knowing if further action is possible. |
| `request_for_information_received`
[See example](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/request_for_information_received.md) | Request for Information received | Occurs when additional information is requested for a payment. |
| `dispute_evidence_submitted`
[See example](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/dispute_evidence_submitted.md) | Dispute evidence submitted | Occurs when you submit evidence for a dispute.
No further action is required. |
---
## 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 following endpoint 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.
### Endpoints
For the full API specification, see the [API reference](https://api-reference.checkout.com/).
> **Information**
>
> Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md).
**Production**
`GET` `https://{prefix}.api.checkout.com/disputes`
**Sandbox**
`GET` `https://{prefix}.api.sandbox.checkout.com/disputes`
### Request example
**Node.js (Beta)**
```js
import { Checkout } from 'checkout-node-sdk';
const cko = new Checkout('sk_XXXX');
const disputes = await cko.disputes.get({
limit: 5,
id: 'dsp_bc94ebda8d275i461229',
});
```
### Response example
```json
{
"limit": 10,
"skip": 10,
"from": "2024-08-12T01:15:56Z",
"to": "2024-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": "2024-08-22T00:00:00Z",
"received_on": "2024-08-01T01:15:56Z",
"last_update": "2024-08-12T04:15:56Z",
"_links": {
"self": {
"href": "https://{prefix}.api.checkout.com/disputes/dsp_rbhwd2qrg13uhrp2newf"
}
}
}
]
}
```
### Get details about a dispute
Use the following endpoint to retrieve all the information relating to a specific dispute.
### Endpoints
For the full API specification, see the [API reference](https://api-reference.checkout.com/).
> **Information**
>
> Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md).
**Production**
`GET` `https://{prefix}.api.checkout.com/disputes/{dispute_id}`
**Sandbox**
`GET` `https://{prefix}.api.sandbox.checkout.com/disputes/{dispute_id}`
### Request example
**Node.js (Beta)**
```js
import { Checkout } from 'checkout-node-sdk';
const cko = new Checkout('sk_XXXX');
const disputeDetails = await cko.disputes.getDetails('dsp_bc94ebda8d275i461229');
```
### Response example
```json
{
"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": "2024-08-21T00:00:00Z",
"received_on": "2024-08-01T04:00:10Z",
"last_update": "2024-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": "2024-08-01T08:18:10Z"
},
"_links": {
"self": {
"href": "https://{prefix}.api.checkout.com/disputes/dsp_rbhwd2qrg13uhrp2newf"
},
"evidence": {
"href": "https://{prefix}.api.checkout.com/disputes/dsp_rbhwd2qrg13uhrp2newf/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
Use the following endpoint 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](#Submit_evidence) to us.
> **Information**
>
> The type of evidence we recommend submitting [depends on the reason for the dispute](https://www.checkout.com/docs/risk-management/disputes.md).
> **Note**
>
> If you wish to submit files as evidence, you will first need to upload them using the [File uploader API](https://www.checkout.com/docs/risk-management/disputes/file-uploader.md). This will give you a file `id` (prefixed by `file_`) which you can then use in your request.
### Endpoints
For the full API specification, see the [API reference](https://api-reference.checkout.com/).
> **Information**
>
> Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md).
**Production**
`PUT` `https://{prefix}.api.checkout.com/disputes/{dispute_id}/evidence`
**Sandbox**
`PUT` `https://{prefix}.api.sandbox.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 following evidence types 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 |
| --- | --- |
| `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 customer 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 cancelation 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
previous 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](https://www.checkout.com/docs/business-operations/manage-disputes/how-disputes-work.md#Arbitration). |
| `arbitration_no_review`
`optional`
`string` | The evidence to submit directly to the scheme when you escalate the dispute to arbitration.
Only applies to [arbitrations](https://www.checkout.com/docs/business-operations/manage-disputes/how-disputes-work.md#Arbitration). |
### Request example
**Dispute JSON**
```json
{
"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 customer",
"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 product was delivered on 2024-12-20"
}
```
**Dispute Node.js (Beta)**
```js
import { Checkout } from 'checkout-node-sdk';
const cko = new Checkout('sk_XXXX');
const evidence = await cko.disputes.provideEvidence('dsp_bc94ebda8d275i461229', {
proof_of_delivery_or_service_text: 'http://checkout.com/document.pdf',
});
```
**Arbitration JSON**
```json
{
"arbitration_no_review_text" : "Description of files",
"arbitration_no_review_files" : ["file_jmbfgkjromvcrn9t4qu1", "file_jmbfgkjromvcrn9t4qu2"],
"arbitration_review_required_text" : "Description of files",
"arbitration_review_required_files" : ["file_jmbfgkjromvcrn9t4qu3", "file_jmbfgkjromvcrn9t4qu4"]
}
```
### 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 following error codes 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 API specification, see the [API reference](https://api-reference.checkout.com/).
> **Information**
>
> Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md).
**Production**
`GET` `https://{prefix}.api.checkout.com/disputes/{dispute_id}/evidence`
**Sandbox**
`GET` `https://sandbox.checkout.com/disputes/{dispute_id}/evidence`
### Request example
**Node.js (Beta)**
```js
import { Checkout } from 'checkout-node-sdk';
const cko = new Checkout('sk_XXXX');
const getEvidence = await cko.disputes.getEvidence('dsp_bc94ebda8d275i461229');
```
### Response example
```json
{
"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": "Product was delivered on 2024-12-30"
}
```
### 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
> **Information**
>
> Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md).
**Production**
`POST` `https://{prefix}.api.checkout.com/disputes/{dispute_id}/evidence`
**Sandbox**
`POST` `https://{prefix}.api.sandbox.checkout.com/disputes/{dispute_id}/evidence`
### Request example
**Node.js (Beta)**
```js
import { Checkout } from 'checkout-node-sdk';
const cko = new Checkout('sk_XXXX');
const submitEvidence = await cko.disputes.submit('dsp_bc94ebda8d275i461229');
```
### 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 following error codes 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
> **Information**
>
> Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md).
**Production**
`POST` `https://{prefix}.api.checkout.com/disputes/{dispute_id}/accept`
**Sandbox**
`POST` `https://{prefix}.api.sandbox.checkout.com/disputes/{dispute_id}/accept`
### Request example
**Node.js (Beta)**
```js
import { Checkout } from 'checkout-node-sdk';
const cko = new Checkout('sk_XXXX');
const accept = await cko.disputes.accept('dsp_bc94ebda8d275i461229');
```
### 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 following error codes 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`