Categories and Stages
Overview
Highnote disputes are one of two types: a chargeback or a compliance case. Chargebacks fall into four categories and progress through up to five stages. Compliance cases have no category and progress through up to three 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 SUBMITTED, and its chargeback stage is COMPLETED.
For all dispute/stage status possibilities, see the category-stage status matrix below.
Disputes
A dispute's type, category, and status describe it as a whole. The type tells a chargeback from a compliance case. The category classifies what the cardholder claims and determines how you contest a chargeback. The status tracks the dispute's progress and outcome.
Dispute types
Every dispute carries a type, a CardPaymentDisputeType value:
| Type | Description |
|---|---|
CHARGEBACK | A card network chargeback (dispute) case. Progresses through the chargeback stages. |
COMPLIANCE | A compliance case, from pre-compliance through compliance. Progresses through the compliance stages. |
The issuer opens a compliance case to allege a card network rule violation outside the dispute conditions.
A compliance case has no category: its category is null.
Dispute categories
Every chargeback 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
Stages are exposed as objects implementing the CardPaymentDisputeStage interface.
A dispute's stages list holds its chargeback stages or its compliance stages, depending on its type.
Chargeback stages
A chargeback progresses through one to five stages—either party can accept the loss at a stage that allows it, and some network workflows skip stages entirely. Visa fraud and authorization disputes, for example, have no representment stage; see Network differences.
| 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. |
CardPaymentDisputePreArbitrationResponseStage | 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. |
Compliance stages
A compliance case progresses through up to three stages:
| Stage | What it represents |
|---|---|
CardPaymentDisputePreComplianceStage | The issuer alleges a card network rule violation outside the dispute conditions. |
CardPaymentDisputePreComplianceResponseStage | The merchant contests the pre-compliance in full or in part. |
CardPaymentDisputeComplianceStage | The final stage, where the card network makes a binding ruling. |
The merchant answers a pre-compliance by accepting it, or by contesting it in full or in part, which opens the pre-compliance response stage.
No questionnaire applies to compliance stages, so their questionnaire is always null.
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. |
SUBMITTED | The merchant's response for this stage has been filed with the network. The stage is waiting on the issuer or the network, and no merchant action can be taken on it. |
COMPLETED | The stage has been completed. |
EXPIRED | The stage has expired without action. |
WITHDRAWN | The stage was withdrawn by the party that filed it, for example a chargeback or pre-arbitration recalled by the issuer. |
Stage response windows
Every stage carries a deadline field:
| Field | Type | Description |
|---|---|---|
responseDueAt | String (ISO-8601) | The deadline for a response. |
Missing a response deadline typically results in the dispute closing against the merchant.
How disputes resolve
A chargeback 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.
A compliance case can resolve when the merchant accepts the pre-compliance. At the compliance stage, the card network's binding ruling resolves it.
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 at most one active stage, in progress or submitted, and every earlier stage is completed. When a pre-arbitration is withdrawn, the dispute stays under review with no active stage until a new filing arrives:
| Stage status → Dispute status ↓ | PENDING | IN_PROGRESS | SUBMITTED | COMPLETED | EXPIRED | WITHDRAWN |
|---|---|---|---|---|---|---|
INITIATED | Chargeback stage (creation) | — | — | — | — | — |
IN_REVIEW | — | The active stage | The active stage, once the merchant's response is filed | All earlier stages | — | A withdrawn pre-arbitration |
MERCHANT_ACCEPTED | — | — | — | All stages | — | — |
ISSUER_ACCEPTED | — | — | — | All stages | — | — |
TIMED_OUT | — | — | — | — | — | — |
WITHDRAWN | — | — | — | — | — | Chargeback stage (issuer recall) |
CLOSED | — | — | — | All stages (acceptance or arbitration) | — | — |
Read the matrix as follows:
- A resolved dispute is
MERCHANT_ACCEPTED,ISSUER_ACCEPTED, orCLOSEDwith all stagesCOMPLETED. A dispute whose chargeback the issuer withdraws isWITHDRAWN, and so is its chargeback stage. INITIATEDandTIMED_OUTare transitional: a new dispute typically advances toIN_REVIEWas it is created—though a query can catch it earlier, asINITIATEDwith aPENDINGchargeback stage—and a timed-out dispute typically advances toCLOSED. 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 defined for a stage whose response window lapses without action, and theWITHDRAWNdispute status has a matching webhook event. A stage isWITHDRAWNwhen the party that filed it withdraws it, for example a chargeback or pre-arbitration recalled by the issuer. Handle every defined value in your code rather than treating any status as unreachable.