Skip to main content

​
Dispute Flow

​
List Disputes

Retrieve a list of disputes processed for your game. Send a server-side request to list disputes: 
const { disputes } = await toffee.disputes.list({
  paymentId: "pay_xyz789",
  limit: 50,
});
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: 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

  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) before executing player account restrictions.