> For the complete documentation index, see [llms.txt](https://support.swisspay.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://support.swisspay.ai/api-reference/disputes.md).

# Disputes

{% hint style="info" %}
The **Disputes API is in active development** and not yet exposed on the public API. This page documents the shape so you can plan an integration. The contract below will not change in incompatible ways at launch. Until the endpoints ship, dispute notifications arrive via email and the dashboard.
{% endhint %}

A dispute represents a chargeback or related challenge raised against one of your payments. SwissPay normalises events from every connected processor into a single provider-neutral resource, so your handling code does not need to branch on processor.

## The Dispute object

```json
{
  "id": "dsp_01HABCXYZ...",
  "payment": "pay_01HABCXYZ...",
  "customer": "cus_01HCUSXYZ...",
  "amount": 2999,
  "currency": "CHF",
  "state": "chargeback",
  "status": "action_required",
  "reason": "fraud_card_absent",
  "respond_by": "2026-06-04T23:59:59Z",
  "raised_at": "2026-05-20T12:00:00Z",
  "payment_method": {
    "type": "card",
    "brand": "visa",
    "last4": "1111"
  },
  "arn": "12345600000000000000001",
  "metadata": {}
}
```

| Field                 | Type           | Notes                                                                                           |
| --------------------- | -------------- | ----------------------------------------------------------------------------------------------- |
| `id`                  | string         | Stable, prefixed with `dsp_`.                                                                   |
| `payment`             | string         | The `pay_...` ID under dispute.                                                                 |
| `customer`            | string \| null | The `cus_...` ID of the customer attached to the disputed payment, when one was attached.       |
| `amount` / `currency` | int / string   | The disputed amount in minor units. May be less than the original payment for partial disputes. |
| `state`               | string         | The dispute lifecycle stage — see below.                                                        |
| `status`              | string         | The action required (or completed).                                                             |
| `reason`              | string         | Card-network reason code translated to a stable enum.                                           |
| `respond_by`          | string         | ISO 8601 deadline by which a defence must be submitted.                                         |
| `arn`                 | string \| null | Acquirer Reference Number, when the processor returned one.                                     |
| `payment_method`      | object         | Same shape as on `Payment` — brand + BIN + last4 only.                                          |

## State and status

`state` traces the dispute through the network's lifecycle:

| State                 | Meaning                                                              |
| --------------------- | -------------------------------------------------------------------- |
| `information_request` | The issuer has asked for documentation — not yet a chargeback.       |
| `chargeback`          | A formal chargeback has been filed.                                  |
| `pre_arbitration`     | The issuer has rejected the first defence and re-raised the dispute. |
| `scheme_arbitration`  | The card network is adjudicating.                                    |
| `second_chargeback`   | A new chargeback filed after a previous one was reversed.            |

`status` reflects what *you* need to do:

| Status            | Meaning                                                      |
| ----------------- | ------------------------------------------------------------ |
| `new`             | We have received the dispute; nothing required from you yet. |
| `action_required` | You must accept or defend before `respond_by`.               |
| `challenged`      | You submitted a defence; awaiting outcome.                   |
| `recovered`       | A previously-lost dispute has been reversed in your favour.  |
| `accepted`        | You chose to accept (or did not respond).                    |
| `lost`            | The dispute was decided against you.                         |
| `won`             | The dispute was decided in your favour.                      |

## Planned endpoints

When the API ships, you will be able to:

* `GET /api/v1/disputes` — list disputes for your merchant account, with filters by `state`, `status`, `payment`, and time range.
* `GET /api/v1/disputes/{id}` — retrieve a single dispute.
* `POST /api/v1/disputes/{id}/accept` — accept the loss and stop the challenge.
* `POST /api/v1/disputes/{id}/defend` — submit evidence to challenge.

The exact submission schema (and the evidence types each card scheme accepts) will be documented when the endpoints go live. Until then, dispute notifications will arrive via email and the dashboard.