Manage Issuing disputes

Last updated: January 21, 2026

If your cardholder notices an unfamiliar transaction on a card you've issued and questions its validity, you can raise a dispute to reclaim the funds from the merchant. For example, when there are concerns about fraud, or the quality or delivery of a purchase.

For acquiring disputes, see Process disputes.

Note

You can raise and manage disputes using the Issuing Disputes API if:

You're a certified issuer with card schemes.
The dispute reason is not fraud.

Otherwise, contact Checkout.com to raise and manage disputes using the Cardholder Dispute Form.

Disputes go through four standard stages in their lifecycle to reach resolution:

Chargeback:
- You raise a dispute with the card scheme and request a chargeback from the merchant. The funds are returned to the cardholder.
- If the merchant accepts or does not respond to the chargeback, you win the dispute.
Representment:
- If the merchant rejects the chargeback, they can provide evidence and send a representment. The funds are reversed to the merchant.
- If you accept or do not respond to the representment, the merchant wins the dispute.
Pre-arbitration:
- If you reject the representment, you can escalate the dispute to pre-arbitration and provide more evidence.
- If the merchant accepts or does not respond to pre-arbitration, you win the dispute and the funds are returned to the cardholder.
Arbitration:
- If the merchant rejects pre-arbitration, you can escalate to arbitration from the card scheme.
- The scheme's decision is final and the funds go to the winning party.

Set up an authentication mechanism for your API requests, using OAuth 2.0 or API keys.
Prepare to handle the Issuing dispute statuses.
Configure your webhook server and subscribe to Issuing dispute webhooks.

Check that the transaction is eligible for dispute.
You can:
- Create and submit a dispute to the card scheme simultaneously.
- Create a dispute and then submit it separately later.
- Cancel the dispute before submission or during processing if you decide not to proceed.
Monitor the dispute and consider the merchant's response. You can optionally:
- Retrieve the report.
- Retrieve the dispute details.
- Download evidence files.
Escalate to pre-arbitration if you reject the merchant's representment.
Escalate to arbitration if the merchant rejects pre-arbitration.

Before you raise a dispute, check that the transaction is eligible. You cannot dispute an ineligible transaction.

Ensure that the cardholder has tried all other ways of resolving the issue with the merchant directly.
For example, by trying to return any products they received, cancel ongoing services, or seek a refund.
Collect documentation of these attempts as evidence for the dispute.
Confirm that the transaction status is cleared and not already refunded.
Ensure you are within the card scheme's chargeback time limit, which can be 30 to 120 days after the billing date, depending on the dispute reason code you provide.

Card schemes apply time limits to each stage of the dispute lifecycle:

Dispute stage	Time limit
You raise a dispute	Within 30, 90, or 120 days after the transaction Central Site Business Date (CSBD), depending on the dispute reason code
Merchant responds to the dispute or sends representment	Within 45 calendar days after the chargeback date, or you win the dispute
You escalate to pre-arbitration	Within 30 calendar days after the representment date, or the merchant wins the dispute Checkout.com recommends within 10–15 calendar days.
Merchant responds to pre-arbitration	Within 30 calendar days after the representment date, or you win the dispute
You escalate to arbitration	Within 15 calendar days after the merchant rejects pre-arbitration, or the merchant wins the dispute Checkout.com recommends within 2–4 calendar days.

You can raise a dispute for only part of the original transaction amount. For example, if part of the transaction is not disputed or has already been refunded.

Dispute outcomes can also be partial. Following pre-arbitration or arbitration, you may win only part of the disputed amount back.

Call the Create an issuing dispute endpoint and provide the following:

Cko-Idempotency-Key header – Your idempotency key so you can safely retry this request without creating duplicate disputes.
transaction_id field – The unique identifier for the disputed transaction, prefixed with trx_.
reason field – If Checkout.com is your issuing processor, a four-digit scheme-specific reason code.

Optionally, you can provide:

evidence object – Your evidence for the dispute, according to the card scheme's requirements.
amount field – The chargeback amount (if lower than the cleared transaction amount), in the transaction currency's minor unit.
presentment_message_id field – The unique identifier for the disputed presentment from the Presentment received webhook (if the transaction has multiple presentments).
justification field – Your justification for the chargeback.
is_ready_for_submission boolean – To create the dispute and submit it:
- Simultaneously – Set to true.
- Later – Set to false.

Providing evidence is optional, but it may improve your chances of winning the dispute.
Upload a single evidence file or a single ZIP file containing multiple evidence files.

Documents and images must meet the following requirements:

File name – Maximum 16 alphanumeric English characters, with no spaces or special characters
File format – JPEG, TIFF, or PDF
File size – Maximum 14.5MB or 14,500,000 Bytes and maximum 19 pages
File resolution – Maximum 300 X 300 DPI
Pixel count – Maximum 30,000,000 pixels
Minimal graphics and color

Information

Your base URL [prefix] is unique. To learn how to retrieve your unique base URLs for the sandbox and production environments, see API endpoints.

post

https://[prefix].api.checkout.com/issuing/disputes


1{
2  "transaction_id": "trx_aayhhfwbdyxwcaeyhhfwbd4xga",
3  "reason": "4855",
4  "evidence": [
5    {
6      "name": "evidence.pdf",
7      "content": "string",
8      "description": "Goods were not received."
9    }
10  ],
11  "amount": 100,
12  "presentment_message_id": "msg_fa6psq242dcd6fdn5gifcq1491",
13  "justification": "string",
14  "is_ready_for_submission": false
15}


1{
2  "id": "idsp_fa6psq242dcd6fdn5gifcq1491",
3  "reason": "4855",
4  "disputed_amount": {
5    "amount": 100,
6    "currency": "USD"
7  },
8  "status": "created",
9  "status_reason": "chargeback_processed",
10  "transaction_id": "trx_aayhhfwbdyxwcaeyhhfwbd4xga",
11  "presentment_message_id": "msg_fa6psq242dcd6fdn5gifcq1491",
12  "merchant": {
13    "id": "(*)123456789",
14    "name": "Software Company",
15    "city": "London",
16    "state": "",
17    "country_code": "UK",
18    "category_code": 5734,
19    "evidence": [
20      "file_6lbss42ezvoufcb2beo76rvwly"
21    ]
22  },
23  "created_on": null,
24  "modified_on": null,
25  "chargeback": {
26    "submitted_on": "2019-09-10T10:11:12Z",
27    "reason": "4855",
28    "amount": {
29      "amount": 100,
30      "currency": "USD"
31    },
32    "evidence": [
33      {
34        "file_id": "file_6lbss42ezvoufcb2beo76rvwly",
35        "description": "Goods were not received."
36      }
37    ],
38    "justification": "string"
39  },
40  "second_presentment": {
41    "received_on": null,
42    "evidence": [
43      {
44        "file_id": "file_6lbss42ezvoufcb2beo76rvwly",
45        "description": "Goods were not received."
46      }
47    ]
48  },
49  "pre_arbitration": {
50    "submitted_on": "2019-09-10T10:11:12Z",
51    "evidence": [
52      {
53        "file_id": "file_6lbss42ezvoufcb2beo76rvwly",
54        "description": "Goods were not received."
55      }
56    ],
57    "amount": {
58      "amount": 100,
59      "currency": "USD"
60    },
61    "justification": "string",
62    "merchant_responded_on": null,
63    "merchant_evidence": [
64      {
65        "file_id": "file_6lbss42ezvoufcb2beo76rvwly",
66        "description": "Goods were not received."
67      }
68    ]
69  },
70  "arbitration": {
71    "submitted_on": "2019-09-10T10:11:12Z",
72    "amount": {
73      "amount": 100,
74      "currency": "USD"
75    },
76    "justification": "string",
77    "decided_on": "string"
78  },
79  "_links": {
80    "self": {
81      "href": "string",
82      "actions": [],
83      "types": []
84    },
85    "card": {
86      "href": "string",
87      "actions": [],
88      "types": []
89    },
90    "cardholder": {
91      "href": "string",
92      "actions": [],
93      "types": []
94    },
95    "transaction": {
96      "href": "string",
97      "actions": [],
98      "types": []
99    },
100    "submit": {
101      "href": "string",
102      "actions": [],
103      "types": []
104    },
105    "escalate": {
106      "href": "string",
107      "actions": [],
108      "types": []
109    }
110  }
111}

If successful, you receive a 201 response code. The response returns:

The dispute ID in the id field, prefixed with idsp_
The dispute status and status_reason – See Chargeback statuses.
Information about the transaction and the merchant
Placeholder objects for each stage in the dispute lifecycle

If you do not receive a response, retry the request with the same idempotency key. If the original request exists and was already processed, you receive a 200 response code. The response payload is the same as the initial request's response. This indicates that the request is a retry, not a new dispute. If the dispute was already successfully created, you receive a 200 response code with the same payload as the initial response.

Note

If the transaction is ineligible for dispute, you receive a 422 error response code.
If you receive a presentment_reversed status reason, the scheme rejected the dispute because the funds were already reversed. Do not re-submit the dispute.

After creating a dispute, call the Submit an issuing dispute endpoint, and provide the following:

{disputeId} path parameter – The dispute ID.
Cko-Idempotency-Key header – Your idempotency key.

Optionally, you can update the reason or disputed amount fields, and the evidence object following the card scheme's requirements.

Note

After submitting the dispute, you cannot change your evidence files or add more files.

Information

Your base URL [prefix] is unique. To learn how to retrieve your unique base URLs for the sandbox and production environments, see API endpoints.

post

https://[prefix].api.checkout.com/issuing/disputes/{disputeId}/submit


1{
2  "reason": "4855",
3  "evidence": [
4    {
5      "name": "evidence.pdf",
6      "content": "string",
7      "description": "Goods were not received."
8    }
9  ],
10  "amount": 80
11}


1{
2  "id": "idsp_fa6psq242dcd6fdn5gifcq1491",
3  "reason": "4855",
4  "disputed_amount": {
5    "amount": 80,
6    "currency": "USD"
7  },
8  "status": "created",
9  "status_reason": "chargeback_processed",
10  "transaction_id": "trx_aayhhfwbdyxwcaeyhhfwbd4xga",
11  "presentment_message_id": "msg_fa6psq242dcd6fdn5gifcq1491",
12  "merchant": {
13    "id": "(*)123456789",
14    "name": "Software Company",
15    "city": "London",
16    "state": "",
17    "country_code": "UK",
18    "category_code": 5734,
19    "evidence": [
20      "file_6lbss42ezvoufcb2beo76rvwly"
21    ]
22  },
23  "created_on": null,
24  "modified_on": null,
25  "chargeback": {
26    "submitted_on": "2019-09-10T10:11:12Z",
27    "reason": "4855",
28    "amount": {
29      "amount": 100,
30      "currency": "USD"
31    },
32    "evidence": [
33      {
34        "file_id": "file_6lbss42ezvoufcb2beo76rvwly",
35        "description": "Goods were not received."
36      }
37    ],
38    "justification": "string"
39  },
40  "second_presentment": {
41    "received_on": null,
42    "evidence": [
43      {
44        "file_id": "file_6lbss42ezvoufcb2beo76rvwly",
45        "description": "Goods were not received."
46      }
47    ]
48  },
49  "pre_arbitration": {
50    "submitted_on": "2019-09-10T10:11:12Z",
51    "evidence": [
52      {
53        "file_id": "file_6lbss42ezvoufcb2beo76rvwly",
54        "description": "Goods were not received."
55      }
56    ],
57    "amount": {
58      "amount": 100,
59      "currency": "USD"
60    },
61    "justification": "string",
62    "merchant_responded_on": null,
63    "merchant_evidence": [
64      {
65        "file_id": "file_6lbss42ezvoufcb2beo76rvwly",
66        "description": "Goods were not received."
67      }
68    ]
69  },
70  "arbitration": {
71    "submitted_on": "2019-09-10T10:11:12Z",
72    "amount": {
73      "amount": 100,
74      "currency": "USD"
75    },
76    "justification": "string",
77    "decided_on": "string"
78  },
79  "_links": {
80    "self": {
81      "href": "string",
82      "actions": [],
83      "types": []
84    },
85    "card": {
86      "href": "string",
87      "actions": [],
88      "types": []
89    },
90    "cardholder": {
91      "href": "string",
92      "actions": [],
93      "types": []
94    },
95    "transaction": {
96      "href": "string",
97      "actions": [],
98      "types": []
99    },
100    "submit": {
101      "href": "string",
102      "actions": [],
103      "types": []
104    },
105    "escalate": {
106      "href": "string",
107      "actions": [],
108      "types": []
109    }
110  }
111}

The response returns the status and status_reason. See Chargeback statuses.

Note

If you receive a presentment_reversed status reason, the scheme rejected the dispute because the funds were already reversed. Do not re-submit the dispute.

You can receive the following webhooks:

Issuing chargeback processed – The scheme has processed the chargeback.
Issuing representment received – The merchant rejected the chargeback and sent a representment.

You many need to resubmit a dispute using the Submit an issuing dispute endpoint in the following scenarios:

The scheme rejects the evidence or justification you provided for the dispute, after creation or after submission.
You accidentally provided incorrect evidence or justification when creating or submitting the dispute. For example, you specified the wrong evidence file.
You want to reactivate a canceled dispute.

You can specify a different amount or reason.

If the dispute status is:

action_required – Submit the dispute again and provide your updated evidence or justification.
created or processing – Cancel the dispute, and then resubmit it with the updated information.

Note

Resubmitting a dispute does not escalate it to pre-arbitration or arbitration.

If you decide not to proceed with a dispute, you can cancel it either:

Before you submit it
While the dispute status is processing and status_reason is chargeback_pending or chargeback_processed

Call the Cancel an issuing dispute endpoint, and provide the dispute ID as the {disputeId} path parameter.

Information

Your base URL [prefix] is unique. To learn how to retrieve your unique base URLs for the sandbox and production environments, see API endpoints.

post

https://[prefix].api.checkout.com/issuing/disputes/{disputeId}/cancel

If the dispute:

Can no longer be canceled – You receive a 409 error response code.
Is successfully canceled – You receive a 202 response code. The dispute status is canceled and the status_reason is chargeback_reversed.

Note

To reactivate a canceled dispute, you need to re-submit it with the same dispute ID, using the Submit an issuing dispute endpoint. Do not create a new dispute for the same presentment if a dispute was previously canceled.

You can monitor the progress of the dispute in the following ways:

Retrieve the Dispute Lifecycle Report.
Retrieve the dispute details using the API.
Download evidence files.

This report helps you monitor events during the lifecycle of all disputes on your cards during a selected timeframe. It includes transaction amounts and currencies, dispute reasons, and your justifications.

For full details and how to retrieve the report, see Dispute Lifecycle Report.

To retrieve the details of a dispute, call the Get an issuing dispute endpoint, and provide the dispute ID as the {disputeId} path parameter.

Information

Your base URL [prefix] is unique. To learn how to retrieve your unique base URLs for the sandbox and production environments, see API endpoints.

get

https://[prefix].api.checkout.com/issuing/disputes/{disputeId}


1{
2  "id": "idsp_fa6psq242dcd6fdn5gifcq1491",
3  "reason": "4855",
4  "disputed_amount": {
5    "amount": 80,
6    "currency": "USD"
7  },
8  "status": "created",
9  "status_reason": "chargeback_processed",
10  "transaction_id": "trx_aayhhfwbdyxwcaeyhhfwbd4xga",
11  "presentment_message_id": "msg_fa6psq242dcd6fdn5gifcq1491",
12  "merchant": {
13    "id": "(*)123456789",
14    "name": "My Merchant",
15    "city": "Paris",
16    "state": "",
17    "country_code": "FR",
18    "category_code": 5331,
19    "evidence": [
20      "file_6lbss42ezvoufcb2beo76rvwly"
21    ]
22  },
23  "created_on": null,
24  "modified_on": null,
25  "chargeback": {
26    "submitted_on": "2019-09-10T10:11:12Z",
27    "reason": "4855",
28    "amount": {
29      "amount": 100,
30      "currency": "USD"
31    },
32    "evidence": [
33      {
34        "file_id": "file_6lbss42ezvoufcb2beo76rvwly",
35        "description": "Goods were not received."
36      }
37    ],
38    "justification": "string"
39  },
40  "second_presentment": {
41    "received_on": null,
42    "evidence": [
43      {
44        "file_id": "file_6lbss42ezvoufcb2beo76rvwly",
45        "description": "Goods were not received."
46      }
47    ]
48  },
49  "pre_arbitration": {
50    "submitted_on": "2019-09-10T10:11:12Z",
51    "evidence": [
52      {
53        "file_id": "file_6lbss42ezvoufcb2beo76rvwly",
54        "description": "Goods were not received."
55      }
56    ],
57    "amount": {
58      "amount": 80,
59      "currency": "USD"
60    },
61    "justification": "string",
62    "merchant_responded_on": null,
63    "merchant_evidence": [
64      {
65        "file_id": "file_6lbss42ezvoufcb2beo76rvwly",
66        "description": "Goods were not received."
67      }
68    ]
69  },
70  "arbitration": {
71    "submitted_on": "2019-09-10T10:11:12Z",
72    "amount": {
73      "amount": 100,
74      "currency": "USD"
75    },
76    "justification": "string",
77    "decided_on": "string"
78  },
79  "_links": {
80    "self": {
81      "href": "string",
82      "actions": [],
83      "types": []
84    },
85    "card": {
86      "href": "string",
87      "actions": [],
88      "types": []
89    },
90    "cardholder": {
91      "href": "string",
92      "actions": [],
93      "types": []
94    },
95    "transaction": {
96      "href": "string",
97      "actions": [],
98      "types": []
99    },
100    "submit": {
101      "href": "string",
102      "actions": [],
103      "types": []
104    },
105    "escalate": {
106      "href": "string",
107      "actions": [],
108      "types": []
109    }
110  }
111}

The response returns the full details of the dispute.

If you or the merchant have uploaded evidence, you can download the files using the file ID from the evidence object in the relevant stage, prefixed with file_.

To download an evidence file that you or the merchant uploaded, you need the file_id from the evidence object in the relevant stage of the Get an issuing dispute response.

Call the Get file information endpoint, and provide the file ID as the {file_id} path parameter.

Information

Your base URL [prefix] is unique. To learn how to retrieve your unique base URLs for the sandbox and production environments, see API endpoints.

get

https://[prefix].api.checkout.com/files/{file_id}


1{
2  "id": "file_6lbss42ezvoufcb2beo76rvwly",
3  "filename": "receipt.png",
4  "purpose": "dispute_evidence",
5  "size": 1024,
6  "uploaded_on": "2016-05-17T16:48:52.000Z",
7  "_links": {
8    "self": {
9      "href": "https://[prefix].api.sandbox.checkout.com/files/file_6lbss42ezvoufcb2beo76rvwly"
10    },
11    "download": {
12      "href": "https://checkout-file-upload.s3.eu-west-2.amazonaws.com/ucdac/ucdac/6lbss42ezvoufcb2beo76rvwly?X-Amz-Expires=3600&x-amz-security-token=FQoDYXdzENL%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEa"
13    }
14  }
15}

The response returns the file details and a temporary download URL where you can download the file.

If you reject the merchant's representment, escalate the dispute to pre-arbitration within 45 calendar days after the representment date or you lose the dispute.

Call the Escalate an issuing dispute endpoint, and provide the following:

{disputeId} path parameter – The dispute ID.
Cko-Idempotency-Key header – Your idempotency key.
justification field – Your justification for escalating to pre-arbitration.

Optionally, you can update the following:

additional_evidence – Provide additional evidence following the card scheme's requirements.
reason_change – If the reason for pre-arbitration is different to the chargeback reason, provide the new reason and your justification for the change.
amount – The disputed amount is in the representment currency because the acquirer may reject the chargeback in a different currency to the chargeback currency. You can retrieve the amount in the representment currency in the Dispute Lifecycle Report, or by calling the Get an issuing dispute endpoint.

Note

This is your last opportunity to submit evidence for the dispute. However, if the dispute proceeds to arbitration, any evidence you upload with this request is ignored.
You cannot cancel a pre-arbitration.

Information

Your base URL [prefix] is unique. To learn how to retrieve your unique base URLs for the sandbox and production environments, see API endpoints.

post

https://[prefix].api.checkout.com/issuing/disputes/{disputeId}/escalate


1{
2  "additional_evidence": [
3    {
4      "name": "evidence.pdf",
5      "content": "string",
6      "description": "Goods were not received."
7    }
8  ],
9  "amount": 80,
10  "justification": "Your justification for escalating to pre-arbitration.",
11  "reason_change": {
12    "reason": "4863",
13    "justification": "Your justification for changing the dispute reason."
14  }
15}

If successful, Checkout.com sends the pre-arbitration to the card scheme for processing.

Check the status and status_reason using the API or the Dispute Lifecycle Report. See Pre-arbitration statuses.

When the scheme processes the pre-arbitration, you receive an Issuing pre-arbitration processed webhook.

If the merchant rejects pre-arbitration, review their evidence. You can then choose to escalate to arbitration from the card scheme. The scheme's decision is final and the funds go to the winning party.

Your time limit for submitting your request is within 75 days after the representment date, except for dispute reason codes 4808 and 4834 for which the limit is 45 days.

Note

Arbitrations can take a long time to resolve. The cost of arbitration can range from 500–1,000 USD and is debited from the losing party. This may be greater than the disputed amount.
You cannot cancel an arbitration.
The card scheme ignores any additional_evidence you upload at this stage.

Call the Escalate an issuing dispute endpoint, and provide the following:

{disputeId} path parameter – The dispute ID,
justification field – Your justification for escalating to arbitration.

Optionally, you can update the disputed amount.

Information

Your base URL [prefix] is unique. To learn how to retrieve your unique base URLs for the sandbox and production environments, see API endpoints.

post

https://[prefix].api.checkout.com/issuing/disputes/{disputeId}/escalate


1{
2  "amount": 100,
3  "justification": "Your justification for escalating to arbitration."
4}

If successful, Checkout.com sends the arbitration to the card scheme for processing.

Check the status and status_reason using the API or the Dispute Lifecycle Report. See Arbitration statuses.

Note

Dispute lifecycle

Before you begin

How it works

Dispute eligibility

Dispute time limits

Partial disputes

Create a dispute

Evidence file requirements

Information

Request example

Response example

Note

Submit the dispute

Note

Information

Request example

Response example

Note

Resubmit a dispute

Note

Cancel a dispute

Information

Response

Note

Monitor the dispute

Dispute Lifecycle Report

Retrieve dispute details

Information

Response example

Download evidence files

Information

Response example

Escalate to pre-arbitration

Note

Information

Request example

Escalate to arbitration

Note

Information

Request example