> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reap.global/llms.txt
> Use this file to discover all available pages before exploring further.

# File a Dispute

> Check the requirements, file the dispute, and track it to resolution

This page files one dispute end to end. You start with a cleared transaction and the reason the cardholder gives you, and finish with a dispute that Reap takes to the card network and reports on until it is resolved.

## Before you start

* The transaction has status `CLEARED`, which means the money has moved. `PENDING` and `VOID` transactions cannot be disputed, and neither can a standalone refund, which pays the cardholder rather than charging them. The [transaction lifecycle](https://docs.reap.global/transactions/lifecycle.md) covers each status
* The transaction first cleared within the last 120 days. The filing window is the same for every reason
* The amount you dispute is at most the cleared cardholder amount, net of refunds. The cardholder amount is the charge plus FX markup and ATM fees. When you omit `amount`, the full cleared cardholder amount is disputed. A partly refunded transaction can still be disputed for the remainder
* No live dispute exists on the transaction. You can file again only when the earlier dispute reached `CANCELED` or `DECLINED`, which means it never reached the card network
* A reason that matches what the cardholder is telling you. [Dispute Reasons](https://docs.reap.global/cards/disputes/reasons.md) lists every value by category

> [!WARNING]
>
> File within 75 days of clearing where you can. Reap files a later dispute on a best-effort basis, and the card network may still refuse it.

Every request takes an `Authorization` header with your API key as a bearer token and a `Reap-Version` header.

## File and track the dispute

**1. Collect the reason from the cardholder**

Pick the [dispute reason](https://docs.reap.global/cards/disputes/reasons.md) that matches what the cardholder is telling you. The reason drives how the card network handles the dispute, so show it as a clear choice in your UI rather than guessing.

**2. File the dispute**

Call [`POST /disputes`](https://docs.reap.global/api-reference/disputes/file-dispute) with `transactionId` and `reason`. Everything else is derived from the transaction, including the card, the cardholder identity, and the currency. An `Idempotency-Key` is required. A retry with the same key replays the original response, so a network timeout on your side does not turn into an error on the retry. Without it, a retry of a request that already succeeded returns `CARD_DISPUTE_ALREADY_EXISTS`.

The dispute is created as `RECEIVED` and Reap handles it from that point. Keep the dispute `id`. In the response, `amount` is the full cleared cardholder amount when the request omits it, `category` is derived from the reason, and the `cardholder` block carries the identity Reap derived from the transaction. `refundedAmount` and `resolvedAt` stay `null` while the dispute is open. The [`POST /disputes`](https://docs.reap.global/api-reference/disputes/file-dispute) reference shows the full request and response.

Send `amount` as a number in the billing currency to dispute part of the charge. Send `contactEmail` to route the outcome somewhere other than the cardholder email on file. The response echoes it in `cardholder.contactEmail`.

**3. Track the outcome**

Subscribe to [`CARD_DISPUTE_STATUS_UPDATED`](https://docs.reap.global/api-reference/card-dispute-status-updated). You receive it on every status change through to resolution, and `data` carries the dispute in the same shape as the `POST /disputes` response. The event reference shows the full payload.

Return any 2xx status to acknowledge the event, and use the event `id` to skip a delivery you have already processed. A dispute can take weeks to resolve, so treat the webhook as the source of truth rather than polling. [`GET /disputes/:id`](https://docs.reap.global/api-reference/disputes/get-dispute) returns the current dispute whenever you need it, and [Lifecycle and Statuses](https://docs.reap.global/cards/disputes/lifecycle.md) maps each status to the action it calls for.

## List disputes

List the disputes in your project with [`GET /disputes`](https://docs.reap.global/api-reference/disputes/list-disputes), newest first. The reference page shows the request and the response. Filter by `status`, `reason`, `category`, `cardId`, or `transactionId`, or by the time the dispute was filed with `filedFrom` and `filedTo`.

Follow `nextCursor` when it holds a value. A `null` cursor means the last page.

## Errors

| Error | What happened | What to do |
| - | - | - |
| `CARD_DISPUTE_TRANSACTION_NOT_FOUND` | `transactionId` does not match a card transaction in your project | Check the transaction ID |
| `CARD_DISPUTE_TRANSACTION_NOT_CLEARED` | The transaction is `PENDING`, `VOID`, or a standalone refund | Dispute only a `CLEARED` transaction |
| `CARD_DISPUTE_FILING_WINDOW_EXPIRED` | The [filing window](#before-you-start) has passed | The transaction can no longer be disputed |
| `CARD_DISPUTE_AMOUNT_INVALID` | `amount` is above the cleared cardholder amount net of refunds | Lower `amount`, or omit it to dispute the full remaining amount |
| `CARD_DISPUTE_ALREADY_EXISTS` | A live dispute already exists on the transaction, or a retry without an `Idempotency-Key` repeated a request that already succeeded | Track the existing dispute. File again only once it reaches `CANCELED` or `DECLINED` |

## Next steps

> [card] [Dispute Reasons](https://docs.reap.global/cards/disputes/reasons.md)
>
> Every reason by category, and how to pick the closest match.

> [card] [Lifecycle and Statuses](https://docs.reap.global/cards/disputes/lifecycle.md)
>
> Every status value, what to do about it, and how the refund is calculated.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.