Skip to content

Dispute V2 System Documentation

Overview

The Dispute v2 System consists of two key components:

  • Hydra: Responsible for determining if a transaction can be disputed and if the user has the necessary permissions to perform dispute actions.
  • Dispute: Manages the flow and lifecycle of a dispute once it is initiated.

Hydra Responsibilities

Hydra is responsible for all validation and eligibility checks related to disputes. Its core responsibilities include:

  • Permission Validation: Checks if a user has permission to initiate or take actions on a dispute.
  • Transaction Eligibility:
    • Verifies if a transaction can be disputed (based on flags, types such as preauth, completed, etc.).
    • Determines if actions can be taken on a dispute.
    • Determines which transactions can be disputed, by using BE configurations
  • Timeframe Enforcement: Applies rules for how long after a transaction a dispute can be initiated or resolved.
  • Re-disputation Logic: Controls whether a transaction can be disputed again (only if previous disputes were marked as Denied status).

Dispute Responsibilities

Dispute handles the operational flow of the dispute lifecycle. It does not enforce business rules — it purely executes valid dispute transitions and actions once initiated.

Dispute Status Lifecycle

There are five statuses in a dispute's lifecycle:

  1. Reported
  2. Ongoing
  3. Denied
  4. Rejected
  5. Approved

1. Reported

  • First status when a dispute is initiated.
  • Requires a Transaction ID.
  • The transaction is validated via the Transaction Service.
  • All subsequent actions use the Dispute ID and Transaction ID.

Actions by Risk Team

Once a dispute is in the Reported state, the Risk Team can perform one of the following actions through Hydra:

  • Deny:
    • Dispute is marked as Denied.
    • No money movement.
    • The dispute can be reported again if requested via support.
  • Approve:
    • Dispute is marked as Approved.
    • A permanent credit is issued to the user.
    • The dispute is resolved.
  • Mark as Ongoing:
    • Dispute is marked as Ongoing.
    • A provisional credit is issued to the user.
    • The case remains open and under investigation (typically involving external providers).

Ongoing State Actions

While in Ongoing status, RT can take the following actions:

  • Reject:
    • Reverses the provisional credit.
    • Marks the dispute as Rejected.
    • Final state. Dispute cannot be re-initiated.
  • Approve:
    • Reverses the provisional credit.
    • Issues a new permanent credit.
    • Marks the dispute as Approved.
    • Final state. Dispute cannot be re-initiated.

Status Transition Summary

Current Status Action New Status Credit Impact
Reported Deny Denied No credit issued
Reported Approve Approved Permanent credit issued
Reported Ongoing Ongoing Provisional credit issued
Ongoing Reject Rejected Provisional credit reversed
Ongoing Approve Approved Provisional credit reversed + permanent credit issued

Important Notes

  • All business logic and permission checks are handled by Hydra.
  • Dispute is only responsible for processing the dispute flow.
  • Once a dispute reaches Approved or Rejected, it is considered final.
  • Only Denied disputes may be reported again — this logic is controlled by Hydra.