Skip to main content
This guide describes the sequence of API requests used in a typical dispute case and how to simulate the full disputes lifecycle within a private sandbox environment.. By the end of this guide, you will understand:
  • The complete disputes lifecycle using the Marqeta Disputes API, from creating and submitting a dispute, to monitoring dispute state changes via webhook events.
  • The sequence of API requests that comprise the disputes lifecycle, including basic payloads and response examples.
  • The different dispute states used by Marqeta and the card networks (Visa, Mastercard, and Pulse), and how these relate to each other.

​
Prerequisites

Before using this guide, ensure that you have performed the following actions:
  • Set up a private sandbox environment with Marqeta.
  • Enabled the disputes API functionality within your private sandbox.
  • Confirmed that you can simulate and clear a transaction within your private sandbox.
The Disputes Sandbox guide contains the following topics:
  • Set up a webhook handler – This topic explains how to create, host, and submit a webhook handler API in the sandbox environment.
The Marqeta platform sends all dispute-related notifications via webhook events. You must setup the webhook handler before attempting to simulate a dispute.