Disputes API: Sample Flows

This article presents possible use cases and corresponding sample flows that you can support. This can be a helpful jumping off point as you plan your implementation.

Monitor dispute lifecycle and respond appropriately

You need to track disputes as they progress through their lifecycle and take appropriate action based on status changes and available actions. This ensures timely responses within PSP and bank deadlines.

To monitor dispute lifecycle and respond appropriately:

  1. Subscribe to Dispute Created and Dispute Updated events to receive real-time notifications when disputes are created or their statuses change. Handle the remaining steps in your event handlers.
  2. To retrieve the dispute, call Get Dispute, specifying the ID from the event data payload.
  3. Check the actions array in the dispute to determine what operations are currently available (ACCEPT or DEFEND) and their respective due dates.
  4. Based on your business logic and the dispute details (reason, amount, seller protection level), decide whether to accept liability or defend the dispute.
    • To accept: Call Accept Dispute before the action's due date to acknowledge liability and resolve the dispute.
    • To defend:
      1. Call Create Dispute Evidence Document and use the upload URL in the response to upload a document that supports your defense. Repeat this step for every document you want to submit.
      2. Call Defend Dispute to submit the evidence documents you uploaded in the previous step.
  5. Monitor the dispute status as it moves to UNDER_REVIEW and eventually resolves as WON or LOST.

Track dispute performance and outcomes

Monitor your dispute resolution performance to identify trends, optimize defense strategies, and understand the financial impact on your business.

To track dispute performance and outcomes:

  1. Analyze disputes over a specific time period by calling Query Disputes with date range filters using createdDate.
  2. Calculate your dispute win rate and identify successful defense patterns by filtering the results based on the status values WON and LOST.
  3. When reviewing the LOST disputes:
    1. Make a list of the IDs of the LOST disputes retrieved in the previous steps.
    2. Call Query Dispute History Records, filtering by the IDs of the LOST disputes.
    3. Review the results to determine which of these disputes were defended and what type of evidence was submitted for each one.
  4. When reviewing the WON disputes:
    1. Make a list of the IDs of the WON disputes retrieved in the previous steps.
    2. Call Query Dispute History Records, filtering by the IDs of the WON disputes.
    3. Review the results to determine what type of evidence was submitted for each one.
  5. Compare the results to identify trends and patterns to improve your strategy in defending disputes.
Did this help?