What is normalization of the dispute lifecycle?

Hyperswitch represents disputes through two enumerations that unify the diverse payment processor vocabularies. First is a DisputeStatus that carries the outcomes from dispute_opened to dispute_expired. Second is a DisputeStage that carries the escalation level from pre-dispute to reversal. Every payment processor dispute events is mapped deterministically into both axes at the integration layer.

The normalization of dispute lifecycle involves handling three aspects: (i) Status normalization, (ii) Channel normalization, and (iii) Workflow normalization.

Status normalization

Every payment processor provides dispute states differently. Hyperswitch condenses all of this into seven canonical statuses defined in a single DisputeStatus. The DisputeStatus is complemented by a DisputeStage that tracks escalation levels which could be pre-dispute, dispute, pre-arbitration, arbitration, or reversal. The mapping is fully deterministic and resides within the integration layer of the Hyperswitch platform.

Figure 1. The canonical Hyperswitch's dispute state machine. All payment processor-specific states collapse into these seven statuses

Below is a sample of how the unification looks like across Stripe, Adyen and Worldpay on the Hyperswitch system.

Note: While the DisputeStatus mapping for a payment processor (Stripe) may have some repeat values, the combination of WebhookEvent and DisputeStatus will always lead to a dispute status in the Hyperswitch system.

With such a unification, the dispute flow integrated once through the Hyperswitch system will work seamlessly across multiple payment processors.

Channel normalization

The second unification is to manage the diversity in how processors notify dispute information. It is generally implemented by payment processors through three notification channels:

• Real-time Webhooks
• List/Retrieve APIs
• Dashboard

Each payment processor uses one or a combination of channels, and the spread across the ecosystem is wider than most merchants expect. The table below summarises the notification channel used by multiple payment processors for inbound dispute data.

Three broad categories from the analysis: (i) Payment processors with both Webhooks and APIs, (ii) Payment processors that expose only a list API, and (iii) Payment processors where disputes live in a dashboard with no machine-readable channel integration at all.

Figure 2. How Hyperswitch normalizes disputes from each notification and presents a unified surface to the merchant.

This is where the common simplification that most processors support both webhooks and APIs breaks down. For example - Worldpay Vantiv does not send real-time dispute webhooks. The chargeback and retrieval information is delivered as batch report files retrieved through the Report API. That single fact will drive a significant part of the orchestration design: Hyperswitch cannot assume a webhook is coming, so for this class of payment processor it runs a scheduled polling loop and converts list-API results into the same internal event stream that webhook-based connectors feed into.

Handling payment processors not offering real-time webhooks

Hyperswitch implements a polling pipeline that handles payment processors (like Worldpay Vantiv) so that webhook-less payment processors can participate in the same unified event stream. This happens through a three step process:

• Schedule configuration: Payment processors that only support list APIs are flagged in configuration. The merchant can set a schedule frequency for the particular payment processor.
• Fetch and Normalize: The payment processor’s list/ retrieve disputes API is triggered with a paginated and date-windowed request. The response is validated and inserted as a new record in the dispute table.
• Termination: The schedule keeps running until the dispute reaches a terminal status.

Workflow normalization

While interpretation of the dispute state is one side of the problem, acting on it is the other side to be simplified. A complete dispute management workflow needs at minimum four operations: retrieve, accept, upload evidence, and submit defense. Below is a summary of how the dispute management workflow is unified across three payment processors.

The availability of dispute workflow automation through APIs is not uniform across the wider set of payment processors. The table below captures, for the same three reference processors, whether programmatic workflow actions exist at all.

Beyond the three reference payment processors, most acquirers globally still require evidence to be uploaded through a hosted portal or emailed as a PDF to a representation address. Hyperswitch normalizes the interpretation side for those processors so that the dispute appears in the same dashboard with the same status vocabulary. However, the actionable side falls back to a link-out into the processor's own portal. That is a property of the acquirer ecosystem, not of the orchestration layer.

Missing dispute SLAs on webhook-less payment processors

Failure to address disputes within the required timeline leads to fines and settlements being blocked. Lets say, a merchant assumes Worldpay Vantiv pushes webhook events the same way Stripe does, or if the merchant does not poll Worldpay Vantiv frequently enough, there are risks of breaching the deadline to respond to the chargeback. To add to this complexity, every payment processor and card network combination has different SLAs for dispute handling. Visa typically grants 30 days for chargeback response while Mastercard windows are 45 days, and individual payment processors can shorten these further.

Hyperswitch provides configuration settings to poll regularly and surfaces the deadline as challenge_required_by on every DisputeResponse, so the merchant's SLA logic is driven by one field regardless of source.

Implementation

For any merchant with chargeback volume above 20 basis points (as a percentage of total transactions), the recommended implementation pattern is to consume Hyperswitch's outbound webhook stream.

The payload envelope is consistent across all event types; the content.object field carries a full DisputeResponse as below.

{
  "merchant_id": "merchant_1234",
  "event_id": "evt_01J9X7KQ8F3N2R5W6T8Y9Z0A1B",
  "event_type": "dispute_opened",
  "timestamp": "2026-04-24T10:15:32Z",
  "content": {
    "type": "dispute_details",
    "object": {
      "dispute_id": "dp_01J9X7KQ8F3N2R5W6T8Y9Z0A1B",
      "payment_id": "pay_01J9W2ABCDEF...",
      "attempt_id": "att_01J9W2ABCDEF...",
      "amount": "4999",
      "currency": "USD",
      "dispute_stage": "dispute",
      "dispute_status": "dispute_opened",
      "connector": "stripe",
      "connector_status": "needs_response",
      "connector_dispute_id": "dp_1Q8xYz...",
      "connector_reason": "Product not received",
      "connector_reason_code": "13.1",
      "challenge_required_by": "2026-05-08T23:59:59Z",
      "connector_created_at": "2026-04-24T10:15:30Z",
      "connector_updated_at": "2026-04-24T10:15:30Z",
      "created_at": "2026-04-24T10:15:32Z",
      "profile_id": "pro_01J...",
      "merchant_connector_id": "mca_01J...",
      "is_already_refunded": false
    }
  }
}

The event_type takes one of seven values corresponding to each dispute_status transition. Because the payload always carries the same shape, a merchant's handler can be a single function with a switch statement on event_type.

The fastest way to validate your Hyperswitch dispute integration is to trigger a dispute through Stripe's test environment using a card number that simulates a chargeback, then observe the normalized event stream Hyperswitch delivers to your webhook endpoint regardless of which processor raised the dispute.

The integration you tested against Stripe’s sandbox will be the integration you go live with everywhere. Whether the dispute arrives as a charge.dispute.created webhook from Stripe, or a NOTIFICATION_OF_CHARGEBACK from Adyen, or a row pulled from a Worldpay Vantiv Report API - it will expose one unified interface to the merchant.

Once the implementation is done, adding a new processor to your payment stack will be very simple without having to modify your dispute handling setup.