GET/
List existing dispute cases. This endpoint supports sorting and pagination.
Query parameters
| Fields | Description |
|---|---|
| 3ds boolean Optional | Returns dispute cases that involve 3DS. Allowable Values: true, false |
| assignee string Optional | Returns dispute cases associated with the specified assignee. Allowable Values: 255 char max |
| chargeback_token string Optional | Returns dispute cases associated with the specified chargeback. Allowable Values: 36 char max |
| dispute_state array of strings Optional | Returns a comma-separated list of dispute states that will be used to filter the resulting case. Allowable Values: INITIATED, REPRESENTMENT, PRE_ARBITRATION, ARBITRATION, CASE_WON, CASE_LOST, NETWORK_REJECTED, CLOSED, WRITTEN_OFF_ISSUER, WRITTEN_OFF_PROGRAM |
| network_case_number string Optional | Returns dispute cases associated with the specified network case number. Allowable Values: A valid network case number. |
| next_actor string Optional | Returns the dispute cases associated with the specified next actor, such as ISSUER, ACQUIRER, COURT, or DISPUTE_COMPLETED.Allowable Values: An existing next actor. |
| original_transaction_token string Optional | Returns dispute cases associated with the specified token. Allowable Values: 36 char max |
| reason string Optional | Returns disputes that are using the provided dispute reason. Allowable Values: See Dispute case reasons. |
| state string Optional | Returns a comma-separated list of case states that will be used to filter the resulting case. Allowable Values: OPEN, OPEN_WITH_ACTION_REQUIRED, READY, CHARGEBACK_INITIATED, CLOSED |
| type string Optional | Returns cases of the specified type. Allowable Values: DISPUTE |
| user_token string Optional | Returns dispute cases associated with the specified user. Allowable Values: 36 char max |
Response body
| Fields | Description |
|---|---|
| token string Returned | The unique identifier of the dispute case. Allowable Values: 36 char max |
| type string Returned | The type of case. Allowable Values: DISPUTE |
| memo string Returned | Free-form comments about the dispute. Allowable Values: 512 char max |
| user_token string Returned | Token that identifiers the user that made the original transaction. Allowable Values: 36 char max |
| state string Returned | Indicates the current case state. Allowable Values: OPEN, OPEN_WITH_ACTION_REQUIRED, READY, CHARGEBACK_INITIATED, CLOSED |
| assignee string Returned | Indicates who is working on the case. This is updated by the case transition endpoint with reason_code 22 and ASSIGN action. Allowable Values: 255 char max |
| zendesk_ticket_id string Optional | ID for the Zendesk ticket. Allowable Values: 255 char max |
| dispute_details object Returned | The details of the dispute case. Allowable Values: See The dispute_details_response object table. |
| created_time datetime Returned | The time when the dispute case was created. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ |
| last_modified_time datetime Returned | The time when the dispute case was last updated. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ |
The dispute_details_response object
| Fields | Description |
|---|---|
| original_transaction_token string Returned | The token of the original transaction under dispute. Allowable Values: 36 char max |
| original_transaction_type string Returned | The type of the original transaction under dispute. Allowable Values: 255 char max |
| dispute_amount number Returned | The amount of funds under dispute. Allowable Values: Must be less than or equal to the original transaction amount. |
| dispute_amount_change_reason string Returned | The reason the dispute amount has been changed from the transaction amount. Allowable Values: MERCHANT_ISSUED_PARTIAL_REFUND, PARTIAL_DISPUTE, NOT_AS_DESCRIBED_PARTIAL, PARTIAL_SERVICE, PRORATED_REFUND, NOT_AUTHORIZED_FOR_FULL_AMOUNT |
| currency_code string Returned | The currency in which the original transaction was made. Currently, only 480, which is USD, is supported. Allowable Values: 30 char max |
| dispute_reason string Returned | The code describing the reason for the dispute. Allowable Values: See the Dispute case reasons table. |
| dispute_state string Returned | The current dispute state. Once the case’s state has been moved to CHARGEBACK_INITIATED, this field will be updated as it progresses in the backend lifecycle.Allowable Values: INITIATED, REPRESENTMENT, PRE_ARBITRATION, ARBITRATION, CASE_WON, CASE_LOST, NETWORK_REJECTED, CLOSED, WRITTEN_OFF_ISSUER, WRITTEN_OFF_PROGRAM |
| chargeback_token string Returned | Indicates what is the associated chargeback in the legacy system. This is useful to map the current chargeback webhooks back a dispute case. This field is populated once the case state has moved to CHARGEBACK_INITIATED. For Regulation E dispute cases, this value is returned after dispute case creation.Allowable Values: 36 char max |
| network string Returned | The network where the transaction took place. Allowable Values: MASTERCARD |
| acquirer_fee number Returned | The acquirer fee for the transaction. Allowable Values: A valid number. |
| associated_transaction_selection_required boolean Returned | Indicates whether there are any transactions related to the original transaction. Allowable Values: true, false |
| card_token string Returned | Unique identifier that maps back to the card that made the original transaction. Allowable Values: 36 char max |
| network_failure_response string Returned | Indicates the latest error that has occurred while the case is processed. Allowable Values: 255 char max |
| cardholder_contact_date datetime Returned | The date that the cardholder made initial contact regarding the dispute. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ |
| provisional_credit_granted boolean Returned | Indicates whether the provisional credit was granted. Allowable Values: true, false |
| regulation_type string Returned | The regulation type of the disputer case. For Regulation E cases, this value is REG_E.Allowable Values: 255 char max |
| regulation_details object Conditionally returned | Contains the Regulation E configuration that governs the dispute case throughout the lifecycle. Available only if the expanded query parameter was set to regulation_details in the query.Allowable Values: See The regulation details object. |
The regulation_details object
| Fields | Description |
|---|---|
| pc_grant_days_to_act string Conditionally returned | The maximum number of days to grant provisional credit before the dispute case becomes out of compliance. Allowable Values: 255 char max |
| pc_perm_days_to_act string Conditionally returned | The maximum number of days to reverse a cardholder’s provisional credit. If a dispute case is still open with no outcome, the provisional credit cannot be reversed from the cardholder. Allowable Values: 255 char max |
| pc_reversed_coms_days_to_act string Conditionally returned | The maximum number of days to inform a cardholder that the provisional credit will be reversed from the day the case was attempted to be closed. Allowable Values: 255 char max |
| pc_reversed_days_to_act string Conditionally returned | The number of business days that must elapse before the reversal of the provisional credit. Allowable Values: 255 char max |
Sample response body
JSON
{
"count": 2,
"start_index": 0,
"end_index": 1,
"is_more": true,
"data": [
{
"created_time": "2024-10-15T09:35:16Z",
"last_modified_time": "2025-01-03T19:02:17Z",
"token": "my_case_token",
"type": "DISPUTE",
"memo": "",
"user_token": "my_user_token",
"state": "CLOSED",
"assignee": "Ross Geller",
"zendesk_ticket_id": "1234",
"dispute_details": {
"original_transaction_token": "my_txn_token",
"original_transaction_type": "authorization.clearing 3DS",
"dispute_amount": 33.99,
"currency_code": "GBP",
"dispute_reason": "CARDHOLDER_DISPUTE",
"dispute_state": "CASE_WON",
"chargeback_token": "my_cb_token",
"network": "MASTERCARD",
"network_case_number": "my_network_case_number",
"card_token": "my_card_token",
"cardholder_contact_date": "2024-08-19T07:16:00Z",
"provisional_credit_granted": false,
"acquirer_fee": 0.0000,
"associated_transaction_selection_required": false,
"network_case_status_details": {
"created_time": "2024-10-15T10:45:03Z",
"last_modified_time": "2025-01-03T19:02:16Z",
"case_status": "Closed",
"current_case_amount": 33.99,
"next_actor": "DISPUTE_COMPLETED",
"days_to_act": -194,
"last_action_date": "2024-10-15T00:00:00Z",
"case_opened_date": "2024-10-15T00:00:00Z",
"last_refresh_date": "2025-01-03T19:02:17Z",
"allowable_actions": []
},
"network_failure_response": ""
},
"case_tags": []
},
{
"created_time": "2024-10-15T13:23:34Z",
"last_modified_time": "2024-11-11T16:28:59Z",
"token": "my_case_token",
"type": "DISPUTE",
"memo": "",
"user_token": "my_user_token",
"state": "CLOSED",
"assignee": "Ross Geller",
"zendesk_ticket_id": "1234",
"dispute_details": {
"original_transaction_token": "my_txn_token",
"original_transaction_type": "authorization.clearing 3DS",
"dispute_amount": 667.73,
"currency_code": "GBP",
"dispute_reason": "CARDHOLDER_DISPUTE",
"dispute_state": "CASE_LOST",
"network": "MASTERCARD",
"network_case_number": "my_network_case_number",
"card_token": "my_card_token",
"cardholder_contact_date": "2024-09-18T17:17:00Z",
"provisional_credit_granted": false,
"acquirer_fee": 0.0000,
"associated_transaction_selection_required": false,
"network_case_status_details": {
"created_time": "2024-10-15T18:47:03Z",
"last_modified_time": "2024-11-14T10:32:03Z",
"case_status": "Closed",
"current_case_amount": 667.73,
"next_actor": "DISPUTE_COMPLETED",
"days_to_act": -194,
"last_action_date": "2024-10-15T00:00:00Z",
"case_opened_date": "2024-10-15T00:00:00Z",
"last_refresh_date": "2024-11-14T10:32:03Z",
"allowable_actions": []
}
},
"case_tags": []
}
]
}