Disputes

Overview

Disputes (also known as chargebacks) occur when a customer questions a charge with their card issuer or bank, resulting in a formal dispute process. Using webhooks, merchant applications can receive real-time updates on dispute status changes and related events, allowing them to respond promptly and efficiently manage the dispute resolution process.

Supported Events

Event Type	Description	Applicable payment method types
DISPUTE_WON	Emitted when dispute is won and funds are reinstated.	CARD, BANK_ACCOUNT
DISPUTE_LOST	Emitted when dispute is lost.	CARD, BANK_ACCOUNT
DISPUTE_INITIATED	Emitted when a dispute is created and funds are withdrawn.	CARD, BANK_ACCOUNT

Event Structure

Field	Type	Valid values	Description
name	Enum	DISPUTE_WON, DISPUTE_LOST, DISPUTE_INITIATED	Event name
payload	Payload		Event Payload

Payload Structure

The payload contains comprehensive information about the dispute, including:

Field	Type	Description
amount	Number	The disputed amount
eventType	String	Type of dispute event (DISPUTE_INITIATED, DISPUTE_WON, DISPUTE_LOST)
merchantTransactionId	String	Unique identifier for the merchant's transaction
merchantId	String	Unique identifier for the merchant
evidence	Object	Collection of evidence related to the dispute
reason	String	The reason for the dispute (e.g., "FRAUDULENT")
status	String	Current status of the dispute (e.g., "NEEDS_RESPONSE")
paymentType	String	Type of payment method involved in the dispute
balanceTransactions	Array	List of balance transaction records related to the dispute

Evidence Object

The evidence object contains fields that can be submitted to support your case in a dispute. Different dispute reasons may require different types of evidence:

• billing_address: Customer's billing address
• customer_name: Name of the customer
• receipt: Receipt or proof of purchase
• service_documentation: Documentation of services provided
• shipping_documentation: Shipping confirmations or documentation
• And many other fields relevant to the specific dispute case

Balance Transaction Object

Each balance transaction contains details about financial impact:

• amount: Transaction amount
• currency: Currency code
• fee: Associated fees
• description: Description of the transaction
• status: Status of the transaction
• And other relevant financial details

Payload Structure Sample

{
   "amount": 50,
   "eventType": "DISPUTE_INITIATED||DISPUTE_WON||DISPUTE_LOST",
   "merchantTransactionId": "3ecd813a-12dd-4135-ac4e-9f400d5181fb",
   "merchantId": "8e44f962-36bf-4eef-b80c-fd6a23029800",
   "evidence": {
      "access_activity_log": null,
      "billing_address": "IN",
      "cancellation_policy": null,
      "cancellation_policy_disclosure": null,
      "cancellation_rebuttal": null,
      "customer_communication": null,
      "customer_email_address": null,
      "customer_name": "Devender",
      "customer_purchase_ip": null,
      "customer_signature": null,
      "duplicate_charge_documentation": null,
      "duplicate_charge_explanation": null,
      "duplicate_charge_id": null,
      "product_description": null,
      "receipt": null,
      "refund_policy": null,
      "refund_policy_disclosure": null,
      "refund_refusal_explanation": null,
      "service_date": null,
      "service_documentation": null,
      "shipping_address": null,
      "shipping_carrier": null,
      "shipping_date": null,
      "shipping_documentation": null,
      "shipping_tracking_number": null,
      "uncategorized_file": null,
      "uncategorized_text": null
   },
   "reason": "FRAUDULENT",
   "status": "NEEDS_RESPONSE",
   "paymentType": "CARD",
   "balanceTransactions": [
      {
         "amount": -50,
         "available_on": 1716854400,
         "created": 1716283111,
         "currency": "usd",
         "description": "Chargeback withdrawal for ch_3PIoq2I4dYE13Vva13lNTr3y",
         "exchange_rate": null,
         "fee": 1500,
         "fee_details": [
            {
               "amount": 1500,
               "application": null,
               "currency": "usd",
               "description": "Dispute fee",
               "type": "stripe_fee"
            }
         ],
         "id": "txn_1PIoq3I4dYE13VvaWkU6uYvT",
         "net": -1550,
         "object": "balance_transaction",
         "reporting_category": "dispute",
         "source": "dp_1PIoq2I4dYE13Vva263rszkj",
         "status": "pending",
         "type": "adjustment"
      }
   ]
}