Dispute Events

Dispute webhook events are triggered whenever a dispute (chargeback) is created or updated for a payment. These events allow you to track the lifecycle of a dispute and take appropriate action.

Dispute Status Overview

Status	Description
created	The dispute request has been created
processing	The dispute request is currently in process
active	The dispute is active and awaiting resolution
lost	The dispute was lost. Funds have been returned to the payer
won	The dispute was won by the merchant. Funds have been returned to the merchant
failed	The dispute process failed due to an internal or processor error

Event: Dispute Status — Created

This event is triggered when a new dispute is first created.

{
  "object": "event",
  "id": "bnxcd5rda2n7q7o4x7g0ioe8",
  "resource": {
    "object": "dispute",
    "id": "l0j286qvs32jp1hcybcfpe7n",
    "amount": "798.29",
    "currency": "USD",
    "settlementAmount": "798.29",
    "settlementCurrency": "USD",
    "fees": [],
    "paymentId": "uqyfsnsara28pmmvq97ki0y5",
    "resourceId": "uqyfsnsara28pmmvq97ki0y5",
    "resourceType": "Payment",
    "reason": "fraudulent",
    "status": "created",
    "created": "2025-07-15T20:50:08.000Z",
    "lastUpdated": "2025-07-15T20:50:08.000Z",
    "resource": {
      "object": "payment",
      "id": "uqyfsnsara28pmmvq97ki0y5",
      "amount": 798.29,
      "currency": "USD",
      "payer": {
        "object": "payer",
        "id": "yl7d5pupdmqkhvbm337tzun1",
        "name": "Mercury Rising Technologies",
        "email": "uluna+psx@paystand.com",
        "externalId": "CUST-42974F02"
      },
      "source": {
        "object": "source",
        "id": "6wyb3xmrj2qtpxb6658lxwoa",
        "nameOnCard": "Juan",
        "brand": "visa",
        "last4": "0259"
      },
      "sourceType": "Card",
      "status": "posted"
    }
  },
  "diff": {
    "previous": {},
    "changes": {
      "object": "dispute",
      "id": "l0j286qvs32jp1hcybcfpe7n",
      "reason": "fraudulent",
      "status": "created"
    }
  },
  "sourceId": "l0j286qvs32jp1hcybcfpe7n",
  "sourceType": "Dispute",
  "status": "active"
}

Event: Dispute Status — Processing

This event is triggered when a dispute moves to processing status, often including dispute fees.

{
  "object": "event",
  "id": "0a6jh9eqliutnfc76ra8dj8n",
  "resource": {
    "object": "dispute",
    "id": "l0j286qvs32jp1hcybcfpe7n",
    "amount": "798.29",
    "currency": "USD",
    "settlementAmount": "798.29",
    "settlementCurrency": "USD",
    "fees": [
      {
        "object": "fee",
        "id": "4zohgx3b3x2fqhrlunhh2rn2",
        "amount": "35.00",
        "resourceAmount": "798.29",
        "currency": "USD",
        "status": "active",
        "created": "2025-07-15T20:50:10.000Z",
        "lastUpdated": "2025-07-15T20:50:10.000Z"
      }
    ],
    "paymentId": "uqyfsnsara28pmmvq97ki0y5",
    "resourceId": "uqyfsnsara28pmmvq97ki0y5",
    "resourceType": "Payment",
    "reason": "fraudulent",
    "status": "processing",
    "created": "2025-07-15T20:50:08.000Z",
    "lastUpdated": "2025-07-15T20:50:11.000Z",
    "balanceChangeId": "q3zsu8d3cjvtpfm31w6l6ol0"
  },
  "diff": {
    "previous": {
      "fees": [],
      "status": "created",
      "lastUpdated": "2025-07-15T20:50:08.000Z"
    },
    "changes": {
      "fees": [
        {
          "object": "fee",
          "id": "4zohgx3b3x2fqhrlunhh2rn2",
          "amount": "35.00"
        }
      ],
      "status": "processing",
      "lastUpdated": "2025-07-15T20:50:11.000Z",
      "balanceChangeId": "q3zsu8d3cjvtpfm31w6l6ol0"
    }
  },
  "sourceId": "l0j286qvs32jp1hcybcfpe7n",
  "sourceType": "Dispute",
  "status": "active"
}

Key Dispute Event Fields

Field	Description
resource.id	Unique dispute identifier
resource.amount	Disputed amount
resource.currency	Currency code
resource.reason	Dispute reason (fraudulent, duplicate, etc.)
resource.status	Current dispute status
resource.paymentId	Original payment being disputed
resource.fees	Associated dispute fees
resource.balanceChangeId	Balance change when dispute affects account
sourceType	Always "Dispute" for dispute events

Common Dispute Reasons

Reason	Description
fraudulent	Customer claims they didn't authorize the payment
duplicate	Customer was charged multiple times for the same transaction
product_not_received	Customer didn't receive the product or service
product_unacceptable	Product or service was defective or not as described
credit_not_processed	Customer was promised a refund that wasn't processed
general	Other dispute reasons

Handling Dispute Events

Best Practices

1. Immediate action: Respond quickly when disputes are created
2. Document everything: Gather evidence for dispute response
3. Monitor fees: Track dispute fees that may be charged
4. Customer communication: Contact customers to resolve issues
5. Prevent future disputes: Analyze dispute patterns

Common Use Cases

• Alert systems: Notify teams immediately when disputes are created
• Evidence gathering: Automatically collect transaction evidence
• Customer outreach: Contact customers to resolve disputes amicably
• Accounting updates: Adjust records for disputed amounts and fees
• Fraud monitoring: Track fraudulent dispute patterns