Disputes

Dispute Flow

List Disputes

Retrieve a list of disputes processed for your game. Send a server-side request to list disputes:

TypeScript
Python
Go
API

const { disputes } = await toffee.disputes.list({
  paymentId: "pay_xyz789",
  limit: 50,
});

resp = await toffee.disputes.list(ListDisputesRequest(
    payment_id="pay_xyz789",
    limit=50,
))
disputes = resp.disputes

paymentId := "pay_xyz789"
limit := int32(50)
resp, err := toffee.Disputes.List(ctx, &sdk.ListDisputesRequest{
  PaymentId: &paymentId,
  Limit:     &limit,
})
disputes := resp.GetDisputes()

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: A ListDisputesResponse containing an array of disputes.

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.

{
  "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: When a dispute is created and registered

See the 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:

{
  "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 page.

Best Practices

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.
Fraud Pattern Analysis: Regularly audit dispute rates against the originating payments (joined via payment_id) to tune your checkout and fraud verification gates.
Webhook Verification: Always verify webhook signatures (see Webhooks) before executing player account restrictions.

Bootstrap

Core

Integration

Dispute Flow

List Disputes

Dispute Properties

Webhook Events

Handle Dispute Notifications

Best Practices

​Dispute Flow

​List Disputes

​Dispute Properties

​Webhook Events

​Handle Dispute Notifications

​Best Practices

Dispute Flow

List Disputes

Dispute Properties

Webhook Events

Handle Dispute Notifications

Best Practices