Skip to main content

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:

TypeDescription
CHARGEBACKA card network chargeback (dispute) case. Progresses through the chargeback stages.
COMPLIANCEA 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:

CategoryDescription
CONSUMER_DISPUTEDispute categorized as a consumer dispute. Has an optional questionnaire.
PROCESSING_ERRORDispute categorized as a processing error. Has an optional questionnaire.
FRAUDDispute categorized as fraud.
INVALID_AUTHORIZATIONDispute 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:

StatusMeaning
INITIATEDDispute has been initiated.
IN_REVIEWDispute is in review.
TIMED_OUTDispute has timed out due to inaction.
WITHDRAWNDispute has been withdrawn by the party that created it.
CLOSEDDispute is closed.
ISSUER_ACCEPTEDIssuer accepts responsibility for the dispute. Resolved in favor of the merchant.
MERCHANT_ACCEPTEDMerchant 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.

StageWhat it represents
CardPaymentDisputeChargebackStageThe first stage of the dispute where the cardholder, via their issuing bank, disputes a transaction.
CardPaymentDisputeRepresentmentStageThe acquiring merchant challenges the issuer's chargeback by submitting further evidence.
CardPaymentDisputePreArbitrationStageEither party—issuer or merchant—escalates the dispute after representment.
CardPaymentDisputePreArbitrationResponseStageThe 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.
CardPaymentDisputeArbitrationStageThe final stage, where the card network makes a binding decision.

Compliance stages​

A compliance case progresses through up to three stages:

StageWhat it represents
CardPaymentDisputePreComplianceStageThe issuer alleges a card network rule violation outside the dispute conditions.
CardPaymentDisputePreComplianceResponseStageThe merchant contests the pre-compliance in full or in part.
CardPaymentDisputeComplianceStageThe 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:

StatusMeaning
PENDINGThe stage is awaiting action.
IN_PROGRESSThe stage is actively being worked on.
SUBMITTEDThe 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.
COMPLETEDThe stage has been completed.
EXPIREDThe stage has expired without action.
WITHDRAWNThe 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:

FieldTypeDescription
responseDueAtString (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 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 ↓
PENDINGIN_PROGRESSSUBMITTEDCOMPLETEDEXPIREDWITHDRAWN
INITIATEDChargeback stage (creation)—————
IN_REVIEW—The active stageThe active stage, once the merchant's response is filedAll 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, or CLOSED with all stages COMPLETED. A dispute whose chargeback the issuer withdraws is WITHDRAWN, and so is its chargeback stage.
  • 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 defined for a stage whose response window lapses without action, and the WITHDRAWN dispute status has a matching webhook event. A stage is WITHDRAWN when 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.