Payload

All webhook payloads follow a consistent top-level structure with event-specific data nested within the data object.

paymentTransactionIdstring

The disputed payment transaction ID.

invoiceIdstring | null

The invoice the payment collected, or null for payments without an invoice.

invoiceNumberstring | null

The human-readable invoice number, if available.

customerIdstring | null

The customer ID, when the payment is linked to an invoice. Returns your externalId if you provided one when creating the customer, otherwise returns the Commet publicId.

subscriptionIdstring | null

The subscription ID, if the invoice is linked to a subscription.

disputeAmountnumber

The contested amount in cents (100 = $1.00).

currencystring

The dispute currency code.

disputeReasonstring | null

The provider's reason code (e.g. fraudulent, product_not_received), or null when none is given.

{
  "event": "payment.disputed",
  "timestamp": "2026-05-02T09:00:00.000Z",
  "organizationId": "org_abc123",
  "mode": "live",
  "apiVersion": "2026-06-10",
  "data": {
    "paymentTransactionId": "ptx_q7r8s9",
    "invoiceId": "inv_n4o5p6",
    "invoiceNumber": "INV-0043",
    "customerId": "user_123",
    "subscriptionId": "sub_1a2b3c4d",
    "disputeAmount": 9900,
    "currency": "usd",
    "disputeReason": "fraudulent"
  }
}

When this fires

When the cardholder's bank notifies the payment provider that a charge is being disputed (a chargeback). The disputed amount is frozen from your payout balance while the dispute is open. As the Merchant of Record, Commet handles the evidence and resolution process with the provider.

disputeAmount is the contested amount in cents; disputeReason is the provider's reason code (for example fraudulent or product_not_received), or null when the provider gives none.

The resolution fires payment.dispute_resolved with the outcome. Use this event to flag the account internally — repeated disputes are a strong fraud signal.