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 |
| associated_transaction_required boolean Optional | Returns dispute cases that have any associated transactions. Allowable Values: true, false |
| 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 |
| program_short_code string Returned | Indicates what program the case belongs to. Allowable Values: 10 char max |
| user_token string Returned | Token that identifies the user that made the original transaction. Allowable Values: 36 char max |
| business_token string Returned | The token of the business involved in the dispute case. 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 |
| type_change_time datetime Optional | When the type was changed. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ |
| dispute_details object Returned | The details of the dispute case. Allowable Values: See The dispute details response object. |
| created_time datetime Returned | The time when the dispute case was created. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ |
| updated_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_id integer Returned | The ID 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 840 is supported. There is a known caveat for multi-currency programs: disputes are created in the transaction currency as expected, but chargebacks might currently default to the program-level default currency rather than the transaction currency. Allowable Values: 30 char max |
| dispute_reason string Returned | The code describing the reason for the dispute. Allowable Values: See The dispute_details.dispute_reason field 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 to 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: VISA |
| network_case_number string Returned | The network identifier for the dispute case. Allowable Values: A valid network case number. |
| 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 |
| processing_error_type_dispute_details object Returned | An object providing details about processing error disputes. Allowable Values: See The processing_error_type_dispute_details object table. |
| consumer_dispute_type_dispute_details object Returned | Indicates the latest error that has occurred while the case is processed. Allowable Values: See The consumer_dispute_type_dispute_details object table. |
| network_case_status_details object Returned | Available once the case state has been successfully transitioned to CHARGEBACK_INITIATED.Allowable Values: See The network_case_status_details object table. |
| additional_dispute_details object Optional | An object providing any additional information for a case. Allowable Values: See The additional_dispute_details object table. |
| fraud_dispute_type_details object Returned | Provides any additional information for cases with a fraud dispute reason. Contains the general_fraud_type_dispute_details object, which contains the chip_on_card boolean value, which is set to true if the card used for the original transaction had a chip.Allowable Values: true, false |
| network_failure_response string Returned | Indicates the latest error that has occurred while the case is processed. Allowable Values: 255 char max |
| fraud_category_type_dispute_details object Returned | Additional information regarding a previously submitted fraud report in the network. Allowable Values: See The fraud_category_type_dispute_details object table. |
| fraud_classification_type_dispute_details object Optional | Object that provides details about the fraud type classification to the Visa card network. Allowable Values: See the fraud_classification_type_dispute_details object table. |
| cardholder_contact_date date 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. Set to true whenever a credit has been granted through the Cases endpoint.Allowable Values: true, false |
| regulation_type string Returned | The regulation type of the dispute 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 network_case_status_details object
| Fields | Description |
|---|---|
| network string Returned | Network where the original transaction originated and is being processed. Allowable Values: VISA |
| network_case_number string Returned | Network identifier for the case. Allowable Values: A valid network identifier. |
| case_status string Returned | Network-specific value that represents the status of the case in the network. Allowable Values: A valid status value. |
| current_case_amount number Returned | Current amount that has been disputed in the network. Allowable Values: A valid number. |
| next_actor string Returned | Who is currently expected to act upon the case. Allowable Values: ISSUER, ACQUIRER, DISPUTE_COMPLETED, UNKNOWN |
| days_to_act integer Returned | The number of days left to act for the next_actor before the dispute case defaults.Allowable Values: A valid integer. |
| last_action_date date Returned | When the case was last updated in the network. Allowable Values: Format: yyyy-MM-dd |
| case_opened_date date Returned | Date when the case was opened in the network. Allowable Values: Format: yyyy-MM-dd |
| last_refresh_date date Returned | When the case was last refreshed from the network to the Marqeta system. Allowable Values: Format: yyyy-MM-dd |
| allowable_actions string Returned | The actions allowed for the dispute case in the current dispute state. Allowable Values: SUBMIT, ACCEPT_AND_CLOSE, RESPOND_WITH_PREARB, RESPOND_WITH_PREARB_RESPONSE, RESPOND_WITH_ARB, WAIT, ALLOCATION_ACKNOWLEDGED, REPRESENTMENT_RECEIVED, PREARB_RECEIVED, PREARB_ACCEPTED, PREARB_DECLINED, PREARB_RESPONSE_DECLINED, ADJUSTMENT, CLOSE_WITH_CASE_WON, CLOSE_WITH_NETWORK_REJECTED |
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": 1,
"start_index": 0,
"end_index": 0,
"is_more": true,
"data": [
{
"token": "string",
"type": "DISPUTE",
"memo": "Multiple browser submission",
"program_short_code": "string",
"user_token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"business_token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"state": "OPEN",
"assignee": "string",
"dispute_details": {
"original_transaction_token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"original_transaction_type": "transaction_type",
"dispute_amount": 120.49,
"dispute_amount_change_reason": "MERCHANT_ISSUED_PARTIAL_REFUND",
"currency_code": "840",
"dispute_reason": "SERVICE_NOT_PROVIDED_MERCHANDISE_NOT_RECEIVED",
"dispute_state": "INITIATED",
"chargeback_token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"network": "VISA",
"network_case_number": "string",
"acquirer_fee": 0,
"associated_transaction_selection_required": "true",
"card_token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"network_failure_response": "string",
"processing_error_type_dispute_details": {
"late_presentment_details": {
"account_status": "ACCOUNT_CLOSED"
},
"incorrect_transaction_code_details": {
"how_is_transaction_code_incorrect": "CREDIT_INSTEAD_OF_REVERSAL_OR_ADJUSTMENT",
"explain_why_the_credit_refund_was_processed_in_error": "string"
},
"incorrect_currency_details": {
"incorrect_currency_reason": "CURRENCY_DIFFERENCE",
"what_was_the_correct_currency": 0,
"certification_that_the_cardholder_did_not_agree_to_dynamic_currency_conversion_and_did_not_make_an_active_choice": "string"
},
"incorrect_account_number_details": {
"is_the_account_number_on_the_issuers_master_file": true,
"does_the_account_number_on_the_receipt_match_the_cardholders_account_number_or_token": true
},
"incorrect_transaction_amount_details": {
"what_is_the_amount_on_the_cardholders_receipt": 0,
"what_is_the_currency_on_the_cardholders_receipt": "string"
}
},
"consumer_dispute_type_dispute_details": {
"service_not_provided_merchandise_not_received_details": {
"detailed_description_of_what_was_purchased_and_explanation_of_the_dispute": "string",
"expected_receipt_date": "2022-01-31",
"expected_receipt_time": "2022-01-31",
"did_cardholder_cancel_prior_to_the_expected_date": true,
"cancellation_date": "2022-01-31",
"cancellation_reason": "string",
"did_cardholder_attempt_to_resolve_dispute_with_merchant": true,
"is_attempt_to_resolve_prohibited_by_local_law_or_regulations": true,
"provide_details_of_local_law_or_regulations": "string",
"merchandise_or_services": "MERCHANDISE SERVICES",
"was_merchandise_delivered_to_wrong_location": true,
"address_of_agreed_location": "string",
"did_cardholder_return_merchandise": true,
"date_cardholder_returned_merchandise": "2022-01-31",
"date_merchant_received_returned_merchandise": "2022-01-31",
"did_cardholder_attempt_to_return_merchandise": true,
"date_of_attempted_return": "2022-01-31",
"explain_how_merchandise_was_returned": "string",
"third_party_gift_card_indicator": true,
"visa_commercial_card_virtual_account_indicator": true,
"did_virtual_account_holder_suffer_financial_loss": true,
"did_merchant_cancel_services": true,
"date_merchant_cancelled_services": "2022-01-31",
"explanation_dispute_prior_expected_delivery_date": "string"
},
"cancelled_recurring_transaction_details": {
"cancellation_date": "2022-01-31",
"cancellation_reason": "string",
"date_issuer_informed_merchant_of_account_closure": "2022-01-31"
},
"not_as_described_or_defective_merchandise_details": {
"not_as_described_or_defective": "NOT_AS_DESCRIBED DEFECTIVE",
"merchandise_or_services": "MERCHANDISE SERVICES",
"date_the_cardholder_first_notified_the_issuer_of_the_dispute": "2022-01-31",
"did_the_cardholder_attempt_to_resolve_the_dispute_with_the_merchant": true,
"is_attempt_to_resolve_prohibited_by_local_law_or_regulations": true,
"provide_details_of_local_law_or_regulations": "string",
"did_the_cardholder_return_the_merchandise": true,
"date_cardholder_returned_the_merchandise": "2022-01-31",
"date_merchant_received_the_returned_merchandise": "2022-01-31",
"return_method": "FACE_TO_FACE",
"tracking_number": "string",
"date_of_attempted_return": "2022-01-31",
"provide_a_detailed_description_of_how_the_cardholder_attempted_to_return_and_the_disposition_of_the_merchandise": "string",
"did_the_cardholder_attempt_to_return_the_merchandise": true,
"explain_how_the_merchandise_was_returned": "string",
"cardholder_merchant_previous_negotiation_evidence": true,
"explain_prev_negotiation": "string",
"when_negotiations_begin": "2022-01-31",
"date_merchandise_or_service_was_received": "2022-01-31",
"does_the_dispute_involve_merchandise_or_services_provided_that_do_not_match_the_merchants_verbal_description": true,
"did_the_merchandise_or_services_differ_from_what_was_described_on_the_receipt": true,
"provide_details_of_what_was_ordered_and_not_as_described": "string",
"did_the_cardholder_cancel_the_services": true,
"cancellation_date": "2022-01-31",
"cancellation_reason": "string",
"what_was_ordered_and_how_it_was_damaged_or_defective": "string",
"date_merchandise_was_received": "2022-01-31"
},
"credit_not_processed_details": {
"was_a_credit_voucher_voided_transaction_receipt_or_refund_acknowledgement_given": true,
"is_the_credit_voucher_transaction_receipt_or_refund_acknowledgement_dated": true,
"credit_voucher_transaction_receipt_or_refund_acknowledgement_date": "2022-01-31",
"date_cardholder_returned_cancelled_merchandise": "string"
},
"cancelled_merchandise_or_services_details": {
"merchandise_or_services": "MERCHANDISE SERVICE",
"describe_what_was_purchased": "string",
"date_cardholder_received_or_expected_to_receive_merchandise": "2022-01-31",
"did_the_cardholder_attempt_to_resolve_the_dispute_with_the_merchant": true,
"is_attempt_to_resolve_prohibited_by_local_law_or_regulations": true,
"provide_details_of_local_law_or_regulations": "string",
"did_the_cardholder_return_the_merchandise": true,
"date_of_return": "2022-01-31",
"date_merchant_received_returned_merchandise": "2022-01-31",
"return_method": "FACE_TO_FACE",
"tracking_number": "string",
"explain_how_the_merchandise_was_returned": "string",
"did_the_cardholder_attempt_to_return_the_merchandise": true,
"date_of_attempted_return": "2022-01-31",
"detailed_description_of_how_the_cardholder_attempted_to_return_and_the_disposition_of_the_merchandise": "2022-01-31",
"did_cardholder_cancel": true,
"cancellation_date": "2022-01-31",
"cancellation_reason": "string",
"was_cancellation_policy_provided": true,
"type_of_service": "TIMESHARE",
"date_of_service_or_expected_service": "2022-01-31",
"cancelled_guaranteed_reservation_certification_selection": "string"
}
},
"fraud_dispute_type_details": {
"general_fraud_type_dispute_details": {
"chip_on_card": true
}
},
"fraud_classification_type_dispute_details": {
"fraud_type_classification": "PURCHASE_SCAM"
},
"network_case_status_details": {
"network": "VISA",
"network_case_number": "string",
"case_status": "string",
"current_case_amount": 0,
"next_actor": "ISSUER",
"days_to_act": 0,
"last_action_date": "2022-01-31T18:57:42.890Z",
"case_opened_date": "2022-01-31",
"last_refresh_date": "2022-01-31T18:57:42.890Z",
"allowable_actions": [
"SUBMIT"
]
},
"fraud_category_type_dispute_details": {
"fraud_report_details": {
"fraud_type": "LOST",
"fraud_type_code": "string",
"fraud_report_id": 0,
"fraud_type_category": "string"
}
}
},
"created_time": "2022-01-31T18:57:42.890Z",
"updated_time": "2022-01-31T18:57:42.890Z"
}
]
}