Monitoring Disputes
Overview
Subscribers observe acquiring disputes through three mechanisms:
- Subscribing to webhook events using the
CARD_PAYMENT_DISPUTE_*events family. - Looking up
CardPaymentDisputeby ID. - Listing your organization's disputes with the
cardPaymentDisputesconnection.
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:
| Event | When it fires |
|---|---|
CARD_PAYMENT_DISPUTE_PRE_COMPLIANCE_UPDATED | The 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_UPDATED | The pre-compliance response stage transitions, following the merchant's answer to a pre-compliance. |
CARD_PAYMENT_DISPUTE_COMPLIANCE_UPDATED | The 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.
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>"
}
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.