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

# Disputes

> Track and manage payment disputes

## Dispute Flow

```mermaid theme={null}
sequenceDiagram
    participant User as Cardholder / Bank
    participant API as ToffeePay
    participant Server as Game Server

    User->>API: Contests charge (Chargeback)
    API->>API: Log dispute petition
    API->>API: Recalculate user fraud persona (BAD_ACTOR / HIGH_RISK)

    API->>Server: Send dispute webhook (signed)
    Server->>Server: Verify webhook signature
    Server->>Server: Lock bad actor / restrict account
```

***

## List Disputes

Retrieve a list of disputes processed for your game. Send a server-side request to [list disputes](/api-reference/disputes/list):

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    const { disputes } = await toffee.disputes.list({
      paymentId: "pay_xyz789",
      limit: 50,
    });
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    resp = await toffee.disputes.list(ListDisputesRequest(
        payment_id="pay_xyz789",
        limit=50,
    ))
    disputes = resp.disputes
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    paymentId := "pay_xyz789"
    limit := int32(50)
    resp, err := toffee.Disputes.List(ctx, &sdk.ListDisputesRequest{
      PaymentId: &paymentId,
      Limit:     &limit,
    })
    disputes := resp.GetDisputes()
    ```
  </Tab>

  <Tab title="API">
    ```http theme={null}
    GET /v1/disputes?payment_id=pay_xyz789&limit=50&offset=0
    Authorization: Bearer <your_access_token>
    ```
  </Tab>
</Tabs>

**Query Parameters:**

* `payment_id`: *Optional.* Filter disputes for a specific payment transaction ID.
* `limit`: *Optional.* Max number of disputes to return (default: `100`, max: `250`).
* `offset`: *Optional.* Number of records to skip (default: `0`).
* `from`: *Optional.* Filter disputes created at or after this RFC 3339 timestamp.
* `to`: *Optional.* Filter disputes created at or before this RFC 3339 timestamp.

**Response:** A `ListDisputesResponse` containing an array of disputes.

<Note>
  A dispute's resolution state is assigned and updated by the upstream payment
  provider, not by ToffeePay. Because that lifecycle is outside our control, a
  normalized `status` field is intentionally **not** exposed on the public API.
  It may be added later as a normalized value if there is demand.
</Note>

```json theme={null}
{
  "disputes": [
    {
      "id": "dp_01kw1w89abcdefghij",
      "payment_id": "pay_9876543210",
      "reason": "FRAUDULENT - Cardholder claims transaction was not authorized.",
      "amount": 1500,
      "currency": "USD",
      "created_at": "2026-06-26T11:55:36Z"
    }
  ],
  "total": 1,
  "has_more": false
}
```

***

## Dispute Properties

Each dispute contains the following key properties:

* `id`: The unique identifier for the dispute (e.g. `dp_01kw1w89abcdefghij`).
* `payment_id`: *Optional.* The ID of the original payment transaction that was disputed. May be absent when the dispute could not be matched to a payment in our system.
* `reason`: The raw explanation or reasoning code provided by the bank or payment processor.
* `amount`: The total disputed transaction amount in minor currency units (e.g., `1500` = `$15.00`).
* `currency`: The currency of the disputed transaction (`USD`, `GBP`, `EUR`).
* `created_at`: RFC 3339 timestamp when the dispute was registered by ToffeePay.

***

## Webhook Events

ToffeePay sends webhooks for the following dispute-related events:

* [`dispute.created`](/api-reference/webhooks/dispute.created): When a dispute is created and registered

See the [Webhooks](/webhooks) page for implementation details and signature verification.

***

## Handle Dispute Notifications

When a dispute is processed, ToffeePay sends a **signed webhook** to your backend.

**Sample Payload:**

```json theme={null}
{
  "type": "dispute.created",
  "timestamp": "2026-06-29T12:00:00Z",
  "data": {
    "id": "dp_01kw1w89abcdefghij",
    "payment_id": "pay_9876543210",
    "reason": "FRAUDULENT - Cardholder claims transaction was not authorized.",
    "amount": 1500,
    "currency": "USD",
    "created_at": "2026-06-26T11:55:36Z"
  }
}
```

For webhook signature verification, see the [Webhooks](/webhooks#webhook-signature-verification) page.

***

## Best Practices

1. **Restrict Bad Actors**: When processing a dispute webhook, use the `payment_id` to look up the original transaction in your system, resolve the associated player, and lock or restrict their account to prevent further fraud.
2. **Fraud Pattern Analysis**: Regularly audit dispute rates against the originating payments (joined via `payment_id`) to tune your checkout and fraud verification gates.
3. **Webhook Verification**: Always verify webhook signatures (see [Webhooks](/webhooks)) before executing player account restrictions.