Skip to main content

Monitoring Disputes

Overview​

Subscribers observe acquiring disputes through three mechanisms:

  • Subscribing to webhook events using the CARD_PAYMENT_DISPUTE_* events family.
  • Looking up CardPaymentDispute by ID.
  • Listing your organization's disputes with the cardPaymentDisputes connection.

Watch for dispute activity​

Subscribe to CARD_PAYMENT_DISPUTE_STATUS_* events to track a dispute's lifecycle transitions. Each fires when the dispute reaches the matching CardPaymentDisputeStatus.

Subscribe to CARD_PAYMENT_DISPUTE_ACTION_REQUIRED for disputes that need a response from you. The STATUS_CLOSED payload's disputeOutcome, when set, carries the final result.

Watch for compliance cases​

Like a chargeback, a compliance case emits CARD_PAYMENT_DISPUTE_STATUS_* and CARD_PAYMENT_DISPUTE_ACTION_REQUIRED events, plus a stage event for each of its compliance stages:

EventWhen it fires
CARD_PAYMENT_DISPUTE_PRE_COMPLIANCE_UPDATEDThe pre-compliance stage transitions. Use CARD_PAYMENT_DISPUTE_ACTION_REQUIRED to tell whether a response is expected from the merchant.
CARD_PAYMENT_DISPUTE_PRE_COMPLIANCE_RESPONSE_UPDATEDThe pre-compliance response stage transitions, following the merchant's answer to a pre-compliance.
CARD_PAYMENT_DISPUTE_COMPLIANCE_UPDATEDThe compliance stage transitions. The card network decides the outcome, and the dispute's final result arrives on a terminal CARD_PAYMENT_DISPUTE_STATUS_* event.

Webhook payloads do not carry the dispute's type. Identify a compliance case in a payload by its stage types: a __typename of CardPaymentDisputePreComplianceStage, CardPaymentDisputePreComplianceResponseStage, or CardPaymentDisputeComplianceStage in the stages list. To read type itself, look up the dispute by ID.

See the Events Reference: Dispute for the full event list, when each fires, and the payload shape.
Not every defined status is currently produced—see the Status Matrix for which statuses occur and where.

Find a dispute​

Look up a dispute directly with node(id:), using the dispute ID from a webhook payload:

Find a Dispute​
Query
query NodeCardPaymentDispute($id: ID!) {
node(id: $id) {
__typename
... on CardPaymentDispute {
id
cardPaymentDisputeStatus
category
type
merchantIdentifier
initiatedAt
closedAt
financialImpact {
value
decimalPlaces
currencyCode
}
networkCaseIdentifier
networkReason {
code
description
}
transactionEvent {
acquirerReferenceNumber
createdAt
}
stages {
__typename
status
amount {
value
decimalPlaces
currencyCode
}
startedAt
responseDueAt
completedAt
questionnaire {
__typename
}
}
}
}
}
Variables
{
"id": "<CARD_PAYMENT_DISPUTE_ID>"
}
⚠️ Please login to execute queries. Visit the dashboard to authenticate.
Result
{
"data": {
"node": {
"__typename": "CardPaymentDispute",
"id": "<CARD_PAYMENT_DISPUTE_ID>",
"cardPaymentDisputeStatus": "IN_REVIEW",
"category": "CONSUMER_DISPUTE",
"type": "CHARGEBACK",
"merchantIdentifier": "<MERCHANT_ID>",
"initiatedAt": "1970-01-01T00:01:00.000Z",
"closedAt": null,
"financialImpact": {
"value": 5000,
"decimalPlaces": 2,
"currencyCode": "USD"
},
"networkCaseIdentifier": "<NETWORK_CASE_ID>",
"networkReason": {
"code": "13.1",
"description": "Reason provided by the card network."
},
"transactionEvent": {
"acquirerReferenceNumber": "24445551234567890123456",
"createdAt": "1970-01-01T00:00:30.000Z"
},
"stages": [
{
"__typename": "CardPaymentDisputeChargebackStage",
"status": "COMPLETED",
"amount": {
"value": 5000,
"decimalPlaces": 2,
"currencyCode": "USD"
},
"startedAt": "1970-01-01T00:01:00.000Z",
"responseDueAt": "1970-01-01T00:11:00.000Z",
"completedAt": "1970-01-01T00:05:00.000Z",
"questionnaire": null
},
{
"__typename": "CardPaymentDisputeRepresentmentStage",
"status": "SUBMITTED",
"amount": {
"value": 5000,
"decimalPlaces": 2,
"currencyCode": "USD"
},
"startedAt": "1970-01-01T00:05:00.000Z",
"responseDueAt": "1970-01-01T00:15:00.000Z",
"completedAt": null,
"questionnaire": {
"__typename": "ConsumerDisputeQuestionnaire"
}
}
]
}
}
}

On CardPaymentDispute, the agentNotes field is restricted to the Highnote Dashboard and is not available to a subscriber API key. Every other field, including stages and each stage's questionnaire, resolves normally.

List disputes​

List your organization's disputes with the cardPaymentDisputes connection. Results are paginated: pass first: 20, page with after, and narrow the results with filterBy.

query ListCardPaymentDisputes {
organizations {
cardPaymentDisputes(first: 20) {
pageInfo {
hasNextPage
endCursor
startCursor
}
edges {
node {
id
cardPaymentDisputeStatus
}
}
}
}
}

Track financial impact​

Highnote tracks the merchant's financial impact of a dispute on the financialImpact field on CardPaymentDispute. Use financialImpact with your transaction and ledger activity as the authoritative source for a given dispute's financial state.

Exact fund movement timing depends on the dispute's network, as well as category and stage.

For the full field-by-field breakdown of dispute categories, stages, and status values, see Categories and Stages. For the evidence questionnaire fields returned on each stage, see Evidence Questionnaires.