# Disputes

{% hint style="info" %}
The **Disputes API is in active development** and not yet available against the staging endpoint. This page documents the shape so you can plan an integration. The contract below will not change in incompatible ways at launch.
{% 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://support.swisspay.ai/api-reference/disputes.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.