Skip to main content

Dispute events

PaymentsAI dispatches dispute events whenever a chargeback or inquiry is opened or updated on a transaction. Use these events to track dispute status and respond before deadlines.

Events​

Event typeWhen it fires
dispute-createdA new dispute (chargeback or inquiry) was opened on a transaction.
dispute-updatedAn existing dispute was updated. The status, evidence, or deadline changed.
dispute-lostThe dispute was resolved in favor of the customer. Funds were debited from your account.
dispute-wonThe dispute was resolved in favor of the merchant.
dispute-commentsA new comment was added to the dispute.

Payload​

All dispute events share the same payload shape:

type Event = {
  deduplicationId: string;
  type: string;
  organizationId: string;
  metadata: Dispute;
};

See Schemas for the full Dispute type definition, including DisputeCategory, DisputeType, and DisputeReasonCode.

Correlating with transactions​

The metadata.transaction field on the dispute payload contains the full transaction object that was disputed. Use metadata.transaction.id to link the dispute back to the original transaction-processed event.

Typical dispute lifecycle​

dispute-created
  ↓
dispute-updated  (may fire multiple times as the dispute progresses)
  ↓
dispute-won | dispute-lost

Check metadata.createdAt and respond to the dispute before the deadline. See Dispute process for how to submit evidence.