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

# Disputes

> Learn how chargebacks work on Axra Pay, how to retrieve dispute data via the API, and what steps you can take to reduce disputes and win them.

A dispute — also called a chargeback — occurs when a cardholder contacts their bank to challenge a charge. The bank initiates a formal dispute process on the cardholder's behalf, and the outcome determines whether the funds are returned to the customer or kept by you. When a dispute is opened, Axra immediately debits the full charge amount from your merchant account and charges a **\$5.82 dispute fee**. This fee is non-refundable regardless of the outcome — even if you win the dispute.

<Warning>
  Disputes can occur weeks or months after the original transaction. Maintain records of customer orders, delivery confirmations, and communications so you can respond with evidence if needed.
</Warning>

## How disputes affect your account

| Event                  | Merchant impact                                      |
| ---------------------- | ---------------------------------------------------- |
| `payment.disputed`     | Charge amount debited + \$5.82 dispute fee charged   |
| `payment.dispute_won`  | Charge amount re-credited (dispute fee not refunded) |
| `payment.dispute_lost` | No further changes — funds already debited           |

Axra notifies you of each stage via [webhook events](/manage/webhooks). Subscribe to `payment.disputed`, `payment.dispute_won`, and `payment.dispute_lost` to track dispute outcomes in real time.

## List disputes

Retrieve all disputes for your business account.

```bash theme={null}
GET /business/disputes
```

**Authentication:** Required

**Query parameters:**

| Parameter | Type   | Default | Description                                        |
| --------- | ------ | ------- | -------------------------------------------------- |
| `status`  | string | `all`   | Filter by outcome: `open`, `won`, `lost`, or `all` |
| `page`    | number | `1`     | Page number for pagination                         |
| `limit`   | number | `20`    | Results per page                                   |

**Example response:**

```json theme={null}
{
  "data": [
    {
      "id": "bpay_01H...",
      "amount": 49.99,
      "currency": "USD",
      "status": "DISPUTED",
      "metadata": {
        "disputeId": "dp_1Abc...",
        "disputeReason": "fraudulent",
        "merchantDisputeFee": 5.82
      },
      "business": {
        "id": "biz_01H...",
        "businessName": "Acme Corp"
      },
      "updatedAt": "2026-03-20T16:00:00.000Z"
    }
  ],
  "meta": {
    "total": 3,
    "page": 1,
    "limit": 20,
    "totalPages": 1
  }
}
```

## Get dispute statistics

Retrieve an aggregate summary of dispute activity for your account.

```bash theme={null}
GET /business/disputes/stats
```

**Authentication:** Required

**Response fields:**

| Field              | Description                                |
| ------------------ | ------------------------------------------ |
| `open`             | Number of disputes currently in progress   |
| `won`              | Number of disputes resolved in your favor  |
| `lost`             | Number of disputes resolved against you    |
| `total`            | Total disputes across all statuses         |
| `winRate`          | Percentage of resolved disputes you won    |
| `totalDisputeFees` | Total dispute fees charged to your account |

## Get dispute detail

Retrieve full dispute information for a specific payment.

```bash theme={null}
GET /business/disputes/:paymentId
```

**Authentication:** Required

**Path parameters:**

| Parameter   | Description                                            |
| ----------- | ------------------------------------------------------ |
| `paymentId` | The ID of the payment to look up (e.g., `bpay_01H...`) |

**Errors:**

| Status | Meaning                                                  |
| ------ | -------------------------------------------------------- |
| `400`  | The payment exists but has no dispute associated with it |
| `404`  | No payment found with the given ID                       |

The response is the full payment object, with dispute metadata in the `metadata` field — including `disputeId`, `disputeReason`, and `merchantDisputeFee`.

## Reducing disputes

The most effective way to manage disputes is to prevent them. Fewer disputes mean lower fees, a healthier account standing, and less time spent on evidence gathering.

<Steps>
  <Step title="Enable 3DS authentication">
    Use [3D Secure authentication](/payments/3ds-authentication) on card transactions. When a customer completes 3DS, fraud liability shifts from you to the card issuer — meaning you win most fraud-related disputes automatically.
  </Step>

  <Step title="Use clear billing descriptors">
    Make sure the charge description on your customers' bank statements clearly identifies your business. An unrecognized charge name is one of the most common reasons customers dispute a transaction.
  </Step>

  <Step title="Respond to disputes promptly">
    Card networks impose strict deadlines — typically 7–21 days — for submitting evidence. Respond as quickly as possible with relevant documentation: order receipts, delivery confirmations, customer communications, and usage logs.
  </Step>

  <Step title="Maintain transaction records">
    Keep records of customer interactions, order details, shipping/delivery confirmations, and any refund requests. These are your primary tools when building a dispute response.
  </Step>
</Steps>

<Tip>
  If a customer contacts you directly about an issue before filing a dispute, resolving it promptly (including issuing a refund if warranted) is almost always cheaper than a chargeback. You avoid the dispute fee and protect your dispute rate.
</Tip>