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"
  }
}

Cuándo se dispara

Cuando el banco del titular de la tarjeta notifica al proveedor de pagos que se está disputando un cargo (un contracargo). El monto disputado se congela de tu saldo de payout mientras la disputa esté abierta. Como Merchant of Record, Commet gestiona el proceso de evidencia y resolución con el proveedor.

disputeAmount es el monto en disputa en centavos; disputeReason es el código de motivo del proveedor (por ejemplo fraudulent o product_not_received), o null cuando el proveedor no indica ninguno.

La resolución dispara payment.dispute_resolved con el resultado. Usa este evento para marcar la cuenta internamente — las disputas repetidas son una fuerte señal de fraude.