Categories and Stages

Overview

Highnote disputes fall into four categories and progress through up to five stages.

Each dispute carries a status, as does each stage. For example, a consumer dispute in the representment stage is IN_REVIEW as a whole, while its representment stage is IN_PROGRESS, and its chargeback stage is COMPLETED.

For all dispute/stage status possibilities, see the category-stage status matrix below.

Disputes

A dispute's category and status describe it as a whole. The category classifies what the cardholder claims and determines how you contest it; the status tracks the dispute's progress and outcome.

Dispute categories

Every dispute is assigned one of four CardPaymentDisputeCategory values:

Category	Description
CONSUMER_DISPUTE	Dispute categorized as a consumer dispute. Has an optional questionnaire.
PROCESSING_ERROR	Dispute categorized as a processing error. Has an optional questionnaire.
FRAUD	Dispute categorized as fraud.
INVALID_AUTHORIZATION	Dispute categorized as an authorization issue.

Each category maps to a set of network reason codes and, where applicable, a category-specific evidence questionnaire. See Network Reason Codes for the code tables and Evidence Questionnaires for the questionnaire reference.

Dispute statuses

The overall dispute carries a CardPaymentDisputeStatus that reflects where the dispute stands as a whole:

Status	Meaning
INITIATED	Dispute has been initiated.
IN_REVIEW	Dispute is in review.
TIMED_OUT	Dispute has timed out due to inaction.
WITHDRAWN	Dispute has been withdrawn by the party that created it.
CLOSED	Dispute is closed.
ISSUER_ACCEPTED	Issuer accepts responsibility for the dispute. Resolved in favor of the merchant.
MERCHANT_ACCEPTED	Merchant accepts responsibility for the dispute. Resolved in favor of the issuer.

Stages

A dispute progresses through one to five stages—either party can accept the loss at any stage, and some network workflows skip stages entirely. Visa fraud and authorization disputes, for example, have no representment stage; see Network differences. Stages are exposed as objects implementing the CardPaymentDisputeStage interface:

Stage	What it represents
CardPaymentDisputeChargebackStage	The first stage of the dispute where the cardholder, via their issuing bank, disputes a transaction.
CardPaymentDisputeRepresentmentStage	The acquiring merchant challenges the issuer's chargeback by submitting further evidence.
CardPaymentDisputePreArbitrationStage	Either party—issuer or merchant—escalates the dispute after representment.
Pre-Arbitration Response	The party that did not initiate pre-arbitration responds—a partial acceptance or a denial contesting the claim. The last opportunity to resolve the dispute without network intervention and arbitration.
CardPaymentDisputeArbitrationStage	The final stage, where the card network makes a binding decision.

Stage statuses

Each stage of the dispute tracks its own CardPaymentDisputeStageStatus, independent of the overall dispute status:

Status	Meaning
PENDING	The stage is awaiting action.
IN_PROGRESS	The stage is actively being worked on.
COMPLETED	The stage has been completed.
EXPIRED	The stage has expired without action.

Stage response windows

Every stage carries a deadline field:

Field	Type	Description
responseDueAt	String (ISO-8601)	The deadline for a response.

missing response deadlines

Missing a response deadline typically results in the dispute closing against the merchant.

How disputes resolve

A dispute resolves in one of three ways—a party accepts the loss, a response window lapses, or the card network rules at arbitration.

• Chargeback: The merchant accepts the chargeback, resolving the dispute in the issuer's favor.
• Representment: The issuer accepts the merchant's evidence, resolving the dispute in the merchant's favor.
• Pre-arbitration: The party that did not initiate pre-arbitration accepts the claim in full.
• Pre-arbitration response: The initiating party accepts the response—in a partial acceptance, a portion of the disputed amount resolves in each party's favor. This is the last opportunity to resolve the dispute without network intervention.
• Arbitration: The card network's binding decision resolves the dispute—won, lost, or partially won for the merchant.

At any stage before arbitration, a dispute can also resolve by timeout—miss a response window and the dispute typically closes against the merchant.

When a dispute concludes, its final outcome surfaces on the disputeOutcome field as a CardPaymentDisputeOutcome: WON, LOST, or PARTIALLY_WON, from the merchant's perspective.

Category-stage status matrix

The dispute and stage statuses move together—a dispute under review has exactly one stage in progress, and every stage in its history is completed:

Stage status → Dispute status ↓	PENDING	IN_PROGRESS	COMPLETED	EXPIRED
INITIATED	Chargeback stage (creation)	—	—	—
IN_REVIEW	—	The active stage	All earlier stages	—
MERCHANT_ACCEPTED	—	—	All stages	—
ISSUER_ACCEPTED	—	—	All stages	—
TIMED_OUT	—	—	—	—
WITHDRAWN	—	—	—	—
CLOSED	—	Final stage (timeout)	All stages (acceptance)	—

Read the matrix as follows:

• A live dispute is IN_REVIEW with exactly one stage IN_PROGRESS; every earlier stage in the dispute's history is COMPLETED.
• A resolved dispute is MERCHANT_ACCEPTED, ISSUER_ACCEPTED, or CLOSED with all stages COMPLETED—with one exception: a dispute that closes because a response window lapsed may keep its final stage IN_PROGRESS.
• INITIATED and TIMED_OUT are transitional: a new dispute typically advances to IN_REVIEW as it is created—though a query can catch it earlier, as INITIATED with a PENDING chargeback stage—and a timed-out dispute typically advances to CLOSED. Both also appear in dispute webhook events along the way.
• An em-dash marks a combination without a documented pattern, not one that cannot occur. EXPIRED, for example, is the stage-level counterpart of a lapsed response window, and WITHDRAWN has a matching webhook event. Handle every defined value in your code rather than treating any status as unreachable.