# Disputes

Disputes buyers open on escrowed payments: read the thread, answer it.

## List disputes

`GET /v1/disputes`

The disputes buyers opened on this merchant's escrowed payments, newest first, and how many are open. Needs `payments:read`.

### Query parameters

- `status` `string`
- `limit` `integer`: Default 50.

### Responses

#### `200`: The disputes.

Body (`application/json`):

- `disputes` `object[]` _(required)_
  - `id` `string` _(required)_
  - `reference` `string` _(required)_: The number a person quotes, e.g. 93129301239.
  - `paymentIntentId` `string` _(required)_
  - `status` `string` _(required)_: `open` until the chain decides it; then how the funds moved.
  - `chain` `string` _(required)_
  - `payer` `string` _(required)_: The wallet that paid, and that a refund returns to.
  - `resolveBy` `string` _(required)_: ISO time after which a dispute nobody decided refunds the payer.
  - `openedAt` `string` _(required)_
  - `decidedAt` `string | null` _(required)_
- `open` `integer` _(required)_: Open disputes of this merchant, whatever the filter.

#### `403`: The key lacks `payments:read`, or is publishable.

Body (`application/json`):

- `error` `object` _(required)_
  - `code` `string` _(required)_
  - `message` `string` _(required)_
  - `retryable` `boolean` _(required)_
  - `details` `object`

### Example request

```bash
curl 'https://api.mayarin.xyz/v1/disputes?status=open&limit=0'
```

```ts
fetch('https://api.mayarin.xyz/v1/disputes?status=open&limit=0')
```

## Get a dispute and its thread

`GET /v1/disputes/{id}`

One dispute with its messages, oldest first. Reading refreshes it from the chain, so a decided dispute shows its outcome. Another merchant's dispute is a 404.

### Path parameters

- `id` `string` _(required)_

### Responses

#### `200`: The dispute.

Body (`application/json`):

- `dispute` `object & object` _(required)_

#### `404`: No such dispute.

Body (`application/json`):

- `error` `object` _(required)_
  - `code` `string` _(required)_
  - `message` `string` _(required)_
  - `retryable` `boolean` _(required)_
  - `details` `object`

### Example request

```bash
curl https://api.mayarin.xyz/v1/disputes/string
```

```ts
fetch('https://api.mayarin.xyz/v1/disputes/string')
```

## Answer in a dispute

`POST /v1/disputes/{id}/messages`

Posts the merchant's answer in the thread: evidence of delivery, or an offer to refund. Needs `disputes:manage`, which is separate from `refunds:manage`. Accepted only while the dispute is open. Announced by the `escrow.dispute.message` webhook.

### Path parameters

- `id` `string` _(required)_

### Request body (required) (`application/json`)

- `body` `string` _(required)_: 1 to 2,000 characters; trimmed.

### Responses

#### `201`: The saved message.

Body (`application/json`):

- `message` `object` _(required)_
  - `id` `string` _(required)_
  - `author` `string` _(required)_
  - `body` `string` _(required)_
  - `createdAt` `string` _(required)_

#### `400`: Empty or over-long message.

Body (`application/json`):

- `error` `object` _(required)_
  - `code` `string` _(required)_
  - `message` `string` _(required)_
  - `retryable` `boolean` _(required)_
  - `details` `object`

#### `403`: The key lacks `disputes:manage`, or is publishable.

Body (`application/json`):

- `error` `object` _(required)_
  - `code` `string` _(required)_
  - `message` `string` _(required)_
  - `retryable` `boolean` _(required)_
  - `details` `object`

#### `404`: No such dispute.

Body (`application/json`):

- `error` `object` _(required)_
  - `code` `string` _(required)_
  - `message` `string` _(required)_
  - `retryable` `boolean` _(required)_
  - `details` `object`

#### `409`: The dispute is already decided.

Body (`application/json`):

- `error` `object` _(required)_
  - `code` `string` _(required)_
  - `message` `string` _(required)_
  - `retryable` `boolean` _(required)_
  - `details` `object`

### Example request

```bash
curl https://api.mayarin.xyz/v1/disputes/string/messages \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "body": "string"
}'
```

```ts
fetch('https://api.mayarin.xyz/v1/disputes/string/messages', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    body: 'string'
  })
})
```