Disputes
Retrieves a list of dispute cases action details for the specified merchant with optional filters available.
Request Format
``` GET /api/disputes/v2.0/merchantdisputes?fromDate={fromDate}&toDate={toDate} ```
Query Parameters
`fromDate`: Optional. Filter disputes from this date (inclusive). Format: YYYY-MM-DD.
`toDate`: Optional. Filter disputes to this date (inclusive). Format: YYYY-MM-DD.
`cardBrandName`: Optional. Filter disputes by the card brand name (e.g., "Visa", "Mastercard").
`status`: Optional. Filter disputes by their status (e.g., "New Activity", "Awaiting Response").
`pageNumber`: Optional. The page number for pagination (default: 1).
`pageSize`: Optional. The number of items per page (default: 25).
`sort`: Optional. Sorting criteria. By default, disputes are sorted by `DisputeDate` in descending order.
Sorting Options
The `sort` parameter allows specifying the field and direction:
`sort.field`: The field to sort by (see supported columns below).
`sort.direction`: The sorting direction, either "ASC" for ascending or "DESC" for descending.
Supported Sorting Columns
`CardNumber`
`FamilyID`
`CaseNumber`
`Status`
`CardType`
`CaseType`
`OriginalTrxnFundsFlow`
`DisputeAmount`
`DisputeDate`
`MerchantAmount`
`OriginalReferenceNumber`
`Reason`
`ReferenceNumber`
`ResolvedDate`
`RespondBy`
`ResponseDate`
`TransactionAmount`
`TransactionDate`
`TransactionType`
`ItemType`
`ItemTypeDescription`
Sorting Examples
Sort by dispute amount ascending: ```?sort.field.disputeAmount=ASC```
Sort by card number descending: ```?sort.field.cardNumber=DESC```
Sort by transaction date ascending: ```?sort.field.transactionDate=ASC```
Behavior
Returns `200 OK` with a paginated list of disputes matching the criteria.
Returns `400 Bad Request` if the date format is invalid.
Success
Bad Request
Unauthorized
Server Error
GET /api/disputes/v2.0/merchantdisputes HTTP/1.1
Host:
Accept: */*
{
"data": [
{
"resellerHnk": "text",
"resellerDba": "text",
"parentHnk": "text",
"parentDba": "text",
"mid": "text",
"midLegalName": "text",
"midDba": "text",
"familyId": "text",
"caseNumber": "text",
"caseType": "text",
"reason": "text",
"status": "text",
"cardNumber": "text",
"cardType": "text",
"transactionType": "text",
"originalTrxnFundsFlow": "text",
"originalReferenceNumber": "text",
"referenceNumber": "text",
"transactionDate": "text",
"transactionAmount": 1,
"disputeDate": "text",
"disputeAmount": 1,
"merchantAmount": 1,
"respondByDate": "text",
"caseExpirationDate": "text",
"responseDate": "text",
"caseResolvedDate": "text"
}
],
"page": {
"number": 1,
"size": 1,
"sort": {
"field": {
"ANY_ADDITIONAL_PROPERTY": "ASC"
}
},
"first": true,
"last": true,
"totalPages": 1,
"numberOfElements": 1,
"totalElements": 1
}
}Retrieves the full status history of a specific dispute case of merchant.
Response Structure: The returned object includes high-level case details such as: caseNumberThe unique identifier for the dispute case.midThe merchant ID related to the case.midDBA, midLegalNameMerchant DBA and legal entity names.resellerHNK, parentHNKUpstream hierarchy identifiers.caseType, reason, cardNumber, cardTypeTransactional context.statusHistoryAn ordered list (most recent first) of all historical status transitions for the case, including date markers.
Date Formatting: All dates in the response (e.g., transactionDate, caseResolvedDate, respondByDate) are returned in YYYY-MM-DD format as strings.
Behavior:Returns 200 OK when the case exists and the caller has access.Returns 404 Not Found if the case does not exist in the system.Returns 403 Forbidden if the caller is not authorized to access the case.
Example: GET /api/disputes/v2.0/merchantdisputes/2024129033814
The unique dispute case number (e.g., 2024129033814) to retrieve full history for.
Success
Forbidden
Not Found
GET /api/disputes/v2.0/merchantdisputes/{caseNumber} HTTP/1.1
Host:
Accept: */*
{
"resellerHnk": "text",
"resellerDba": "text",
"parentHnk": "text",
"parentDba": "text",
"mid": "text",
"midLegalName": "text",
"midDba": "text",
"familyId": "text",
"caseNumber": "text",
"caseType": "text",
"reason": "text",
"cardNumber": "text",
"cardType": "text",
"transactionType": "text",
"originalTrxnFundsFlow": "text",
"originalReferenceNumber": "text",
"referenceNumber": "text",
"transactionDate": "text",
"transactionAmount": 1,
"caseExpirationDate": "text",
"caseResolvedDate": "text",
"statusHistory": [
{
"status": "text",
"disputeDate": "text",
"disputeAmount": 1,
"merchantAmount": 1,
"respondByDate": "text",
"responseDate": "text"
}
]
}Retrieves the response history for a specific dispute case including comments and associated evidence file names.
Request Format
``` GET /api/disputes/v2.0/merchantdisputes/{caseNumber}/responses ```
Behavior
Returns `200 OK` with full response history if one or more responses exist for the case.
Returns `200 OK` with an empty `responses` array if the case exists but has no merchant responses yet.
Returns `404 Not Found` if the case does not exist or is not accessible by the authenticated merchant.
The case number to fetch responses for. Must be a valid and accessible dispute case (e.g., "CN12345678").
Success
Unauthorized
Forbidden
Not Found
GET /api/disputes/v2.0/merchantdisputes/{caseNumber}/responses HTTP/1.1
Host:
Accept: */*
{
"responses": [
{
"responseId": "text",
"caseNumber": "text",
"merchantNumber": "text",
"response": "text",
"createDateTimeUtc": "2025-11-15T23:11:21.589Z",
"attachments": [
{
"attachmentId": 1,
"fileName": "text"
}
]
}
]
}Last updated
Was this helpful?