Skip to main content
This guide explains how to create, track, and cancel disputes for card transactions.

​
Create a dispute

Submit a dispute when a cardholder reports an issue with a completed transaction.
For exact request parameters and examples, open the Disputes API reference.
Required fields:
  • cardId — the card or budget card ID
  • transactionId — the ID of the disputed transaction
  • textEvidence — a written description of the dispute reason (minimum 10 characters, maximum 65,535 characters)
Optional fields:
  • files — an array of URLs pointing to supporting evidence (e.g., screenshots, receipts, correspondence)
The dispute is created with an initial status of pending. The response includes the dispute id, which you should store for status tracking.

​
Check dispute status

Your product should show dispute status updates to the cardholder. Possible statuses:
  • pending — the dispute has been submitted and is awaiting review
  • reviewing — the dispute is actively being investigated by the compliance or disputes team
  • accepted — the dispute was resolved in the cardholder’s favor; a refund will be processed
  • rejected — the dispute was reviewed and denied; the original transaction stands
  • cancelled — the dispute was cancelled by the partner before resolution
  • closed — the dispute process is fully completed (after acceptance, rejection, or other final action)
The response can include additional details about the resolution when available.

​
Cancel a dispute

Once cancelled, the dispute cannot be reopened — a new dispute must be created if needed.

​
Best Practices

  • Act quickly. Disputes should be filed as soon as the cardholder reports an issue. Card network rules impose time limits on dispute submissions.
  • Provide detailed evidence. The textEvidence field should clearly describe the reason for the dispute. Include dates, amounts, and what the cardholder expected versus what happened.
  • Attach supporting files. Screenshots, email correspondence with the merchant, or delivery tracking information strengthen the case.
  • Use the correct transaction ID. Make sure you reference the exact transaction being disputed.

​
What happens next

Disputes typically go through a multi-stage lifecycle (review, evidence exchange, outcome). To set expectations for users and support, see:

​
FAQ

Can I dispute any transaction? Disputes can be filed for completed transactions. Pending or declined transactions cannot be disputed. Transactions processed through 3D Secure are not eligible for chargebacks under any circumstances. How long does dispute resolution take? Resolution timelines depend on the card network and the merchant’s response. Typical processing takes up to 90 calendar days. Can I reopen a cancelled dispute? No. If a dispute was cancelled in error, you must create a new dispute for the same transaction. Will the cardholder receive a refund automatically? Not immediately. If the dispute is resolved in the cardholder’s favor, the refund is processed according to the card network’s procedures.