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

# Dispute lifecycle

export const TxnTag = ({status}) => {
  const getStyles = status => {
    const baseStyle = {
      display: 'inline-block',
      padding: '4px 8px',
      borderRadius: '4px',
      fontSize: '13px',
      fontWeight: '400'
    };
    switch (status) {
      case "PENDING":
        return {
          ...baseStyle,
          backgroundColor: '#ececec',
          color: '#9f9f9f'
        };
      case "AUTHORIZED":
        return {
          ...baseStyle,
          backgroundColor: '#ecfdf5',
          color: '#047857'
        };
      case "SETTLED":
      case "PARTIALLY_SETTLED":
        return {
          ...baseStyle,
          backgroundColor: '#ecfdf5',
          color: '#047857'
        };
      case "DECLINED":
      case "FAILED":
        return {
          ...baseStyle,
          backgroundColor: '#fef2f2',
          color: '#dc2626'
        };
      case "CANCELLED":
        return {
          ...baseStyle,
          backgroundColor: '#fefce8',
          color: '#d78203'
        };
      case "SETTLING":
        return {
          ...baseStyle,
          backgroundColor: '#e0f2fe',
          color: '#0c4a6e'
        };
      default:
        return {
          ...baseStyle,
          backgroundColor: '#f3f4f6',
          color: '#374151'
        };
    }
  };
  return <span style={getStyles(status)}>{status}</span>;
};

<Note>
  Full dispute lifecycle updates are currently available for Adyen, Airwallex, Braintree, Checkout.com and PayPal. For other supported processors - currently Worldline Connect, Worldline Direct, MPGS, Payplug, Reach, Stripe, and Worldpay - you will only receive a Webhook with a `status` of `OPEN` where the `type` is `DISPUTE`.
</Note>

Disputes are created in Primer when they are generated by your payment processor.

All Primer disputes conform to a single dispute lifecycle, which makes them work the same way regardless of the payment services you use.

A dispute always has a dispute `type` (Retrieval, Dispute, and Pre-arbitration), and `status` that depends on the `type`.

Every time the `status` or `type` is updated, a new [`DISPUTE.STATUS` webhook](/api-reference/endpoints/v2.4/dispute-&-chargebacks-webhooks/dispute-status) will be sent.

<Frame caption="Dispute lifecycle">![Dispute lifecycle](https://goat-assets.production.core.primer.io/marketing/disputes/external-docs/dispute-lifecycle/dispute-lifecycle.png)</Frame>

<Note>
  Visa and Mastercard do not investigate payments before raising a dispute. As a result, these payment methods skip `RETRIEVAL` and go straight to the `DISPUTE` event type.
</Note>

## Dispute Types

As in the diagram above, Primer's disputes framework separates disputes into three different types: `RETRIEVAL`, `DISPUTE` and `PREARBITRATION`

### RETRIEVAL

A `RETRIEVAL` signifies an investigation into a payment has been launched. For cards, this is launched by a card issuer. Depending on the results of this investigation, a `DISPUTE` may be raised, and the payment can be reversed. This dispute type is not used by all payment methods or card schemes - Visa and Mastercard do not support it.

| **`status`** | **Description**                                                                                           |
| ------------ | --------------------------------------------------------------------------------------------------------- |
| `OPEN`       | Occurs when an investigation is launched into a payment. The merchant has not been debited for this yet.  |
| `EXPIRED`    | Occurs when a retrieval is opened and the merchant has taken too long to provide evidence in a challenge. |
| `CHALLENGED` | Occurs when a retrieval is opened, and the merchant submits evidence to uphold the original sale.         |

### DISPUTE

A `DISPUTE` occurs when a payment is reversed by the payment method (card issuer) after a customer complaint.
The end customer will receive money back, and the processor will then debit the merchant the equivalent amount.
For card payments, this is also known as a chargeback.

| **`status`** | **Description**                                                                                                                                                                                |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `OPEN`       | Occurs when a payment has been disputed, and your processor account has debited.                                                                                                               |
| `ACCEPTED`   | Occurs when a disputed payment has been accepted - acknowledged as a fair dispute by the merchant.                                                                                             |
| `CHALLENGED` | If a merchant thinks that a dispute has been unfairly raised, they can challenge it. This event is sent when a merchant submits evidence to challenge a dispute, and uphold the original sale. |
| `EXPIRED`    | Merchants only have a finite time window in which they can challenge a dispute. This status is set when that time window expires.                                                              |
| `CANCELLED`  | When a dispute is withdrawn by the end customer who raised the initial dispute, the dispute status will be changed to <TxnTag status="CANCELLED" />.                                           |
| `WON`        | If a dispute has been successfully challenged by the merchant, the dispute status will be updated to `WON`. For some card flows, this is known as a chargeback reversal.                       |
| `LOST`       | If a dispute has been unsuccessfully challenged, the dispute status will be updated to `LOST`.                                                                                                 |

### PREARBITRATION

If a merchant successfully challenges a dispute, but the payment method (usually a card issuer) believes a further review is required, a `PREARBITRATION` dispute type will be opened.
This is effectively an ‘appeal’ process.

| **`status`** | **Description**                                                                                                                                                                              |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `OPEN`       | If a dispute has been challenged, but is appealed, the dispute status will be updated to `OPEN`. For cards, this occurs if the card issuer does not feel the evidence was compelling enough. |
| `WON`        | Occurs when the pre-arbitration is won by the merchant, confirming the dispute has been overturned.                                                                                          |
| `LOST`       | Occurs when the pre-arbitration is lost by the merchant, confirming the original dispute will stand. This is sometimes known as a second chargeback.                                         |