> ## Documentation Index
> Fetch the complete documentation index at: https://galacticagames.mintlify.site/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](https://galacticagames.mintlify.site/api-reference/disputes/list.md):

> [tab] TypeScript
>
> ```typescript theme={null}
> const { disputes } = await toffee.disputes.list({
>   paymentId: "pay_xyz789",
>   limit: 50,
> });
> ```

> [tab] Python
>
> ```python theme={null}
> resp = await toffee.disputes.list(ListDisputesRequest(
>     payment_id="pay_xyz789",
>     limit=50,
> ))
> disputes = resp.disputes
> ```

> [tab] 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] API
>
> ```http theme={null}
> GET /v1/disputes?payment_id=pay_xyz789&limit=50&offset=0
> Authorization: Bearer <your_access_token>
> ```

**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:** 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.

```json theme={null}
[
  {
    "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"
  }
]
```

***

## 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`](https://galacticagames.mintlify.site/api-reference/webhooks/dispute.created): When a dispute is created and registered

See the [Webhooks](https://galacticagames.mintlify.site/webhooks.md) 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](https://galacticagames.mintlify.site/webhooks.md#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](https://galacticagames.mintlify.site/webhooks.md)) before executing player account restrictions.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.