> ## 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.

# FAQ

> Short answers to the questions that come up during a disputes integration

Short answers to common questions, each with a link to the page that holds the full detail.

> [accordion] Can I dispute a transaction that has not cleared?
>
> No. Only a `CLEARED` transaction can be disputed, because the money has already moved. `PENDING` and `VOID` transactions cannot be disputed, and neither can a standalone refund. [File a Dispute](https://docs.reap.global/cards/disputes/file-a-dispute.md#before-you-start) lists every requirement.

> [accordion] How long do I have to file?
>
> The window runs from the day the transaction first cleared and is the same for every reason. [File a Dispute](https://docs.reap.global/cards/disputes/file-a-dispute.md#before-you-start) states the number of days and the earlier date to aim for. Past the window, [`POST /disputes`](https://docs.reap.global/api-reference/disputes/file-dispute) returns `CARD_DISPUTE_FILING_WINDOW_EXPIRED`.

> [accordion] Can I dispute part of a charge?
>
> Yes. Send `amount` to dispute part of the charge, up to the cleared cardholder amount net of refunds. A partly refunded transaction can still be disputed for the remainder. Omit `amount` to dispute the full cleared cardholder amount.

> [accordion] Can I file a second dispute on the same transaction?
>
> Only when the earlier dispute reached `CANCELED` or `DECLINED`, which means it never reached the card network. While a dispute is live, a second one returns `CARD_DISPUTE_ALREADY_EXISTS`.

> [accordion] Do I need a fraud alert before I file a dispute?
>
> No. Disputes and fraud alerts are independent. Neither requires the other, and you can file both against the same transaction. [Disputes and fraud alerts](https://docs.reap.global/cards/disputes/overview.md#disputes-and-fraud-alerts) explains what each one does.

> [accordion] Should I poll for the outcome?
>
> No. Subscribe to [`CARD_DISPUTE_STATUS_UPDATED`](https://docs.reap.global/api-reference/card-dispute-status-updated), which you receive on every status change through to resolution. A dispute can take weeks to resolve, so treat the webhook as the source of truth. [`GET /disputes/:id`](https://docs.reap.global/api-reference/disputes/get-dispute) returns the current dispute whenever you need it.

> [accordion] What happens if my request to file a dispute times out?
>
> Retry [`POST /disputes`](https://docs.reap.global/api-reference/disputes/file-dispute) with the same `Idempotency-Key`. Reap replays the original response, so the timeout does not turn into an error on the retry. A retry without the key returns `CARD_DISPUTE_ALREADY_EXISTS` when the first request already succeeded.

> [accordion] What is the difference between DECLINED and LOST?
>
> `DECLINED` means Reap did not file the dispute, so it never reached the card network. `LOST` means it was filed and the card network ruled for the merchant. [Lifecycle and Statuses](https://docs.reap.global/cards/disputes/lifecycle.md#statuses) covers every value.

> [accordion] Why is refundedAmount less than the amount I filed?
>
> The credit includes a proportional share of the FX markup and the ATM variable fee, but the per-withdrawal ATM fee stays charged, the same way a merchant refund leaves it charged. [How a refund is calculated](https://docs.reap.global/cards/disputes/lifecycle.md#how-a-refund-is-calculated) walks through an example.

> [accordion] I keep the cardholder balance myself. Where do I take the credit from?
>
> From the `DISPUTE_REFUND` event on the transaction, the same way you apply a merchant `REFUND`. Do not also credit from the dispute webhook, or the refund is booked twice. [How a refund is calculated](https://docs.reap.global/cards/disputes/lifecycle.md#how-a-refund-is-calculated) covers the credit and the event.

## Next steps

> [card] [File a Dispute](https://docs.reap.global/cards/disputes/file-a-dispute.md)
>
> Check the requirements, file the dispute, and track it to resolution.

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


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