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.

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
      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",
      "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": "IN_PROGRESS",
          "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.