Manage Issuing disputes
Last updated: March 26, 2025
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.
Information
If you're a certified issuer with card schemes, you can use the Issuing Disputes API set out on this page.
Non-issuers must contact Checkout.com to raise and manage disputes at [email protected].
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.
- Set up your webhook receiver and prepare to handle Issuing dispute webhooks.
- Check that the transaction is eligible for dispute.
- Create a dispute. If you decide not to proceed, you can cancel the dispute.
- Submit the dispute.
- 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
clearedand not alreadyrefunded.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.
Note
If the dispute reason is fraud, you cannot use the Issuing Disputes API.
Contact us to raise and manage the dispute at [email protected].
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 |
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 |
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-Keyheader – Your idempotency key so you can retry this request without creating duplicate disputestransaction_idfield – The unique identifier for the disputed transactionreasonfield – If Checkout.com is your issuing processor, a four-digit scheme-specific reason code
Optionally, you can provide:
evidenceobject – Evidence according to the card scheme's requirementsamountfield – The chargeback amount (if lower than the cleared transaction amount), in the minor unit of the transaction currencypresentment_message_idfield – The unique identifier for the disputed presentment from the Presentment received webhook (if the transaction has multiple presentments)justificationfield – Your justification for the chargebackis_ready_for_submissionboolean – To create the dispute and submit it:- Immediately – Set to
true. - Later – Set to
false.
- Immediately – Set to
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
- Not too many graphics or too much color
post
https://api.checkout.com/issuing/disputes
The response returns:
- The unique identifier for the dispute in the
idfield - The dispute
statusandstatus_reason– See Chargeback statuses. - Information about the transaction and the merchant
- Placeholder objects for each stage in the dispute lifecycle
Note
If the transaction is ineligible for dispute, you receive a 422 error response code.
If you decide not to proceed with a dispute, you can cancel it either before you submit it, or while the status is processing with status_reason: chargeback_pending or chargeback_processed.
Note
You cannot reactivate a canceled dispute. You can create a new dispute if needed.
Call the Cancel an issuing dispute endpoint, and provide:
{disputeId}path parameter – The unique identifier for the dispute – for example,idsp_fa6psq242dcd6fdn5gifcq1491Cko-Idempotency-Keyheader – Your idempotency key
post
https://api.checkout.com/issuing/disputes/{disputeId}/cancel
If the dispute:
- Can no longer be canceled – You receive a
409error response code. - Is successfully canceled – You receive a
202response code and the dispute has"status":"canceled"and"status_reason":"chargeback_reversed".
After creating a dispute, call the Submit an issuing dispute endpoint, and provide the following:
{disputeId}path parameter – The unique identifier for the dispute – for example,idsp_fa6psq242dcd6fdn5gifcq1491Cko-Idempotency-Keyheader – 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.
post
https://api.checkout.com/issuing/disputes/{disputeId}/submit
The response returns the status and status_reason. See Chargeback statuses.
You can receive the following webhooks:
- Issuing chargeback processed – When the scheme processes the chargeback
- Issuing representment received – When you the merchant rejects the chargeback and sends a representment
You can monitor the progress of the dispute in the following ways:
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.
For example, idsp_fa6psq242dcd6fdn5gifcq1491.
get
https://api.checkout.com/issuing/disputes/{disputeId}
The response returns the full details of the dispute.
If you or the merchant have uploaded evidence, you can download the files using the fileId from the evidence object in the relevant stage. For example, file_6lbss42ezvoufcb2beo76rvwly.
To download an evidence file that you or the merchant uploaded, you need the fileId from the evidence object in the relevant stage of the Get an issuing dispute response.
Call the Get file information endpoint, and provide the fileId as the {file_id} path parameter. For example, file_6lbss42ezvoufcb2beo76rvwly.
get
https://api.checkout.com/files/{file_id}
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 unique identifier for the dispute – for example,idsp_fa6psq242dcd6fdn5gifcq1491Cko-Idempotency-Keyheader – Your idempotency key
Optionally, you can update the justification or disputed amount fields, and the additional_evidence object following the card scheme's requirements.
Note
This is your last chance 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.
post
https://api.checkout.com/issuing/disputes/{disputeId}/escalate
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 costs may outweigh the disputed amount and are debited from the losing party.
- You cannot cancel an arbitration.
- The card scheme ignores any
additional_evidenceyou upload at this stage.
Call the Escalate an issuing dispute endpoint, and provide the following:
{disputeId}path parameter – The unique identifier for the dispute – for example,idsp_fa6psq242dcd6fdn5gifcq1491Cko-Idempotency-Keyheader – Your idempotency key
Optionally, you can update the disputed amount or justification fields.
post
https://api.checkout.com/issuing/disputes/{disputeId}/escalate
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.