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

# Lifecycle and Statuses

> What each status means, what to do about it, and how the refund is calculated

Every dispute reports a `status`. This page maps each value to the action it calls for and explains what the cardholder is credited when a dispute reaches `REFUNDED`.

## Statuses

```mermaid theme={null}
stateDiagram-v2
    [*] --> RECEIVED: file dispute
    RECEIVED --> REVIEWING: review before filing
    RECEIVED --> SUBMITTED: filed with the card network
    REVIEWING --> SUBMITTED: filed with the card network
    RECEIVED --> DECLINED: not filed
    REVIEWING --> DECLINED: not filed
    RECEIVED --> CANCELED: withdrawn
    REVIEWING --> CANCELED: withdrawn
    SUBMITTED --> CANCELED: withdrawn
    SUBMITTED --> WON: the card network rules for the cardholder
    SUBMITTED --> LOST: the card network rules for the merchant
    SUBMITTED --> REFUNDED: the cardholder is credited
    WON --> REFUNDED: the cardholder is credited
    LOST --> [*]
    REFUNDED --> [*]
    DECLINED --> [*]
    CANCELED --> [*]
```

| Status | What it means | What to do |
| - | - | - |
| `RECEIVED` | Recorded and queued for review | Wait for the next `CARD_DISPUTE_STATUS_UPDATED` |
| `REVIEWING` | Under review before it goes to the card network | Wait for the next `CARD_DISPUTE_STATUS_UPDATED` |
| `SUBMITTED` | Filed with the card network and waiting on its ruling | Wait for the ruling, which can take weeks |
| `WON` | The card network ruled for the cardholder | Wait for `REFUNDED`, which carries the credit |
| `LOST` | The dispute was filed and the card network ruled for the merchant | Nothing. No credit follows, and the transaction cannot be disputed again |
| `REFUNDED` | The cardholder was credited. `refundedAmount` is that credit, and the disputed transaction carries it as a `DISPUTE_REFUND` event | Read `refundedAmount`, which may be less than `amount`. If you keep the cardholder balance, apply the `DISPUTE_REFUND` event on the transaction |
| `DECLINED` | Reap did not file the dispute with the card network | You can file a new dispute on the same transaction |
| `CANCELED` | The dispute was withdrawn before resolution | You can file a new dispute on the same transaction |

A dispute can be canceled from `RECEIVED`, `REVIEWING`, or `SUBMITTED`, and declined from `RECEIVED` or `REVIEWING`. `resolvedAt` is set when the dispute is resolved, which is any of `WON`, `LOST`, `REFUNDED`, `DECLINED`, or `CANCELED`. `WON` is resolved even though `REFUNDED` follows it, so a set `resolvedAt` does not mean the last status change has arrived.

`DECLINED` and `LOST` are often confused. `DECLINED` means the dispute never reached the card network. `LOST` means it was filed and the card network ruled for the merchant.

## How a refund is calculated

The cardholder is credited `refundedAmount` when the dispute reaches `REFUNDED`, not the disputed `amount`. The disputed amount is the cardholder amount, which is the charge plus [FX markup and ATM fees](https://docs.reap.global/transactions/fees.md). Omit `amount` on [`POST /disputes`](https://docs.reap.global/api-reference/disputes/file-dispute) to dispute the full cleared total, as [File a Dispute](https://docs.reap.global/cards/disputes/file-a-dispute.md#before-you-start) describes.

`refundedAmount` stays `null` until then. Read it from the dispute resource or from [`CARD_DISPUTE_STATUS_UPDATED`](https://docs.reap.global/api-reference/card-dispute-status-updated). The same credit is appended to the disputed transaction as a [`DISPUTE_REFUND` event](https://docs.reap.global/transactions/lifecycle#dispute-refund) and delivered in `CARD_TRANSACTION_UPDATED`. The `amount.refunded` and `amount.current` values on the transaction reflect it.

The credit includes a proportional share of the FX markup and the ATM variable fee. The per-withdrawal ATM fee stays charged, the same way a merchant refund leaves it charged.

Consider a USD 105 ATM withdrawal made up of a USD 100 purchase, USD 1 FX markup, USD 1 ATM variable fee, and a USD 3 per-withdrawal fee.

* A full dispute files USD 105. A full refund credits USD 102, and the USD 3 stays charged
* A half dispute files USD 52.50. A matching refund credits USD 51

### Read the credit

Once the cardholder is credited, [`GET /disputes/:id`](https://docs.reap.global/api-reference/disputes/get-dispute) returns the dispute with `status` set to `REFUNDED`, and [`CARD_DISPUTE_STATUS_UPDATED`](https://docs.reap.global/api-reference/card-dispute-status-updated) delivers the same resource in `data` when the status changes. For the full dispute of that withdrawal, `refundedAmount` holds USD 102 against the USD 105 filed, because the USD 3 per-withdrawal fee stays charged, and `resolvedAt` is set because the dispute is resolved. The reference page shows the full response.

> [!WARNING]
>
> If you keep the cardholder balance yourself, as you do under [External authorization](https://docs.reap.global/transactions/external-authorization/overview.md), apply the credit 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. [Keeping your ledger in sync](https://docs.reap.global/transactions/external-authorization/reconciliation.md#credit-a-dispute-refund) covers the full sequence.

## 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] [FAQ](https://docs.reap.global/cards/disputes/faq.md)
>
> Short answers to common integration questions.


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