📘
Merchants can utilise this webhook to track users who have filed a disputes realtime

Webhook

When a user files a dispute and as the dispute progresses, we send a webhook DISPUTE_STATUS_UPDATE, which includes the details about the dispute.

Webhook Payload

Fields	Type	Description
type	`string`	Webhook Type: `DISPUTE_STATUS_UPDATE`
signature	`string`	Webhook signature for verification
dispute	`string`	Identifier for the Dispute
data	`Object`	Webhook data
data.id	`string`	Identifier for the Dispute
data.createdAt	`number`	Dispute creation time in unix
data.updatedAt	`number`	Dispute updated time in unix
data.sourceUpdatedAt	`number`	Dispute source updated time in unix
data.livemode	`boolean`	Sandbox/Production
data.email	`string`	Email of user filing the dispute
data.paymentPageId	`string`	Corresponding payment page ID for which dispute is filed

Example Webhook Payload:

{
  "type": "DISPUTE_STATUS_UPDATE",
  "signature": "example_webhook_signature",
  "dispute": "dp_xxxxxx",
  "data": {
    "id": "dp_xxxxxx", 
    "createdAt": 1757374102012,
    "updatedAt": 1757374102112,
    "sourceUpdatedAt": 1757374132012,
    "livemode": true,
    "email": "[email protected]",
    "paymentPageId": "page_xxxxxx"
  }
}

Getting disputes

To fetch a user's disputes, send a GET request:

curl -X GET 'https://api.breeze.cash/v1/disputes' \
  -u "YOUR_API_KEY:" \
  --header 'Content-Type: application/json' \

Filter	Query Parameter	Example Value(s)	Description
Email	`email`	`[email protected]`	Get disputes for a specific user email
Date Range (UTC, Unix)	`dateRange[start]`, `dateRange[end]`	`1718304000`, `1718390400`	Filter disputes received in a date range
Pagination - Offset	`pagination[offset]`	`0`, `20`	The result offset for pagination
Pagination - Limit	`pagination[limit]`	`20`, `50`	The max number of disputes per request

Example: Filter by Email

GET /v1/disputes?email={email}

curl -X GET 'https://api.breeze.cash/v1/[email protected]' \
  -u "YOUR_API_KEY:" \
  --header 'Content-Type: application/json' \

Example: Filter by Date Range (UTC)

GET /v1/disputes?dateRange[start]={startUnix}&dateRange[end]={endUnix}

curl -X GET 'https://api.breeze.cash/v1/disputes?dateRange[start]=1718304000&dateRange[end]=1718390400' \
  -u "YOUR_API_KEY:" \
  --header 'Content-Type: application/json' \

Example: Pagination

GET /v1/disputes?pagination[offset]={offset}&pagination[limit]={limit}

curl -X GET 'https://api.breeze.cash/v1/disputes?pagination[offset]=0&pagination[limit]=20' \
  -u "YOUR_API_KEY:" \
  --header 'Content-Type: application/json' \

A successful response will look like:

{
  "status": "SUCCEEDED",
  "data": {
    "disputes": [
      {
        "id": "dp_0d5b6a9598ebd21b",
        "createdAt": 1715018438370,
        "email": "[email protected]",
        "livemode": false,
        "sourceUpdatedAt": 1715018432000,
      }
    ],
    "count": 1
  }
}