Disputes (Visa)

Use the /cases endpoint to manage transaction disputes on the Visa network. For specific details on how to integrate with the Visa network, see Managing Visa Disputes. For general information on disputes, chargebacks, and best practices, see About Disputes.

Create dispute case

Action: POST
Endpoint: /cases Create a new dispute case by specifying the type and including the type-specific details object.

Body field details

Fields	Description
token string Optional	The unique identifier of the dispute case. If you do not include a token, the system generates a token automatically. Because this token is necessary for use in other API calls, it is recommended that, rather than let the system generate the token, you use a simple string that is easy to remember. This value cannot be updated. Allowable Values: 36 char max
type string Required	The type of case. Allowable Values: `DISPUTE`
memo string Optional	Free-form comments about the dispute. Allowable Values: 512 char max
zendesk_ticket_id string Optional	ID for the Zendesk ticket. Allowable Values: 255 char max
dispute_details object Required	An object describing the disputed transaction, including the reason for the dispute. Allowable Values: See The dispute_details object table.

The dispute_details object

Include this object in your request if the case type is DISPUTE.

Fields	Description
original_transaction_token string Required	The token of the original transaction under dispute. Allowable Values: 36 char max
original_transaction_id integer Optional	The ID of the original transaction under dispute. Allowable Values: Existing transaction ID.
dispute_amount number Required	The amount of funds under dispute. Allowable Values: Must be less than or equal to the original transaction amount.
dispute_amount_change_reason string Conditionally required	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` Required if `dispute_amount` is not equal to transaction amount.
currency_code string Optional	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 Required	The code describing the reason for the dispute. Allowable Values: See The dispute_details.dispute_reason field table.
processing_error_type_dispute_details object Optional	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 Optional	An object providing consumer dispute type details. Allowable Values: See The consumer_dispute_type_dispute_details object table.
duplicate_processing_or_paid_by_other_means_details object Optional	An object providing duplicate processing for paid by other means dispute type details. Allowable Values: See The duplicate_processing_or_paid_by_other_means_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 Optional	An object providing any additional information for a dispute case with a fraud dispute reason. Allowable Values: See The fraud_dispute_type_details object table.
fraud_category_type_dispute_details object Optional	An object providing the fraud type request to the Visa 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 datetime Conditionally required	The date that the cardholder made initial contact regarding the dispute. Required for Regulation E reason codes if the program has been enrolled for Regulation E provisional credit; otherwise, optional. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ
regulation_type string Conditionally required	The regulation type for the dispute. Allowable Values: `REG_E`

The dispute_details.dispute_reason field

The following table describes the possible values for the dispute_details.dispute_reason field.

Dispute Reason and Visa Code	Description
EMV_LIABILITY_SHIFT_COUNTERFEIT_ FRAUD (10.1)	The transaction was completed with a counterfeit card in a card-present environment and qualifies for the EMV liability shift.
EMV_LIABILITY_SHIFT_NON_COUNTERFEIT_ FRAUD (10.2)	The transaction was completed in a card-present environment with a card that was reported lost or stolen and qualifies for the EMV liability shift.
NOT_AUTHORIZED_CARD_PRESENT (10.3)	The cardholder denies authorization of or participation in a key-entered transaction conducted in a card-present environment.
NOT_AUTHORIZED_CARD_ABSENT (10.4)	An unauthorized user initiated the transaction and the card was not present.
NO_AUTHORIZATION (11.3)	- Authorization was required, but not obtained. - The primary account number (PAN) does not exist. - A Card Not Present (CNP) transaction was initially declined but subsequently approved through stand-in processing.
INCORRECT_TRANSACTION_CODE (12.2)	The transaction code is incorrect.
INCORRECT_CURRENCY (12.3)	The currency is incorrect.
INCORRECT_ACCOUNT_NUMBER (12.4)	The account number is incorrect.
INCORRECT_TRANSACTION_AMOUNT (12.5)	The transaction amount is incorrect.
DUPLICATE_PROCESSING_OR_PAID_BY_ OTHER_MEANS (12.6)	A single transaction was processed more than once using the same payment credential on the same transaction date, and for the same transaction amount.
SERVICE_NOT_PROVIDED_MERCHANDISE_NOT_ RECEIVED (13.1)	The goods or services were not provided.
CANCELLED_RECURRING_TRANSACTION (13.2)	A recurring transaction was cancelled.
NOT_AS_DESCRIBED_OR_DEFECTIVE_ MERCHANDISE (13.3)	The merchandise was not as described or defective.
COUNTERFEIT_MERCH (13.4)	The cardholder received counterfeit goods.
MISREPRESENTATION (13.5)	The merchant misrepresented their advertised goods or services.
CREDIT_NOT_PROCESSED (13.6)	A credit was not processed.
CANCELLED_MERCHANDISE_OR_SERVICES (13.7)	Merchandise or services were cancelled.
ORIGINAL_CREDIT_NOT_ACCEPTED (13.8)	The cardholder did not or could not accept an original credit transaction.
NON_RECEIPT_OF_CASH_OR_LOAD_ TRANSACTION_VALUE_AT_ATM (13.9)	The cardholder did not receive the full cash withdrawal or received only partial amount.
FRAUD_REPORT	Report fraud to the Visa network.

The processing_error_type_dispute_details object

Fields	Description
late_presentment_details object Conditionally required	An object providing late presentment details. Allowable Values: See The late_presentment_details object table.
incorrect_transaction_code_details object Conditionally required	An object providing incorrect transaction code details. Allowable Values: See The incorrect_transaction_code_details object table.
incorrect_currency_details object Conditionally required	An object providing incorrect currency details. Allowable Values: See The incorrect_currency_details object table.
incorrect_account_number_details object Conditionally required	An object providing incorrect account number details. Allowable Values: See The incorrect_account_number_details object table.
incorrect_transaction_amount_details object Conditionally required	An object providing incorrect transaction amount details. Allowable Values: See The incorrect_transaction_amount_details object table.
duplicate_processing_or_paid_by_other_means_details object Conditionally required	An object providing details about duplicate processing or paid by other means. Allowable Values: See The duplicate_processing_or_paid_by_other_means_details object table.

The late_presentment_details object

Fields	Description
account_status string Conditionally required	The account status. Whether this field is optional or required depends on previous answers provided by the cardholder. To determine whether this field is required, see the decision tree for Processing Errors in Managing Visa Disputes. Allowable Values: `ACCOUNT_CLOSED`, `CREDIT_PROBLEM`, `FRAUD`, `NONSUFFICIENT_FUNDS`

The incorrect_transaction_code_details object

Fields	Description
how_is_transaction_code_incorrect string Conditionally required	The token of the original transaction under dispute. Whether this field is optional or required depends on previous answers provided by the cardholder. To determine whether this field is required, see the decision tree for Processing Errors in Managing Visa Disputes. Allowable Values: `CREDIT_INSTEAD_OF_REVERSAL_OR_ADJUSTMENT`, `CREDIT_POSTED_AS_DEBIT`, `DEBIT_POSTED_AS_CREDIT`
explain_why_the_credit_refund_was_processed_in_error string Conditionally required	An explanation for why the credit refund was incorrectly processed. Whether this field is optional or required depends on previous answers provided by the cardholder. To determine whether this field is required, see the decision tree for Processing Errors in Managing Visa Disputes. Allowable Values:

The incorrect_currency_details object

Fields	Description
incorrect_currency_reason string Conditionally required	The reason for the incorrect currency. Whether this field is optional or required depends on previous answers provided by the cardholder. To determine whether this field is required, see the decision tree for Processing Errors in Managing Visa Disputes. Allowable Values: `CURRENCY_DIFFERENCE`, `DCC_DISPUTE`
what_was_the_correct_currency integer Conditionally required	An explanation for why the credit refund was incorrectly processed. Whether this field is optional or required depends on previous answers provided by the cardholder. To determine whether this field is required, see the decision tree for Processing Errors in Managing Visa Disputes. Allowable Values: An ISO 4217 currency number
certification_that_the_cardholder_did_ not_agree_to_dynamic_currency_ conversion_and_did_not_make_an_ active_choice string Conditionally required	Indicates that the cardholder did not agree to or make an active choice for dynamic currency conversion. Whether this field is optional or required depends on previous answers provided by the cardholder. To determine whether this field is required, see the decision tree for Processing Errors in Managing Visa Disputes. Allowable Values: `true`, `false`

The incorrect_account_number_details object

Fields	Description
is_the_account_number_on_the_issuers_master_file boolean Conditionally required	Indicates whether the cardholder’s account number is also in the issuer’s file. Whether this field is optional or required depends on previous answers provided by the cardholder. To determine whether this field is required, see the decision tree for Processing Errors in Managing Visa Disputes. Allowable Values: `true`, `false`
does_the_account_number_on_the_ receipt_match_the_cardholders_account_ number_or_token boolean Conditionally required	Indicates whether the account numbers match. Whether this field is optional or required depends on previous answers provided by the cardholder. To determine whether this field is required, see the decision tree for Processing Errors in Managing Visa Disputes. Allowable Values: `true`, `false`

The incorrect_transaction_amount_details object

Fields	Description
what_is_the_amount_on_the_cardholders_receipt number Conditionally required	The amount on the cardholder’s receipt. To determine whether this field is required, see the decision tree for Processing Errors in Managing Visa Disputes. Allowable Values: 32 bytes
what_is_the_currency_on_the_cardholders_receipt string Conditionally required	The currency on the cardholder’s receipt. To determine whether this field is required, see the decision tree for Processing Errors in Managing Visa Disputes. Allowable Values: A valid currency code.
is_the_dispute_due_to_the_difference_ between_quoted_price_and_actual_ charges_made_by_the_merchant boolean Conditionally required	Indicates whether the dispute appeared due to the difference between quoted price and actual charges made by the merchant. To determine whether this field is required, see the decision tree for Processing Errors in Managing Visa Disputes. Allowable Values: `true`, `false`

The consumer_dispute_type_dispute_details object

Fields	Description
service_not_provided_merchandise_not_ received_details object Conditionally required	An object describing service or merchandise not provided details. Allowable Values: See The service_not_provided_merchandise_not_received_details object table.
cancelled_recurring_transaction_details object Conditionally required	An object providing cancelled recurring transaction details. Allowable Values: See The cancelled_recurring_transaction_details object table.
not_as_described_or_defective_ merchandise_details object Conditionally required	An object providing not as described or defective merchandise details. Allowable Values: See The not_as_described_or_defective_merchandise_details object table.
credit_not_processed_details object Conditionally required	An object providing credit not processed details. Allowable Values: See The credit_not_processed_details object table.
cancelled_merchandise_or_services_ details object Conditionally required	An object providing cancelled merchandise or service details. Allowable Values: See The cancelled_merchandise_or_services_details object table.

The service_not_provided_merchandise_not_received_details object

Fields	Description
detailed_description_of_what_was_ purchased_and_explanation_of_ the_dispute string Conditionally required	A description of what was purchased and explanation of the dispute. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes. Allowable Values:
expected_receipt_date date Conditionally required	The expected date of receipt. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes. Allowable Values: Format: yyyy-MM-dd
expected_receipt_time string Conditionally required	The expected time of receipt. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes. Allowable Values: Format: hh-mm-ss
did_cardholder_cancel_prior_to_ the_expected_date boolean Conditionally required	Indicates whether the cardholder cancelled before the expected date. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes. Allowable Values: `true`, `false`
cancellation_date date Conditionally required	The date the service was canceled. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes. Allowable Values: Format: yyyy-MM-dd
cancellation_reason string Conditionally required	The reason the transaction was cancelled. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes. Allowable Values:
did_cardholder_attempt_to_resolve_ dispute_with_merchant boolean Conditionally required	Indicates whether the cardholder attempted to resolve the dispute with the merchant. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes. Allowable Values: `true`, `false`
is_attempt_to_resolve_prohibited_by_ local_law_or_regulations boolean Conditionally required	Indicates whether the attempt to resolve the dispute is prohibited by local laws or regulations. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes. Allowable Values: `true`, `false`
provide_details_of_local_law_or_ regulations string Conditionally required	A description of the local laws or regulations that prohibit resolution of the dispute. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes. Allowable Values:
merchandise_or_services string Conditionally required	Indicates whether the dispute is over merchandise or services. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes. Allowable Values: `MERCHANDISE`, `SERVICES`
was_merchandise_delivered_to_wrong_ location boolean Conditionally required	Indicates whether merchandise was delivered to the wrong location. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes. Allowable Values: `true`, `false`
address_of_agreed_location string Conditionally required	The address where merchandise was intended to be delivered. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes. Allowable Values: 255 char max
did_cardholder_return_merchandise boolean Conditionally required	Indicates whether the cardholder returned the merchandise. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes. Allowable Values: `true`, `false`
date_cardholder_returned_merchandise date Conditionally required	If the cardholder returned the merchandise, the date it was returned. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes. Allowable Values: Format: yyyy-MM-dd
date_merchant_received_returned_ merchandise date Conditionally required	The date the merchant received the returned merchandise. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes. Allowable Values: Format: yyyy-MM-dd
did_cardholder_attempt_to_return_ merchandise boolean Conditionally required	Indicates whether the cardholder attempted to return the merchandise to the merchant. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes. Allowable Values: `true`, `false`
date_of_attempted_return date Conditionally required	The date the cardholder attempted to return the merchandise to the merchant. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes. Allowable Values: Format: yyyy-MM-dd
explain_how_merchandise_was_ returned string Conditionally required	Describes how the merchandise was returned. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes. Allowable Values:
third_party_gift_card_indicator boolean Conditionally required	Indicates whether the purchase is a third-party gift card without an expiration date, where the merchandise or services were not provided by the third party due to insolvency or bankruptcy. Allowable Values: `true`, `false`
visa_commercial_card_virtual_account_ indicator boolean Conditionally required	Indicates whether the dispute involves a Visa Commercial Card Virtual Account. Allowable Values: `true`, `false`
did_virtual_account_holder_suffer_ financial_loss boolean Conditionally required	Indicates whether the virtual account holder suffered a financial loss. Allowable Values: `true`, `false`
did_merchant_cancel_merchandise boolean Conditionally required	Indicates whether merchant canceled merchandise. Allowable Values: `true`, `false`
date_merchant_cancelled_merchandise date Conditionally required	Date merchant provider cancelled merchandise. Required if `did_merchant_cancel_merchandise` is true. Allowable Values: Format: yyyy-MM-dd
did_merchant_cancel_services boolean Conditionally required	Indicates whether merchant/travel provider canceled services. Allowable Values: `true`, `false`
date_merchant_cancelled_services Date Conditionally required	Date merchant/travel provider cancelled services. Required if `did_merchant_cancel_services` is true. Allowable Values: Format: yyyy-MM-dd
explanation_dispute_prior_expected_ delivery_date String Conditionally required	Explanation of dispute initiated prior to the expected delivery date. Allowable Values:

The cancelled_recurring_transaction_details object

Fields	Description
date_cardholder_withdrew_permission_to_charge_the_payment_credential date Conditionally required	The date the cardholder withdrew permission to charge the payment credential. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes. Allowable Values: Format: yyyy-MM-dd
cancellation_reason string Conditionally required	The reason the cardholder canceled the recurring transaction. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes. Allowable Values:
date_issuer_informed_merchant_of_ account_closure date Conditionally required	The date the card issuer informed the merchant that the account was closed. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes. Allowable Values: Format: yyyy-MM-dd
contact_merchant_details_physical_address object Conditionally required	The physical address of the merchant. Allowable Values: Valid `contact_merchant_details_physical_address` object
contact_method_merchant_in_person_ind boolean Conditionally required	Indicates if the merchant was contacted in person. Allowable Values: `true`, `false`
contact_method_merchant_email_ind boolean Conditionally required	Indicates if the merchant was contacted by email. Allowable Values: `true`, `false`
contact_method_merchant_mail_ind boolean Conditionally required	Indicates if the merchant was contacted by physical mail. Allowable Values: `true`, `false`
contact_merchant_details_application_name string Conditionally required	The application name. Allowable Values: 255 char max
contact_method_merchant_webform_ind boolean Conditionally required	Indicates if the merchant was contacted by webform. Allowable Values: `true`, `false`
contact_merchant_details_phone_number string Conditionally required	The phone number used to contact the merchant. Allowable Values: Valid phone number
contact_merchant_details_email_address string Conditionally required	The email address used to contact the merchant. Allowable Values: Valid email address
contact_method_merchant_SMS_ind string Conditionally required	Indicates if the merchant was contacted by SMS. Allowable Values: `true`, `false`
contact_method_with_merchant_ind boolean Conditionally required	Indicates if the method for contacting the merchant was provided. Allowable Values: `true`, `false`
contact_method_merchant_call_center_ind boolean Conditionally required	Indicates if the merchant was contacted by a call center. Allowable Values: `true`, `false`
other_form_of_payment_ind boolean Optional	Indicates if another form of payment was provided. Allowable Values: `true`, `false`
other_form_of_payment_desc string Conditionally required	Description of the other form of payment. Required if `other_form_of_payment_ind` is `true`. Allowable Values: 255 char max

The not_as_described_or_defective_merchandise_details object

Fields	Description
merchant_refuse_advise string Conditionally required	Provides clarification as to why merchant refused advise. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes. Allowable Values: `MERCHANT_REFUSED_RETURN_AUTHORIZATION`, `MERCHANT_REFUSED_TO_ACCEPT_RETURNED_MERCHANDISE`, `MERCHANT_INFORMED_CARDHOLDER_NOT_TO_RETURN_MERCHANDISE`
not_as_described_or_defective string Conditionally required	Indicates whether the merchandise was not as described or defective. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes. Allowable Values: `NOT_AS_DESCRIBED`, `DEFECTIVE`
merchandise_or_services string Conditionally required	Indicates whether the transaction involves merchandise or services. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes. Allowable Values: `MERCHANDISE`, `SERVICES`
date_the_cardholder_first_notified_ the_issuer_of_the_dispute date Conditionally required	The date the cardholder first notified the card issuer of the dispute. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes. Allowable Values: Format: yyyy-MM-dd
did_the_cardholder_attempt_to_ resolve_the_dispute_with_the_ merchant boolean Conditionally required	Indicates whether the cardholder attempted to resolve the dispute with the merchant. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes. Allowable Values: `true`, `false`
is_attempt_to_resolve_prohibited_ by_local_law_or_regulations boolean Conditionally required	Indicates whether the attempt to resolve the dispute is prohibited by local laws or regulations. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes. Allowable Values: `true`, `false`
provide_details_of_local_law_ or_regulations string Conditionally required	A detailed explanation of local laws or regulations that prevent resolution. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes. Allowable Values:
did_the_cardholder_return_the_ merchandise boolean Conditionally required	Indicates whether the cardholder returned the merchandise. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes. Allowable Values: `true`, `false`
date_cardholder_returned_the_ merchandise date Conditionally required	The date the cardholder returned the merchandise. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes. Allowable Values: Format: yyyy-MM-dd
date_merchant_received_the_returned_ merchandise date Conditionally required	The date the merchant received the returned merchandise. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes. Allowable Values: Format: yyyy-MM-dd
return_method string Conditionally required	The method used to return the merchandise. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes. Allowable Values: `FACE_TO_FACE`, `FED_EX`, `DHL`, `UPS`, `POSTAL_SERVICE`, `OTHER`
tracking_number string Conditionally required	The tracking number of the returned merchandise. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes. Allowable Values:
date_of_attempted_return date Conditionally required	The date the return was attempted. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes. Allowable Values: Format: yyyy-MM-dd
provide_a_detailed_description_ of_how_the_cardholder_attempted_ to_return_and_the_disposition_ of_the_merchandise string Conditionally required	A detailed description of how the cardholder attempted to return them merchandise and its current disposition. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes. Allowable Values:
did_the_cardholder_attempt_to_return_ the_merchandise boolean Conditionally required	Indicates whether the cardholder attempted to return the merchandise to the merchant. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes. Allowable Values: `true`, `false`
explain_how_the_merchandise_ was_returned string Conditionally required	A description of how the merchandise was returned by the cardholder. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes. Allowable Values:
cardholder_merchant_previous_negotiation_evidence boolean Conditionally required	Indicates whether the cardholder and merchant have negotiated. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes. Allowable Values: `true`, `false`
explain_prev_negotiation string Conditionally required	A description of the negotiation between the cardholder and the merchant. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes. Allowable Values:
when_negotiations_begin string Conditionally required	The date when negotiations between the cardholder and merchant began. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes. Allowable Values: Format: yyyy-MM-dd
date_merchandise_or_service_was_ received date Conditionally required	The date the merchandise or service was received by the cardholder. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes. Allowable Values: Format: yyyy-MM-dd
does_the_dispute_involve_ merchandise_or_services_provided_ that_do_not_match_the_merchants_ verbal_description boolean Conditionally required	Indicates whether the dispute involves merchandise or services that do not match the merchant’s verbal description. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes. Allowable Values: `true`, `false`
did_the_merchandise_or_services_ differ_from_what_was_described_ on_the_receipt boolean Conditionally required	Indicates whether the merchandise or services differ from what was described on the receipt. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes. Allowable Values: `true`, `false`
provide_details_of_what_was_ordered_ and_not_as_described string Conditionally required	A description of what the cardholder ordered and how it is different from what was described by the merchant. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes. Allowable Values:
did_the_cardholder_cancel_the_services boolean Conditionally required	Indicates whether the cardholder cancelled the services. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes. Allowable Values: `true`, `false`
cancellation_date date Conditionally required	The date the services were cancelled. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes. Allowable Values: Format: yyyy-MM-dd
cancellation_reason string Conditionally required	The reason the services were cancelled. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes. Allowable Values:
what_was_ordered_and_how_it_was_ damaged_or_defective string Conditionally required	Describes what was ordered and whether it was damaged or defective. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes. Allowable Values:
date_merchandise_was_received date Conditionally required	The date the merchandise was received. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes. Allowable Values: Format: yyyy-MM-dd

The credit_not_processed_details object

Fields	Description
was_a_credit_voucher_voided_ transaction_receipt_or_refund_ acknowledgement_given boolean Conditionally required	Indicates whether a credit voucher voided the transaction receipt or a refund acknowledgment was given. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes. Allowable Values: `true`, `false`
is_the_credit_voucher_transaction_ receipt_or_refund_acknowledgement_ dated boolean Conditionally required	Indicates whether the credit voucher transaction receipt or refund acknowledgment has a date. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes. Allowable Values: `true`, `false`
credit_voucher_transaction_receipt_or_ refund_acknowledgement_date date Conditionally required	The date of the credit voucher transaction receipt or refund acknowledgment. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes. Allowable Values: Format: yyyy-MM-dd
date_cardholder_returned_cancelled_ merchandise Date Conditionally required	Date the cardholder cancelled the service or returned the merchandise. Allowable Values: Format: yyyy-MM-dd

The cancelled_merchandise_or_services_details object

Fields	Description
merchandise_or_services string Conditionally required	Indicates whether the dispute is about merchandise or services. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes. Allowable Values: `MERCHANDISE`, `SERVICE`
describe_what_was_purchased string Conditionally required	A description of what was purchased. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes. Allowable Values:
date_cardholder_received_or_expected_ to_receive_merchandise date Conditionally required	The date the cardholder received or expected to receive the merchandise. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes. Allowable Values: Format: yyyy-MM-dd
did_the_cardholder_attempt_to_resolve_ the_dispute_with_the_merchant boolean Conditionally required	Indicates whether the cardholder attempted to resolve the dispute with the merchant. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes. Allowable Values: `true`, `false`
is_attempt_to_resolve_prohibited_by_ local_law_or_regulations boolean Conditionally required	Indicates whether the attempt to resolve the dispute is prohibited by local laws or regulations. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes. Allowable Values: `true`, `false`
provide_details_of_local_law_ or_regulations string Conditionally required	A description of local laws or regulations that affect the dispute. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes. Allowable Values:
did_the_cardholder_return_ the_merchandise boolean Conditionally required	Indicates whether the cardholder returned the merchandise. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes. Allowable Values: `true`, `false`
date_of_return date Conditionally required	The date the merchandise was returned by the cardholder. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes. Allowable Values: Format: yyyy-MM-dd
date_merchant_received_returned_ merchandise date Conditionally required	The date the returned merchandise was received by the merchant. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes. Allowable Values: Format: yyyy-MM-dd
return_method string Conditionally required	The method used by the cardholder to return the merchandise. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes. Allowable Values: `FACE_TO_FACE`, `FED_EX`, `DHL`, `UPS`, `POSTAL_SERVICE`, `OTHER`
tracking_number string Conditionally required	The tracking number of the returned merchandise. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes. Allowable Values:
explain_how_the_merchandise_was_ returned string Conditionally required	Describes how the merchandise was returned by the cardholder. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes. Allowable Values:
did_the_cardholder_attempt_to_return_ the_merchandise boolean Conditionally required	Indicates whether the cardholder attempted to return the merchandise. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes. Allowable Values: `true`, `false`
date_of_attempted_return date Conditionally required	The date of the attempted return of merchandise to the merchant. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes. Allowable Values: Format: yyyy-MM-dd
detailed_description_of_how_ the_cardholder_attempted_ to_return_and_the_disposition_ of_the_merchandise string Conditionally required	A detailed description of how the cardholder attempted to return the merchandise and its current disposition. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes. Allowable Values:
did_cardholder_cancel boolean Conditionally required	Indicates whether the cardholder canceled. Allowable Values: `true`, `false`
cancellation_date date Conditionally required	The date the cardholder canceled the purchase. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes. Allowable Values: Format: yyyy-MM-dd
cancellation_reason string Conditionally required	The reason for the cancellation. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes. Allowable Values:
was_cancellation_policy_provided boolean Conditionally required	Indicates whether a cancellation policy was provided to the cardholder. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes. Allowable Values: `true`, `false`
type_of_service string Conditionally required	The type of service. Allowable Values: `TIMESHARE`, `GUARANTEED_RESERVATION`, `OTHER`
date_of_service_or_expected_service date Conditionally required	The date of the service or expected service. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes. Allowable Values: Format yyyy-MM-dd
cancelled_guaranteed_reservation_ certification_selection string Conditionally required	Indicates the cancelled guaranteed reservation selection. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes. Allowable Values: `CARDHOLDER_PROPERLY_CANCELLED`, `CARDHOLDER_ATTEMPTED_TO_CANCEL_WITHIN_24_HOURS_OF_CONFIRMATION`, `MERCHANT_BILLED_A_NO_SHOW_TRANSACTION_FOR_MORE_THAN_ONE_DAYS_ACCOMODATION`
merchant_refuse_advise string Conditionally required	Provides clarification as to why merchant refused advise. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes. Allowable Values: `MERCHANT_REFUSED_RETURN_AUTHORIZATION`, `MERCHANT_REFUSED_TO_ACCEPT_RETURNED_MERCHANDISE`, `MERCHANT_INFORMED_CARDHOLDER_NOT_TO_RETURN_MERCHANDISE`

The duplicate_processing_or_paid_by_other_means_details object

Fields	Description
error_type string Required	Indicates whether the dispute is a duplicate or paid by other means. For more information on whether this field is required, see the decision tree for Processing errors in Managing Visa Disputes. Allowable Values: `DUPLICATE`, `PAID_BY_OTHER_MEANS`
both_transactions_in_same_account boolean Required	Indicates whether both transactions are for the same merchant and on the same card. Allowable Values: `true`, `false`
other_transaction_reference_token string Conditionally required	The clearing token of the duplicate original transaction. Required when `both_transactions_in_same_account` is set to `true`. Allowable Values: 36 char max
other_visa_transaction_reference_id string Conditionally required	Used if the other transaction has been made with a different Visa card that has not been issued by Marqeta. Required when `both_transactions_in_same_account` is set to `true` and `transaction_reference_token` is not provided. Allowable Values:
other_visa_transaction_mcsn string Conditionally required	The MCSN of the duplicate transaction. Required when `visa_transaction_reference_id` is provided and the `visa_transaction_reference_id` has an MSCN field. Allowable Values:
transaction_in_different_visa_account boolean Conditionally required	This should be set if the other transaction is for the same merchant and on a different Visa card owned by the same issuer or cardholder. Required when `both_transactions_in_same_account` is set to `false`. Allowable Values: `true`, `false`
is_other_transaction_with_same_merchant boolean Conditionally required	Indicates whether the duplicate transaction is with the same merchant. Required when `transaction_in_different_visa_account` is set to `false`. Allowable Values: `true`, `false`
provided_proof_of_other_means_type string Conditionally required	The type of proof provided that the transaction was paid by other means. Required when `is_other_transaction_with_same_merchant` is set to `false`. For `CASH_RECEIPT`, `THIRD_PARTY_VOUCHER`, `OTHER_CARD_STATEMENT`, and `OTHER` a document must be uploaded and attached when submitting to the network. `COPY_OF_CHECK` must include a copy of the front and back of the check. Allowable Values: `OTHER_TRANSACTION_ARN`, `OTHER_TRANSACTION_INFORMATION`, `CASH_RECEIPT`, `COPY_OF_CHECK`, `THIRD_PARTY_VOUCHER`, `OTHER_CARD_STATEMENT`, `OTHER`
is_evidence_of_merchant_passed_funds_provided boolean Conditionally required	If the user inputs `true`, the attachments docs are required. If user inputs `false`, the case will be network rejected when submitted to the network and will be moved to `OPEN_WITH_ACTION_REQUIRED`. Required when `provided_proof_of_other_means_type` is set to `THIRD_PARTY_VOUCHER`. Allowable Values: `true`, `false`
cardholder_attempted_to_resolve boolean Conditionally required	Indicates whether the cardholder attempted to resolve the dispute with the merchant. Required when `error_type` is set to `PAID_BY_OTHER_MEANS` and when either `transaction_in_different_visa_account` is set to `true` or if `is_other_transaction_with_same_merchant` is set to `true`. Optional when `error_type` is set to `DUPLICATE` and when either `transaction_in_different_visa_account` is set to `true` or if `is_other_transaction_with_same_merchant` is set to `true`. Allowable Values: `true`, `false`
is_attempt_to_resolve_prohibited_by_local_law boolean Conditionally required	Indicates whether the attempt to resolve prohibited by local law or regulations. Required when `cardholder_attempted_to_resolve` is set to false. Visa requires for the cardholder to attempt to resolve the issue before submitting to the network. If the user inputs `false` and `cardholder_attempted_to_resolve` is also `false`, the case will be network rejected when submitted to the network and will be moved to `OPEN_WITH_ACTION_REQUIRED`. Allowable Values: `true`, `false`
other_visa_transaction_arn string Conditionally required	The ARN from other transaction if it was paid with a Visa card. Required when `provided_proof_of_other_means_type` is set to `OTHER_TRANSACTION_ARN`. Allowable Values:
other_visa_transaction_information string Conditionally required	The transaction information from the other transaction if it was paid with a Visa card. Required when `provided_proof_of_other_means_type` is set to `OTHER_TRANSACTION_INFORMATION`. Allowable Values:

The additional_dispute_details object

Fields	Description
explanation_of_credit string Optional	Explanation of credit. Allowable Values:
fraud_category_report_details object Optional	the fraud type request to the Visa network. Allowable Values: See The fraud_category_type_dispute_details object table.

The fraud_category_type_dispute_details object

Fields	Description
fraud_type string Optional	The fraud type of a fraud dispute case. Allowable Values: `LOST`, `STOLEN`, `CARD_NOT_RECEIVED_AS_ISSUED`, `FRAUDULENT_APPLICATION`, `ISSUER_REPORTED_COUNTERFEIT`, `MISCELLANEOUS`, `FRAUDULENT_USE_OF_ACCOUNT_NUMBER`, `ACQUIRER_REPORTED_COUNTERFEIT`, `INCORRECT_PROCESSING`, `ACCOUNT_OR_CREDENTIALS_TAKEOVER`, `MERCHANT_MISREPRESENTATION`, `MANIPULATION_OF_ACCOUNT_HOLDER`

Note
Do not use the FRAUDULENT_APPLICATION type when the dispute reason is either NOT_AUTHORIZED_CARD_PRESENT (10.3) or NOT_AUTHORIZED_CARD_ABSENT (10.4). The Visa card network will reject such disputes.

The fraud_classification_type_dispute_details object

Fields	Description
fraud_type_classification string Optional	Classification of the fraud type. This field is required if you are submitting a fraudulent account funding transaction and the `fraud_type` is `MANIPULATION_OF_ACCOUNT_HOLDER`. Allowable Values: `PURCHASE_SCAM`, `INVESTMENT_SCAM`, `ROMANCE_SCAM`, `ADVANCE_FEE_SCAM`, `INVOICE_OR_MANDATE_SCAM`, `CEO_FRAUD_SCAM`, `IMPERSONATION_SCAM`, `CHARITY_SCAM`, `HOLIDAY_AND_TICKET_SCAM`, `UTILITY_SCAM`, `LOAN_SCAM`, `PARENT_GRANDPARENT_RELATIVE_SCAM`, `JOB_SCAM`

The fraud_dispute_type_details object

An object providing additional information for cases with a fraud dispute reason.

Fields	Description
general_fraud_type_dispute_details object Conditionally required	An object describing general fraud type details. Allowable Values: See The general_fraud_type_dispute_details object table.

The general_fraud_type_dispute_details object

Fields	Description
chip_on_card boolean Conditionally required	This field is set to true if the card used for the original transaction had a chip. Allowable Values: `True`, `False`

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 identifiers 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 table.
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

Sample request body

JSON

{
  "token": "string",
  "type": "DISPUTE",
  "memo": "string",
  "zendesk_ticket_id": "string",
  "dispute_details": {
    "original_transaction_token": "string",
    "original_transaction_id": 0,
    "dispute_amount": 0,
    "dispute_amount_change_reason": "MERCHANT_ISSUED_PARTIAL_REFUND",
    "currency_code": "string",
    "dispute_reason": "SERVICE_NOT_PROVIDED_MERCHANDISE_NOT_RECEIVED",
    "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-07-19",
        "expected_receipt_time": "string",
        "did_cardholder_cancel_prior_to_the_expected_date": true,
        "cancellation_date": "2022-07-19",
        "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-07-19",
        "date_merchant_received_returned_merchandise": "2022-07-19",
        "did_cardholder_attempt_to_return_merchandise": true,
        "date_of_attempted_return": "2022-07-19",
        "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_merchandise": false,
        "date_merchant_cancelled_services": " ",
        "did_merchant_cancel_services": true,
        "date_merchant_cancelled_services": "2022-07-19",
        "explanation_dispute_prior_expected_delivery_date": "string"
      },
      "cancelled_recurring_transaction_details": {
        "merchant_refuse_advise": "MERCHANT_REFUSED_RETURN_AUTHORIZATION",
        "cancellation_date": "2022-07-19",
        "cancellation_reason": "string",
        "date_issuer_informed_merchant_of_account_closure": "2022-07-19"
      },
      "not_as_described_or_defective_merchandise_details": {
        "merchant_refuse_advise": "MERCHANT_REFUSED_RETURN_AUTHORIZATION",
        "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-07-19",
        "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-07-19",
        "date_merchant_received_the_returned_merchandise": "2022-07-19",
        "return_method": "FACE_TO_FACE",
        "tracking_number": "string",
        "date_of_attempted_return": "2022-07-19",
        "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-07-19",
        "date_merchandise_or_service_was_received": "2022-07-19",
        "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-07-19",
        "cancellation_reason": "string",
        "what_was_ordered_and_how_it_was_damaged_or_defective": "string",
        "date_merchandise_was_received": "2022-07-19"
      },
      "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-07-19",
        "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-07-19",
        "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-07-19",
        "date_merchant_received_returned_merchandise": "2022-07-19",
        "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-07-19",
        "detailed_description_of_how_the_cardholder_attempted_to_return_and_the_disposition_of_the_merchandise": "2022-07-19",
        "did_cardholder_cancel": true,
        "cancellation_date": "2022-07-19",
        "cancellation_reason": "string",
        "was_cancellation_policy_provided": true,
        "type_of_service": "TIMESHARE",
        "date_of_service_or_expected_service": "2022-07-19",
        "cancelled_guaranteed_reservation_certification_selection": "string",
        "merchant_refuse_advise": "MERCHANT_REFUSED_RETURN_AUTHORIZATION"
      }
    },
    "additional_dispute_details": {
      "explanation_of_credit": "string",
      "fraud_category_report_details": {
        "fraud_type": "LOST"
      }
    },
    "fraud_dispute_type_details": {
      "general_fraud_type_dispute_details": {
        "chip_on_card": true
      }
    },
    "fraud_category_type_dispute_details": {
      "fraud_type": "LOST"
    },
    "cardholder_contact_date": "2022-07-19T22:36:47.451Z"
  }
}

Sample response body

JSON

{
  "token": "string",
  "type": "DISPUTE",
  "memo": "string",
  "program_short_code": "string",
  "user_token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "business_token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "state": "OPEN",
  "assignee": "string",
  "zendesk_ticket_id": "string",
  "type_change_time": "string",
  "dispute_details": {
    "original_transaction_token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "original_transaction_id": 0,
    "original_transaction_type": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "dispute_amount": 0,
    "dispute_amount_change_reason": "MERCHANT_ISSUED_PARTIAL_REFUND",
    "currency_code": "string",
    "dispute_reason": "SERVICE_NOT_PROVIDED_MERCHANDISE_NOT_RECEIVED",
    "dispute_reason_code": "string",
    "dispute_state": "INITIATED",
    "chargeback_token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "network": "MASTERCARD",
    "network_case_number": "string",
    "acquirer_fee": 0,
    "associated_transaction_selection_required": true,
    "card_token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "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-07-19",
        "expected_receipt_time": "string",
        "did_cardholder_cancel_prior_to_the_expected_date": true,
        "cancellation_date": "2022-07-19",
        "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-07-19",
        "date_merchant_received_returned_merchandise": "2022-07-19",
        "did_cardholder_attempt_to_return_merchandise": true,
        "date_of_attempted_return": "2022-07-19",
        "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_merchandise": false,
        "date_merchant_cancelled_services": " ",
        "did_merchant_cancel_services": true,
        "date_merchant_cancelled_services": "2022-07-19",
        "explanation_dispute_prior_expected_delivery_date": "string"
      },
      "cancelled_recurring_transaction_details": {
        "merchant_refuse_advise": "MERCHANT_REFUSED_RETURN_AUTHORIZATION",
        "cancellation_date": "2022-07-19",
        "cancellation_reason": "string",
        "date_issuer_informed_merchant_of_account_closure": "2022-07-19"
      },
      "not_as_described_or_defective_merchandise_details": {
        "merchant_refuse_advise": "MERCHANT_REFUSED_RETURN_AUTHORIZATION",
        "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-07-19",
        "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-07-19",
        "date_merchant_received_the_returned_merchandise": "2022-07-19",
        "return_method": "FACE_TO_FACE",
        "tracking_number": "string",
        "date_of_attempted_return": "2022-07-19",
        "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-07-19",
        "date_merchandise_or_service_was_received": "2022-07-19",
        "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-07-19",
        "cancellation_reason": "string",
        "what_was_ordered_and_how_it_was_damaged_or_defective": "string",
        "date_merchandise_was_received": "2022-07-19"
      },
      "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-07-19",
        "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-07-19",
        "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-07-19",
        "date_merchant_received_returned_merchandise": "2022-07-19",
        "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-07-19",
        "detailed_description_of_how_the_cardholder_attempted_to_return_and_the_disposition_of_the_merchandise": "2022-07-19",
        "did_cardholder_cancel": true,
        "cancellation_date": "2022-07-19",
        "cancellation_reason": "string",
        "was_cancellation_policy_provided": true,
        "type_of_service": "TIMESHARE",
        "date_of_service_or_expected_service": "2022-07-19",
        "cancelled_guaranteed_reservation_certification_selection": "string",
        "merchant_refuse_advise": "MERCHANT_REFUSED_RETURN_AUTHORIZATION"
      }
    },
    "network_case_status_details": {
      "network": "MASTERCARD",
      "network_case_number": "string",
      "case_status": "string",
      "current_case_amount": 0,
      "next_actor": "ISSUER",
      "days_to_act": 0,
      "last_action_date": "2022-07-19T22:36:47.451Z",
      "case_opened_date": "2022-07-19",
      "last_refresh_date": "2022-07-19T22:36:47.451Z",
      "allowable_actions": [
        "SUBMIT"
      ]
    },
    "additional_dispute_details": {
      "explanation_of_credit": "string",
      "fraud_category_report_details": {
        "fraud_report_details": {
          "fraud_type": "LOST",
          "fraud_type_code": "string",
          "fraud_report_id": 0,
          "fraud_type_category": "string"
        }
      }
    },
    "fraud_dispute_type_details": {
      "general_fraud_type_dispute_details": {
        "chip_on_card": true
      }
    },
    "network_failure_response": "string",
    "fraud_category_type_dispute_details": {
      "fraud_report_details": {
        "fraud_type": "LOST",
        "fraud_type_code": "string",
        "fraud_report_id": 0,
        "fraud_type_category": "string"
      }
    },
    "cardholder_contact_date": "2022-07-18T22:24:46.251Z",
    "provisional_credit_granted": true,
    "regulation_type": "REG_E"
  },
  "created_time": "2022-07-19T22:36:47.451Z",
  "updated_time": "2022-07-19T22:36:47.451Z"
}

Sample request body (FRAUD)

The following shows a sample request body for submitting a fraud report.

JSON

{
    "dispute_details": {
        "dispute_reason": "FRAUD_REPORT",
        "dispute_amount": 50,
        "fraud_category_type_dispute_details": {
            "fraud_type": "FRAUDULENT_APPLICATION"
        },
        "original_transaction_token": "1c0a45c3-8212-4524-b679-610cf4d231a8"
      },

    "memo": "This is a QE test",
    "type": "DISPUTE"
}

Sample response body (FRAUD)

The following shows a sample response body for submitting a fraud report.

JSON

{
    "created_time": "2022-10-10T14:13:49Z",
    "last_modified_time": "2022-10-10T14:13:49Z",
    "token": "qa01-2054",
    "type": "DISPUTE",
    "memo": "This is a QE test",
    "program_short_code": "qa01",
    "user_token": "2ccc806a-d9a4-4357-aa2b-897ec86c409f",
    "state": "CLOSED",
    "dispute_details": {
        "original_transaction_token": "1c0a45c3-8212-4524-b679-610cf4d231a8",
        "original_transaction_type": "authorization.clearing",
        "dispute_amount": 50.00,
        "currency_code": "USD",
        "dispute_reason": "FRAUD_REPORT",
        "network": "VISA",
        "network_case_number": "5155784824",
        "card_token": "8db8321d-56f5-42b4-a9c3-f7d3a64bc92a",
        "provisional_credit_granted": false,
        "acquirer_fee": 0.0000,
        "associated_transaction_selection_required": true
    }
}

Submit a batch of possibly associated transactions

Action: POST
Endpoint: /cases/{token}/associated_transactions/selections Submit a batch of possibly associated transactions to the VISA Network. If the dispute case has any associated transactions, these are updated in the associated_transactions field for each transaction. If the submission is successful, the network_submission_status field is set to SUBMITTED. You can globally set credit_change_reason and auth_change_reason values for all transactions included in the post. These values can be overridden for each associated transaction. Each associated transaction is validated before submitting the batch to the network. If one associated transaction fails validation, the entire request fails. The failure occurs at the first violation, and the validation of the remaining payload is not validated. The response includes the list of affected associated transactions. If one of the potentially associated transactions has already been submitted to the network, an error is returned. The response provides a list of transactions. Those with the associated field set to true are associated with the dispute case.

Warning
Once an associated transaction selection form has been submitted, it cannot be resubmitted. The form can be updated.

URL path parameters

Fields	Description
token string Required	The dispute case token. Allowable Values: 36 char max

Body field details

Fields	Description
network_type string Required	The card network. This should match the dispute case token provided in the path. Allowable Values: `VISA`
credit_change_reason string Optional	The credit change reason. This value is globally applied to all transactions in the list unless overridden by the `credit_change_reason` value for a specific transaction in the associated transaction object. Pattern: `^\d+$` Allowable Values: A valid credit change reason.
auth_change_reason string Optional	The auth change reason. This value is globally applied to all transactions in the list unless overridden by the `auth_change_reason` value for a specific transaction in the associated transaction object. Pattern: `^\d+$` Allowable Values: A valid authorization change reason.
associated_transactions array of objects Required	An array of transactions associated with the current dispute case. Details for each transaction are defined in the `associated_transactions` object table. Allowable Values: A valid array of associated_transaction objects.

The associated_transactions object

Fields	Description
associated boolean Required	Indicates whether the transaction is associated with the given transaction. Allowable Values: `true`, `false`
associated_transaction_token string Required	The unique identifier for the associated transaction. Allowable Values: A valid associated transaction token.
credit_change_reason string Optional	The credit change reason for the specific associated transaction. This value overrides the `credit_change_reason` global value. Pattern: `^\d+$` Allowable Values: A valid credit change reason.
auth_change_reason string Optional	The auth change reason for the specific associated transaction. This value overrides the `auth_change_reason` global value. Allowable Values: A valid authorization change reason.

Associated transactions response

A response is generated when all transactions included in the request have been submitted to the network. A 200 response code is generated with the following fields:

Fields	Description
network_type string Returned	The card network. This matches the dispute case token provided in the path. Allowable Values: `VISA`
token string Returned	Unique identifier of the associated transaction on the Marqeta platform. Allowable Values: 36 char max
case_token string Returned	Token that indicates which dispute case this Associated Transaction belongs to. Allowable Values: 36 char max
network_phase string Returned	The network dispute state. Allowable Values: `DISPUTE`
transaction_date datetime Returned	The date and time of the transaction. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ
transaction_amount number Returned	The amount of money associated with this transaction. Allowable Values: A valid transaction amount.
transaction_currency string Returned	Three-digit ISO 3166-1 numeric code for the currency used in the transaction. Allowable Values: 30 char max
merchant_name string Returned	The name of the merchant associated with this transaction. Allowable Values: 22 char max
network_submission_status string Returned	The status of the associated transaction on the network. Allowable Values: `PENDING`—The initial value before the associated transaction is submitted to the network. `SUBMISSION_FAILED`—The submission of the associated transaction to the network failed. `SUBMITTED`—The associated transaction was successfully submitted to the network. `UPDATE_FAILED`—The update to the associated transaction failed.
first_network_submission_time datetime Returned	The date and time when the associated transaction was first submitted to the network. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ
last_network_submission_time datetime Returned	The date and time when the associated transaction was updated at the network. This value is updated every time the associated transaction is updated to the network. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ
transaction_type string Returned	Visa-specific transaction type (for network use only). Allowable Values: 255 char max
auth_code string Returned	Visa-specific authorization code (for network use only). Allowable Values:
network_selection_form object Returned	Visa-specific network selection form, containing the `credit_change_reason` and `auth_change_reason` code values that were set during the associated transaction selection in the `POST` or `PUT` request. These values are overwritten whenever an attempt is made to update the selection. Allowable Values: See The network_selection_form object.

The network_selection_form object

Fields	Description
associated boolean Returned	Indicates whether the transaction is associated with the dispute case. This field is set once the selection is submitted. If `true`, the transaction is associated with the dispute case. Allowable Values: `True`, `False`
credit_change_reason string Returned	The credit change reason. Pattern: `^\d+$` Allowable Values: A valid credit change reason code.
auth_change_reason string Returned	The authorization change reason. Pattern: `^\d+$` Allowable Values: A valid auth change reason code.

Submission errors

Error Code	Description
400	Indicates one of the following has occurred: One of the associated transaction forms was already submitted. A `network_type` value does not match the one for the dispute. One of the associated transaction forms has a missing required field.
404	Indicates one of the following has occurred: The dispute case token was not found. One of the associated transactions was not found. The user attempts to submit a form for a dispute case that doesn’t belong to the specified program short code. One of the associated transactions does not belong to the dispute case.

Sample request body

JSON

"network_type": "VISA",
  "credit_change_reason": "8",
  "auth_change_reason": "83952347647997785959177943288119589987930259773787787402577751279976256354634112680576",
  "associated_transactions": [
    {
      "associated": true,
      "associated_transaction_token": "string",
      "credit_change_reason": "31320146819959147412182438616152094955519754833",
      "auth_change_reason": "19825646390525201297707582594987938135506677612006399332111987193044"
    }
  ]
}

Sample response body

JSON

{
  "associated_transactions": [
    {
      "network_type": "VISA",
      "token": "string",
      "case_token": "string",
      "network_phase": "DISPUTE",
      "transaction_date": "2022-07-21T20:05:19.469Z",
      "transaction_amount": 0,
      "transaction_currency": "string",
      "merchant_name": "string",
      "network_submission_status": "PENDING",
      "first_network_submission_time": "2022-07-21T20:05:19.469Z",
      "last_network_submission_time": "2022-07-21T20:05:19.469Z",
      "transaction_type": "string",
      "auth_code": "string",
      "network_selection_form": {
        "associated": true,
        "credit_change_reason": "1931821026291098997994936518692286249429118358411883813460319553290652759495697632223762249903373317",
        "auth_change_reason": "88807041187533992807677186332619"
      }
    }
  ]
}

Update submitted associated transactions

Action: PUT
Endpoint: /cases/{token}/associated_transactions/selections Update a list of selection forms that have already been submitted for a given dispute case. You can globally set credit_change_reason and auth_change_reason values for all transactions included in the post. These values can be overridden for each associated transaction. Each associated transaction is validated before submitting the batch to the network. If one associated transaction fails validation, the entire request fails. The failure occurs at the first violation and the remaining payload is not validated. The response includes the list of affected associated transactions. If one of the potentially associated transactions has already been submitted to the network, an error is returned. The response provides a list of transactions. Those with the associated field set to true are associated with the case.

URL path parameters

Fields	Description
token string Required	The dispute case token. Allowable Values: 36 char max

Body field details

For a description of the body field details and the fields in the associated_transactions object, see The associated_transactions object.

Update associated transactions response

For a description of the fields in the response, see Associated transactions response. When all associated forms have been updated, a 200 response code is generated with the fields in the response.

Submission errors

Error Code	Description
400	Indicates one of the following has occurred: The user attempted to update the associated transactions of a dispute case that has moved to the `CHARGEBACK_INITIATED` state. (Phase 2) The user attempted to update the associated transactions of a dispute case with a dispute transition that has moved beyond prearbitration. The user attempted to update an associated transaction with a network type that doesn’t match the network type for the dispute. One of the associated transactions has a missing required field.
404	Indicates one of the following has occurred: The dispute case token was not found. One of the associated transactions was not found. The user attempted to update a dispute case that doesn’t belong to the specified program. One of the associated transactions does not belong to the dispute case.

Sample request body

JSON

{
  "network_type": "VISA",
  "credit_change_reason": "66733283294439907772978420740446990478244312974548240509905403454256830653300576453097992718048",
  "auth_change_reason": "6700644900821340007833045221217107468620657600979029382163103999185490",
  "associated_transactions": [
    {
      "associated": true,
      "associated_transaction_token": "string",
      "credit_change_reason": "119335977632844717862380939473877155180707611424947603253800488969535484445104268638719205",
      "auth_change_reason": "21436322989173875475680301320453226327437272571912420748705468"
    }
  ]
}

Sample response body

JSON

{
  "associated_transactions": [
    {
      "network_type": "VISA",
      "token": "string",
      "case_token": "string",
      "network_phase": "DISPUTE",
      "transaction_date": "2022-07-21T20:16:09.353Z",
      "transaction_amount": 0,
      "transaction_currency": "string",
      "merchant_name": "string",
      "network_submission_status": "PENDING",
      "first_network_submission_time": "2022-07-21T20:16:09.353Z",
      "last_network_submission_time": "2022-07-21T20:16:09.353Z",
      "transaction_type": "string",
      "auth_code": "string",
      "network_selection_form": {
        "associated": true,
        "credit_change_reason": "029039246087712053593482311219773792437645087345397147249441224416802068472501671465461",
        "auth_change_reason": "19350516797465538433816692388789084359411154131712658490518433762316944090146"
      }
    }
  ]
}

List associated transactions

Action: GET
Endpoint: /cases/{token}/associated_transactions Get a list of transactions associated with a given dispute case. Use the network_phase query field to help distinguish associated transactions between the different phases in the network.

URL path parameter

Fields	Description
token string Required	The dispute case token. Allowable Values: 36 char max

Query parameter

Fields	Description
network_submission_status string Optional	The status of the associated transaction on the network. Allowable Values: `DISPUTE`

Associated transactions list response

For a description of the fields in the associated transactions list response, see Associated transactions response. When all associated transactions have been retrieved, a 200 response code is generated.

Submission errors

Error Code	Description
400	Indicates that one of the query parameters has invalid values.
404	Indicates one of the following has occurred: The dispute case token was not found. The user attempted to list the associated transactions of a dispute case that doesn’t belong to their program.

Sample response body

JSON

{
  "count": 0,
  "start_index": 0,
  "end_index": 0,
  "is_more": true,
  "data": [
    {
      "network_type": "VISA",
      "token": "string",
      "case_token": "string",
      "network_phase": "DISPUTE",
      "transaction_date": "2022-07-21T20:28:41.432Z",
      "transaction_amount": 0,
      "transaction_currency": "string",
      "merchant_name": "string",
      "network_submission_status": "PENDING",
      "first_network_submission_time": "2022-07-21T20:28:41.432Z",
      "last_network_submission_time": "2022-07-21T20:28:41.432Z",
      "transaction_type": "string",
      "auth_code": "string",
      "network_selection_form": {
        "associated": true,
        "credit_change_reason": "23081975578411443042951322911018191732213156837897130269",
        "auth_change_reason": "700115018601402049966548711489543545098647136546172313772959758014134282366596585958058"
      }
    }
  ]
}

Retrieve dispute case

Action: GET
Endpoint: /cases/{token} Retrieve a specific dispute case.

URL path parameters

Fields	Description
token string Required	The token of the dispute case to retrieve. Allowable Values: 36 char max

Query parameter

Fields	Description
expand string Optional	If the `regulation_type` field is set to `REG_E`, adds the `regulation_details` fields inside `dispute_details` in the response. For more information, see The regulation_details object. Allowable Values: `regulation_details`

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 identifiers 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

JSON

{
  "count": 0,
  "start_index": 0,
  "end_index": 0,
  "is_more": true,
  "data": [
    {
      "token": "string",
      "type": "DISPUTE",
      "memo": "string",
      "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": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "dispute_amount": 0,
        "dispute_amount_change_reason": "MERCHANT_ISSUED_PARTIAL_REFUND",
        "currency_code": "string",
        "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-03-21",
            "expected_receipt_time": "2022-03-21",
            "did_cardholder_cancel_prior_to_the_expected_date": true,
            "cancellation_date": "2022-03-21",
            "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-03-21",
            "date_merchant_received_returned_merchandise": "2022-03-21",
            "did_cardholder_attempt_to_return_merchandise": true,
            "date_of_attempted_return": "2022-03-21",
            "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-03-21",
            "explanation_dispute_prior_expected_delivery_date": "string"
          },
          "cancelled_recurring_transaction_details": {
            "cancellation_date": "2022-03-21",
            "cancellation_reason": "string",
            "date_issuer_informed_merchant_of_account_closure": "2022-03-21"
          },
          "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-03-21",
            "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-03-21",
            "date_merchant_received_the_returned_merchandise": "2022-03-21",
            "return_method": "FACE_TO_FACE",
            "tracking_number": "string",
            "date_of_attempted_return": "2022-03-21",
            "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-03-21",
            "date_merchandise_or_service_was_received": "2022-03-21",
            "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-03-21",
            "cancellation_reason": "string",
            "what_was_ordered_and_how_it_was_damaged_or_defective": "string",
            "date_merchandise_was_received": "2022-03-21"
          },
          "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-03-21",
            "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-03-21",
            "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-03-21",
            "date_merchant_received_returned_merchandise": "2022-03-21",
            "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-03-21",
            "detailed_description_of_how_the_cardholder_attempted_to_return_and_the_disposition_of_the_merchandise": "2022-03-21",
            "did_cardholder_cancel": true,
            "cancellation_date": "2022-03-21",
            "cancellation_reason": "string",
            "was_cancellation_policy_provided": true,
            "type_of_service": "TIMESHARE",
            "date_of_service_or_expected_service": "2022-03-21",
            "cancelled_guaranteed_reservation_certification_selection": "string"
          }
        },
        "fraud_dispute_type_details": {
          "general_fraud_type_dispute_details": {
            "chip_on_card": true
          }
        },
        "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-03-21T15:46:20.825Z",
          "case_opened_date": "2022-03-21",
          "last_refresh_date": "2022-03-21T15:46:20.825Z",
          "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-03-21T15:46:20.825Z",
      "updated_time": "2022-03-21T15:46:20.825Z"
    }
  ]
}

List dispute cases

Action: GET
Endpoint: /cases 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 identifiers 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 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_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 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 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 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": "480",
        "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"
    }
  ]
}

Create dispute case transition

Action: POST
Endpoint: /cases/{token}/transitions Transition a dispute case to another state or initiate a chargeback against the dispute case. A dispute case transition is an event that changes the state of a dispute case and triggers other related events. The new state of the dispute case and which related events are triggered is determined by the action defined in the dispute case transition.

URL path parameters

Fields	Description
token string Required	The token of the dispute case associated with the transition you want to create. Allowable Values: 36 char max Send a `GET` request to `/cases` to retrieve dispute case tokens.

Body field details

Fields	Description
token string Optional	The unique identifier of the dispute case transition. If you do not include a token, the system generates a token automatically. Allowable Values: 36 char max
action string Required	The action taken on the dispute case. Allowable Values: See Dispute case transitions.
reason_code string Required	Identifies the standardized reason for the transition. Allowable Values: See The transition reason_code field table.
created_by string Required	The user ID or name of the user who created the transition. Allowable Values: 255 char max
assignee string Optional	The user ID or name of the user assigned to the dispute case. Allowable Values: 255 char max
memo string Optional	Additional notes about the transition. Allowable Values: 16777215 char max
transition_details object Required	An object containing the transition details. Allowable Values: See The transition_details object.

The transition_details object

Fields	Description
chargeback_details object Required	An object containing the chargeback details. Allowable Values: See The chargeback_details object.

The chargeback_details object

Fields	Description
attached_contents string Required	List of content tokens that should be submitted to the network when initiating a chargeback. The content tokens should be associated to the case. For more information about the uploading case documents, see Create dispute case content. Allowable Values: A list of valid UUID tokens.

Dispute case transitions

Dispute case transitions represent the workflow during the creation, information gathering, and submission processes a dispute case. The dispute case transition actions and resulting states are described below.

Action	Reason Code	Resulting State	Description
CREATE	N/A	`OPEN`, `OPEN_WITH_ACTION_REQUIRED`	Creates a new dispute case. A default action when a `POST` request is sent to the `/cases` endpoint. The `OPEN_WITH_ACTION_REQUIRED` state results if additional information is needed from the user. For programs that are enabled for Regulation E, this action and reason code returns an error for a Regulation E dispute and sets `provisionalCreditGranted` to `true`.
RE_OPEN	N/A	`OPEN`	Reopens a dispute case to get additional information or documents. Dispute case state changes to `OPEN`.
CHARGEBACK_CREDIT	28	`CHARGEBACK_INITIATED`	Sends a `POST` request to the `\cases` endpoint with `credit_user` set to `true`. Set `reason_description` as the value of `dispute_reason` and `channel` as `ISSUER_AUTOMATED` when creating the chargeback. Dispute case state changes to `CHARGEBACK_INITIATED` if no additional information is required. The `OPEN_WITH_ACTION_REQUIRED` state results if additional information is needed from the user before the chargeback can be submitted to the network. Only for programs that are not enabled for Regulation E.
CHARGEBACK_NO_CREDIT	29	`CHARGEBACK_INITIATED`	Sends a `POST` request to the `\cases` endpoint with `credit_user` set to `false`. Set `reason_description` as the value of `dispute_reason` and `channel` as `ISSUER_AUTOMATED` when creating the chargeback. Dispute case state changes to `CHARGEBACK_INITIATED` if no additional information is required. The `OPEN_WITH_ACTION_REQUIRED` state results if additional information is needed from the user before the chargeback can be submitted to the network. Only for programs that are not enabled for Regulation E. For programs that are enabled for Regulation E, this action and reason code return an error for a Regulation E dispute.
CHARGEBACK_SUBMIT	51	`CHARGEBACK_INITIATED`	Submitting dispute to the network. This applies only to programs that are enabled for Regulation E and for a Regulation E dispute. If provisional credit has not been granted, this returns an error. For programs that are not enabled for Regulation E, this returns an error.
REVIEW	N/A	`READY`	Dispute case is ready to review. Dispute case state changes to `READY`.
ASSIGN	N/A	No change	Assigns a dispute case to a user. An `assignee` value is required. Does not change dispute case state.
KYC_OVERRIDE	N/A	`CLOSED`	Documents are verified and the case is being closed.
CLOSE	41	`CLOSED`	Closes the dispute case. The case was won. Dispute case state changes to `CLOSED`. For all types of dispute cases, this action cannot be triggered until `dispute_state` is in a `CASE_WON` state.
CLOSE	42	`CLOSED`/`PENDING_CLOSED`	Closes the dispute case. The case was lost. For non-Regulation E cases, this results in the `CLOSED` state. For Regulation E cases, this results in the `PENDING_CLOSED` state.
CLOSE	45	`CLOSED`	Closes the dispute case. Dispute case state changes to `CLOSED`. This reason code indicates that the case will be closed and written off using funds from the program account.
DOCUMENTS_DELETED	N/A	No change	Invalid documents were uploaded, documents are not in a readable format or quality, or documents are corrupted and not human readable.
REINSTATE_USER	N/A	`CLOSED`	Failed to reinstate the user.
REINSTATE_BUSINESS	N/A	`CLOSED`	Failed to reinstate the business.
WITHDRAW_AND_CLOSE	40	`CLOSED`	No further action is needed, closing the case by withdrawing. This action can only be taken from the `OPEN` or `OPEN_WITH_ACTION_REQUIRED` state and when provisional credit has not been granted.
WRITE_OFF	N/A	No change	Written off either by user or program.
GRANT_CREDIT	N/A	No change	Granting provisional credit.
REVERT_CREDIT	N/A	No change	Reverting provisional credit.
CHANGE_CASE_TYPE	N/A	No change	Change case from `DISPUTE` type to the `LEGACY_DISPUTE` type.

The transition reason_code field

The transition reason code identifies the standardized reason for the transition.

Reason Code	Description	Related Actions
00	The dispute case was created.	`CREATE`
01	The dispute case was created, but needs additional verification actions.	`CREATE`
05	The dispute case is under review.	`REVIEW`
14	The Marqeta platform updated the dispute case.	`CLOSE`, `NON_CHARGEBACK_CREDIT`
15	An update was initiated by the issuer.	`REINSTATE_USER`, `REINSTATE_BUSINESS`
18	The user or business status was changed to `ACTIVE` because information was properly validated and confirmed.	`REINSTATE_USER`, `REINSTATE_BUSINESS`
19	The user or business status was changed to `ACTIVE` because account activity was properly validated and confirmed.	`REINSTATE_USER`, `REINSTATE_BUSINESS`
22	The dispute case was assigned to a user.	`ASSIGN`
23	The dispute case was reopened.	`RE_OPEN`
24	The dispute case was reopened to gather more information.	`RE_OPEN`, `DOCUMENTS_DELETED`
25	The documents were verified and the dispute case is being closed.	`CLOSE`, `KYC_OVERRIDE`, `REINSTATE_USER`, `REINSTATE_BUSINESS`
26	The customer closed the dispute case.	`CLOSE`
27	The dispute is for a smaller amount and no chargeback is needed.	`NON_CHARGEBACK_CREDIT`
28	A chargeback was created and the cardholder was credited. Only for programs that are not enabled for Regulation E.	`CHARGEBACK_CREDIT`
29	A chargeback was created and the cardholder was not credited. Only for programs that are not enabled for Regulation E.	`CHARGEBACK_NO_CREDIT`
30	The dispute case was closed automatically due to inactivity.	`CLOSE`, `WITHDRAW_AND_CLOSE`
31	Invalid documents were uploaded.	`DOCUMENTS_DELETED`
32	Documents were uploaded that are unreadable because of incorrect format or poor quality.	`DOCUMENTS_DELETED`
33	Corrupted documents were uploaded.	`DOCUMENTS_DELETED`
34	The chargeback failed. Only for programs that are not enabled for Regulation E.	`CHARGEBACK_CREDIT`, `CHARGEBACK_NO_CREDIT`
35	The chargeback failed at the card network. Only for programs that are not enabled for Regulation E.	`CHARGEBACK_CREDIT`, `CHARGEBACK_NO_CREDIT`, `CLOSE`
36	KYC override failed.	`KYC_OVERRIDE`
37	User reinstatement failed.	`REINSTATE_USER`
38	Business reinstatement failed.	`REINSTATE_BUSINESS`
39	Associated transaction selection is required to ready this dispute case.
40	No further action is needed. Closing the dispute case by withdrawing. Only used when the provisional credit has not been granted in the `OPEN` and `OPEN_WITH_ACTION_REQUIRED` states. For Regulation E and non-Regulation E cases, this results in the `CLOSED` state and the chargeback is `WITHDRAWN`.	`WITHDRAW_AND_CLOSE`
41	The dispute case was won, accepted with favorable results, for to all types of dispute cases. This action cannot trigger until the `dispute_state` is `CASE_WON`.	`CLOSE`
42	The dispute case was lost, accepted with unfavorable results. For non-Regulation E dispute cases, this results in the `CLOSED` state. For Regulation E dispute cases, this results in `PENDING_CLOSED`.	`CLOSE`
43	The dispute case was rejected by the network.	`CLOSE`
44	The dispute case was written off by the issuer.	`WRITE_OFF`, `CLOSE`
45	The dispute case was closed and written off by the program using funds from the program account.	`WRITE_OFF`, `CLOSE`
46	Provisional credit has been granted.	`GRANT_CREDIT`
47	Provisional credit has been reverted.	`REVERT_CREDIT`
48	A failure occurred when attempting to transition to the `READY` state.	No change
49	The dispute case was reported to the network as `FRAUD`.	`WITHDRAW_AND_CLOSE`
50	The dispute case was changed from `DISPUTE` type to `LEGACY_DISPUTE` type.	`CHANGE_CASE_TYPE`
51	Submitting dispute to the network. This applies only to programs that are enabled for Regulation E and for a Regulation E dispute. If provisional credit has not been granted, this returns an error. For programs that are not enabled for Regulation E, this returns an error.	`CHARGEBACK_SUBMIT`
52	Provisional credit is required for a Regulation E dispute case.
53	Awaiting milestone.

Dispute transition response

Fields	Description
case_token string Returned	The unique identifier of the dispute case. Allowable Values: 36 char max
token string Returned	The unique identifier of the dispute case transition. If you did not include a token, the system generates a token automatically. Allowable Values: 36 char max
action string Returned	The action taken on the dispute case. Allowable Values: See Dispute case transitions.
reason_code string Returned	Identifies the standardized reason for the transition. Allowable Values: See The transition reason_code field table.
reason_description string Returned	A descriptive reason for the transition. Allowable Values: 36 char max
created_by string Returned	The user ID or name of the user who created the transition. Allowable Values: 36 char max
from_state string Returned	The state of the dispute case before the case transition was created. Allowable Values: `OPEN`, `OPEN_WITH_ACTION_REQUIRED`, `READY`, `CHARGEBACK_INITIATED`, `CLOSED`
state string Returned	The resulting state of the dispute case after the transition was created. Allowable Values: `OPEN`, `OPEN_WITH_ACTION_REQUIRED`, `READY`, `CHARGEBACK_INITIATED`, `CLOSED`
assignee string Returned	The user ID or name of the user assigned to the dispute case. Allowable Values: 255 char max
memo string Returned	Additional notes about the transition. Allowable Values: 512 char max
failure_reason string Returned	If an error occurred while attempting to transition the dispute case, this field provides a brief description of the failure. Allowable Values: 512 char max
transition_details object Returned	An object containing the transition details. Allowable Values: See The transition_details object.

Sample request body (CHARGEBACK_CREDIT)

This sample is only for programs that are not enabled for Regulation E.

JSON

{
  "token": "dispute_case_token",
  "action": "CHARGEBACK_CREDIT",
  "reason_code": "28",
  "created_by": "user_name",
  "assignee": "assignee_name",
  "memo": "Text about this dispute",
  "transition_details": {
    "chargeback_details": {
      "attached_contents": [
        "3fa85f64-5717-4562-b3fc-2c963f66afa6"
      ]
    }
  }
}

Sample response body (CHARGEBACK_CREDIT)

This sample is only for programs that are not enabled for Regulation E.

JSON

{
  "case_token": "my_case_id",
  "token": "my_casetransition_id",
  "action": "CHARGEBACK_CREDIT",
  "reason_code": "28",
  "reason_description": "Smaller Amount",
  "created_by": "user_name",
  "from_state": "OPEN",
  "state": "CHARGEBACK_INITIATED",
  "assignee": "assignee_name",
  "memo": "Text about this dispute",
  "failure_reason": "string",
  "transition_details": {
    "chargeback_details": {
      "attached_contents": [
        "3fa85f64-5717-4562-b3fc-2c963f66afa6"
      ]
    }
  }
}

Sample request body (CHARGEBACK_NO_CREDIT)

JSON

{
  "token": "dispute_case_token",
  "action": "CHARGEBACK_NO_CREDIT",
  "reason_code": "29",
  "created_by": "user_name",
  "assignee": "assignee_name",
  "memo": "Initiating chargeback",
  "transition_details": {
    "chargeback_details": {
      "attached_contents": [
        "3fa85f64-5717-4562-b3fc-2c963f66afa6"
      ]
    }
  }
}

Sample response body (CHARGEBACK_NO_CREDIT)

JSON

{
  "case_token": "my_case_id",
  "token": "my_casetransition_id",
  "action": "CHARGEBACK_N0_CREDIT",
  "reason_code": "29",
  "reason_description": "Smaller Amount",
  "created_by": "user_name",
  "from_state": "OPEN",
  "state": "CHARGEBACK_INITIATED",
  "assignee": "assignee_name",
  "memo": "Initiating chargeback",
  "failure_reason": "string",
  "transition_details": {
    "chargeback_details": {
      "attached_contents": [
        "3fa85f64-5717-4562-b3fc-2c963f66afa6"
      ]
    }
  }
}

Response action/reason code changes

There are some cases where the reason code is changed by the system for either of two reasons:

An error occurred while processing a transition.
The dispute case transition moved the case to a state different from the desired state.

Action	Reason Code	Resulting State	Description
`CHARGEBACK_SUBMIT`	52	`OPEN_WITH_ACTION_REQUIRED`	Triggered during an attempt to transition a dispute case with action `CHARGEBACK_SUBMIT` and reason code 51. Occurs when attempting to transition a Regulation E dispute case that has not granted provisional credit.
`CLOSE`	53	`PENDING_CLOSED`	Triggered during an attempt to transition a dispute case with action `CLOSED` and reason code 42. Occurs for Regulation E cases to indicate that the customer must first notify the cardholder before reverting the credit, as required by Regulation E, and must wait a specified number of days before reverting credit.

Sample response body (ACTION/REASON CODE CHANGES)

JSON

{
  "token": "string",
  "case_token": "string"
  "reason_code": "51",
  "reason_description": "Submit case to the card network"
  "created_by": "string",
  "from_state": "READY",
  "state": "CHARGEBACK_INITIATED",
  "action": "CHARGEBACK_SUBMIT",
  "memo": "string",
  "transition_details": {
    "chargeback_details": {
      "attached_contents": ["uuid"]
    }
  }
}

Transition failure response

An error occurs when attempting to transition a dispute case using CHARGEBACK_SUBMIT when the dispute has no provisional credit granted.

Error response

Error Code	Error Message	Description
400400	Attempted to close case as case won when the dispute state is not set to CASE_WON	Triggered when an attempt to close a case as `CASE_WON` without having it be won in the backend lifecycle.
400400	Cannot write off cases that haven’t granted provisional credit	Triggered during an attempt to transition a case with action `CLOSE` and reason code 45. Occurs for Regulation E cases if provisional credit has not been granted. Solution: Close the case using `WITHDRAW_AND_CLOSE`.
400401	Case is no longer applicable as case lost under RegE	Triggered during an attempt to transition a dispute case with action `CLOSE` and reason code 42. Occurs for Regulation E cases that are past the Regulation E 45-day time limit. Solution: Close the case with reason code 45.
400400	Invalid Action for Current State	Triggered during `CHARGEBACK_SUBMIT` if the program is not Regulation E enabled. Triggered during `CHARGEBACK_CREDIT` or `CHARGEBACK_NO_CREDIT` when attempting to use this action to transition a REG_E case.
400400	Unable to withdraw and close because provisional credit has been granted	Triggered during an attempt to transition a case with `WITHDRAW_AND_CLOSE` when the provisional credit has been granted.
400400	Waiting for provisional credit to be reversed before the case can be closed	Triggered during an attempt to transition a case with action `CLOSE` and reason code 42. Occurs if the case is in `PENDING_CLOSED` state and the reversal of provision credit has not occurred. Solution: Wait for the provisional credit to be reversed.

Sample response body (TRANSITION FAILURE RESPONSE)

JSON

{
  "token": "string",
  "case_token": "string"
  "reason_code": "52",
  "reason_description": "Provisional credit required"
  "created_by": "string",
  "from_state": "READY",
  "state": "OPEN_WITH_ACTION_REQUIRED",
  "action": "CHARGEBACK_SUBMIT",
  "memo": "string",
  "transition_details": {
    "chargeback_details": {
      "attached_contents": ["uuid"]
    }
  }
}

Retrieve dispute case transition

Action: GET
Endpoint: /cases/{token}/transitions/{transition_token} Retrieve a specific dispute case transition for a specific dispute case. A dispute case transition is an event that changes the state of a dispute case and triggers other related events. The new state of the dispute case and which related events are triggered is determined by the action defined in the dispute case transition.

URL path parameters

Fields	Description
token string Required	The token of the dispute case associated with the transitions you want to retrieve. Allowable Values: 36 char max Send a `GET` request to `/cases` to retrieve dispute case tokens.
transition_token string Required	The token of the transition to retrieve. Allowable Values: 36 char max Send a `GET` request to `/cases/{token}/transitions` to retrieve dispute case transition tokens.

Retrieve dispute case transition response

See Dispute transition response.

Sample response body

JSON

{{
  "case_token": "string",
  "token": "string",
  "action": "CREATE",
  "reason_code": "44",
  "reason_description": "string",
  "created_by": "string",
  "from_state": "OPEN",
  "state": "OPEN",
  "assignee": "string",
  "memo": "string",
  "failure_reason": "string",
  "transition_details": {
    "chargeback_details": {
      "attached_contents": [
        "3fa85f64-5717-4562-b3fc-2c963f66afa6"
      ]
    }
  }
}

List dispute case transitions

Action: GET
Endpoint: /cases/{token}/transitions List existing dispute case transitions for the specified dispute case. This endpoint supports sorting and pagination.

URL path parameters

Fields	Description
token string Required	The token of the dispute case associated with the transitions you want to list. Allowable Values: 36 char max Send a `GET` request to `/cases` to retrieve dispute case tokens.

Query parameters

Fields	Description
state string Optional	Filter dispute case transitions that contain the specified resulting state. Allowable Values: `OPEN`, `OPEN_WITH_ACTION_REQUIRED`, `READY`, `CHARGEBACK_INITIATED`, `CLOSED`

List dispute case transition response

See Dispute transition response.

Sample response body

JSON

{
  "count": 2,
  "start_index": 0,
  "end_index": 1,
  "is_more": false,
  "data": [
    {
      "case_token": "my_case_id",
      "token": "my_casetransition_id1",
      "action": "CHARGEBACK_CREDIT",
      "reason_code": "28",
      "reason_description": "Smaller Amount",
      "created_by": "string",
      "from_state": "OPEN",
      "state": "OPEN",
      "assignee": "string",
      "memo": "Initiating chargeback",
      "failure_reason": "string",
      "transition_details": {
        "chargeback_details": {
          "attached_contents": [
            "3fa85f64-5717-4562-b3fc-2c963f66afa6"
          ]
        }
      }
    },
    {
      "case_token": "my_case_id",
      "token": "my_casetransition_id2",
      "action": "ASSIGN",
      "reason_code": "05",
      "reason_description": "Under Review",
      "created_by": "user_name",
      "from_state": "READY",
      "state": "OPEN",
      "assignee": "string",
      "memo": "Assigned to user",
      "failure_reason": "string",
      "transition_details": {
        "chargeback_details": {
          "attached_contents": [
            "4fa85f64-5719-4561-b3fa-2c963f66abc9"
          ]
        }
      }
    }
  ]
}

Create network dispute transition

Action: POST
Endpoint: /cases/{token}/disputetransitions Create a network dispute transition. A network dispute transition is an event that changes the network state of a dispute and triggers other related events. The new state of the dispute within the network dispute lifecycle and which related events are triggered is determined by the action defined in the network dispute transition.

URL path parameters

Fields	Description
token string Required	The token of the dispute associated with the transition you want to create. Allowable Values: 36 char max Submit a `GET` request to `/cases` to retrieve case tokens.

Request body

Fields	Description
action string Required	The action to take: - `RESPOND_WITH_PREARB:` Action to move a dispute to prearbitration with Visa. - `RESPOND_WITH_ARB:` Action to move a prearbitration disputes to arbitration. - `RESPOND_WITH_PREARB_RESPONSE`: Respond to the prearbitration response. - `ACCEPT_AND_CLOSE:` Action to accept the dispute decision and close the dispute. - `CLOSE_WITH_CASE_WON`: Close with case won dispute transition. - `CLOSE_WITH_NETWORK_REJECTED`: Close with network rejected. - `REPRESENTMENT_RECEIVED`: Indicates that representment was received. Allowable Values: `RESPOND_WITH_PREARB`, `RESPOND_WITH_ARB`, `RESPOND_WITH_PREARB_RESPONSE`, `ACCEPT_AND_CLOSE`, `CLOSE_WITH_CASE_WON`, `CLOSE_WITH_NETWORK_REJECTED`, `REPRESENTMENT_RECEIVED`
created_by string Optional	The user who is creating the transition. Allowable Values: 255 char max
memo string Optional	A memo regarding the transaction. Allowable Values: 16777215 char max
network_details object Conditionally required	The network details. Allowable Values: See The network_details object table.

The network_details object

Depending on the transition, contains the prearbitration_details object or the arbitration_details object.

Fields	Description
prearbitration_details object Optional	Object defining the prearbitration details. Allowable Values: See The prearbitration_details object table.
prearbitration_response_details object Optional	Object defining the prearbitration response details. Allowable Values: See The prearbitration_response_details object table.
arbitration_details object Optional	Object defining the arbitration details. Allowable Values: See The arbitration_details object table.
representment_details object Optional	Object defining the representment details. Allowable Values: See The representment_details object table.
case_close_details string Optional	The new dispute state. Allowable Values: See The case_close_details object table.

The prearbitration_details object

The details for prearbitration.

Fields	Description
amount number Required	The amount in dispute. Allowable Values: 32 bytes
attached_contents string Optional	Content token for documents to be submitted to the network at the current dispute state. Allowable Values: 256 char max
why_are_you_initiating_prearbitration string Required	The reason you are initiating prearbitration. Allowable Values:
are_you_providing_new_information boolean Required	Indicates whether this state change includes new information useful for the dispute. Allowable Values: `true`, `false`
summary_of_new_information string Conditionally required.	A summary of the new information provided. Allowable Values:

The prearbitration_response_details object

The details for prearbitration response.

Fields	Description
attached_contents string Optional	Content token for documents to be submitted to the network at the current dispute state. Allowable Values: 256 char max
prearbitration_response_decision string Required	The prearbitration response decision. Allowable Values: `ACCEPT_PARTIAL`, `DECLINE`
amount string Required	The partial acceptance amount. Allowable Values: 32 bytes
why_are_you_not_accepting_liability string Required	The reason you are not accepting liability. Allowable Values:
certify_that_you_have_contacted_ cardholder_and_reviewed_the_ compelling_evidence_with_them_ and_cardholder_continues_dispute boolean Required	Indicates whether you have contacted the cardholder and reviewed the evidence and that the cardholder is continuing the dispute. Allowable Values: `true`, `false`
explanation_of_why_cardholder_ continues_dispute string Required	A description of why the cardholder is continuing the dispute. Allowable Values:
certify_that_cardholder_name_and_ address_provided_by_acquirer_does_ not_match_issuer_records boolean Required	Indicates whether the cardholder’s name and address from the acquirer does not match issuer records. Allowable Values: `true`, `false`
explanation_of_why_you_are_ continuing_the_dispute string Required	An explanation of why you are continuing the dispute. Allowable Values:

The arbitration_details object

The details for arbitration.

Fields	Description
attached_contents string Optional	Content token for documents to be submitted to the network at the current dispute state. Allowable Values: 256 char max

The representment_details object

The details for representment transition.

Fields	Description
amount number Required	The amount in dispute. Allowable Values: Min: 0.1
attached_contents string Optional	Content token for documents to be submitted to the network at the current dispute state. Allowable Values: 256 char max

The case_close_details object

The details for case close transition details.

Fields	Description
write_off boolean Optional	Indicates whether the write-off due to the case lost happened. Allowable Values: `true`, `false`
write_off_actor string Optional	The actor who performed the write-off. Allowable Values: `PROGRAM`, `ISSUER`

Network dispute transition response body

Fields	Description
token string Returned	The unique identifier of the dispute transition. Allowable Values: 36 char max
created_time datetime Returned	The date and time when the transition was created. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ
last_modified_time datetime Returned	The date and time when the transition was last modified. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ
case_token string Returned	The token identifying the dispute case for the created the dispute transition. Allowable Values: 36 char max
action string Returned	The action taken. 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`
created_by string Returned	The user ID or name of the user who created the transition. Allowable Values: 256 char max
memo string Conditionally returned	A memo regarding the transaction. Allowable Values: 16777215 char max
from_network_status string Conditionally returned	The network status before the transition. Allowable Values: 255 char max
to_network_status string Conditionally returned	The new network status after the transition. Allowable Values: 255 char max
network_dispute_id string Returned	The ID assigned to the dispute by the network. Allowable Values: 36 char max
system_error_message string Conditionally returned	The error message for the system error. Allowable Values: 16777215 char max
network_error_message string Conditionally returned	The error message for the network error. Allowable Values: 16777215 char max
network_details object Conditionally returned	Dispute details from the network. Contents depend on the network state. Allowable Values: See The network_details_response object table.

The network_details_response object

Depending on the transition, contains the prearbitration_details object or the arbitration_details object.

Fields	Description
prearbitration_details object Optional	Object defining the prearbitration details. Allowable Values: See The prearbitration_details object table.
prearbitration_response_details object Optional	Object defining the prearbitration response details. Allowable Values: See The prearbitration_response_details object table.
arbitration_details object Optional	Object defining the arbitration details. Allowable Values: See The arbitration_details object table.
representment_details object Optional	Object defining the representment details. Allowable Values: See The representment_details object table.
network_state_details string Optional	A JSON object, containing the details, received from the network. Allowable Values:
dispute_state string Optional	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`, `CLOSED`, `NETWORK_REJECTED`, `CASE_LOST`, `WRITTEN_OFF_ISSUER`, `WRITTEN_OFF_PROGRAM`
case_close_details string Optional	The new dispute state. Allowable Values: See The case_close_details object table.

Sample request with prearbitration

JSON

{
  "action": "RESPOND_WITH_PREARB",
  "created_by": "user_name",
  "memo": "pre-arb transition for Mc testing",
  "network_details": {
    "prearbitration_details": {
      "amount": 112.0,
      "attached_contents": [
        "content_token"
      ],
      "why_are_you_initiating_prearbitration": "string",
      "are_you_providing_new_information": true,
      "summary_of_new_information": "string"
    },
    "prearbitration_response_details": {
      "attached_contents": [
        "string"
      ],
      "prearb_response_decision": "ACCEPT_PARTIAL",
      "amount": "string",
      "whyAreYouNotAcceptingLiability": "string",
      "certifyThatYouHaveContactedCardholderAndReviewedTheCompellingEvidenceWithThemAndCardholderContinuesDispute": true,
      "explanationOfWhyCardholderContinuesDispute": "string",
      "certifyThatCardholderNameAndAddressProvidedByAcquirerDoesNotMatchIssuerRecords": true,
      "explanationOfWhyYouAreContinuingTheDispute": "string"
    },
    "arbitration_details": {
      "attached_contents": [
        "string"
      ]
    },
    "representment_details": {
      "amount": 0.1,
      "attached_contents": [
        "string"
      ]
    },
    "case_close_details": {
      "write_off": true,
      "write_off_actor": "PROGRAM"
    }
  }
}

Sample response with prearbitration

JSON

{
  "token": "my_dispute_transition_token",
  "created_time": "2022-07-20T22:10:57.423Z",
  "last_modified_time": "2022-07-20T22:10:57.423Z",
  "case_token": "my_case_token",
  "action": "RESPOND_WITH_PREARB",
  "created_by": "user_name",
  "memo": "pre-arb transition for Mc testing",
  "from_network_status": "string",
  "to_network_status": "string",
  "network_dispute_id": "network_dispute_id",
  "system_error_message": "string",
  "network_error_message": "string",
  "network_details": {
    "prearbitration_details": {
      "amount": 112.5,
      "attached_contents": [
        "content_token"
      ],
      "why_are_you_initiating_prearbitration": "string",
      "are_you_providing_new_information": true,
      "summary_of_new_information": "string"
    },
    "prearbitration_response_details": {
      "attached_contents": [
        "content_token"
      ],
      "prearb_response_decision": "ACCEPT_PARTIAL",
      "amount": "string",
      "whyAreYouNotAcceptingLiability": "string",
      "certifyThatYouHaveContactedCardholderAndReviewedTheCompellingEvidenceWithThemAndCardholderContinuesDispute": true,
      "explanationOfWhyCardholderContinuesDispute": "string",
      "certifyThatCardholderNameAndAddressProvidedByAcquirerDoesNotMatchIssuerRecords": true,
      "explanationOfWhyYouAreContinuingTheDispute": "string"
    },
    "arbitration_details": {
      "attached_contents": [
        "content_token"
      ]
    },
    "representment_details": {
      "amount": 112.5,
      "attached_contents": [
        "content_token"
      ]
    },
    "network_state_details": "string",
    "dispute_state": "INITIATED",
    "case_close_details": {
      "write_off": true,
      "write_off_actor": "PROGRAM"
    }
  }
}

Sample request with arbitration

JSON

{
  "action": "RESPOND_WITH_ARB",
  "created_by": "user_name",
  "memo": "arbitration response transition response for Mc testing",
  "network_details": {
    "prearbitration_details": {
      "amount": 112.0,
      "attached_contents": [
        "content_token"
      ],
      "why_are_you_initiating_prearbitration": "string",
      "are_you_providing_new_information": true,
      "summary_of_new_information": "string"
    },
    "prearbitration_response_details": {
      "attached_contents": [
        "string"
      ],
      "prearb_response_decision": "ACCEPT_PARTIAL",
      "amount": "string",
      "whyAreYouNotAcceptingLiability": "string",
      "certifyThatYouHaveContactedCardholderAndReviewedTheCompellingEvidenceWithThemAndCardholderContinuesDispute": true,
      "explanationOfWhyCardholderContinuesDispute": "string",
      "certifyThatCardholderNameAndAddressProvidedByAcquirerDoesNotMatchIssuerRecords": true,
      "explanationOfWhyYouAreContinuingTheDispute": "string"
    },
    "arbitration_details": {
      "attached_contents": [
        "string"
      ]
    },
    "representment_details": {
      "amount": 0.1,
      "attached_contents": [
        "string"
      ]
    },
    "case_close_details": {
      "write_off": true,
      "write_off_actor": "PROGRAM"
    }
  }
}

Sample response with arbitration

JSON

{
  "token": "my_dispute_transition_token",
  "created_time": "2022-07-20T22:10:57.423Z",
  "last_modified_time": "2022-07-20T22:10:57.423Z",
  "case_token": "my_case_token",
  "action": "RESPOND_WITH_ARB",
  "created_by": "user_name",
  "memo": "Arbitration response transition response for Mc testing",
  "from_network_status": "string",
  "to_network_status": "string",
  "network_dispute_id": "network_dispute_id",
  "system_error_message": "string",
  "network_error_message": "string",
  "network_details": {
    "prearbitration_details": {
      "amount": 112.5,
      "attached_contents": [
        "content_token"
      ],
      "why_are_you_initiating_prearbitration": "string",
      "are_you_providing_new_information": true,
      "summary_of_new_information": "string"
    },
    "prearbitration_response_details": {
      "attached_contents": [
        "content_token"
      ],
      "prearb_response_decision": "ACCEPT_PARTIAL",
      "amount": "string",
      "whyAreYouNotAcceptingLiability": "string",
      "certifyThatYouHaveContactedCardholderAndReviewedTheCompellingEvidenceWithThemAndCardholderContinuesDispute": true,
      "explanationOfWhyCardholderContinuesDispute": "string",
      "certifyThatCardholderNameAndAddressProvidedByAcquirerDoesNotMatchIssuerRecords": true,
      "explanationOfWhyYouAreContinuingTheDispute": "string"
    },
    "arbitration_details": {
      "attached_contents": [
        "content_token"
      ]
    },
    "representment_details": {
      "amount": 112.5,
      "attached_contents": [
        "content_token"
      ]
    },
    "network_state_details": "string",
    "dispute_state": "INITIATED",
    "case_close_details": {
      "write_off": true,
      "write_off_actor": "PROGRAM"
    }
  }
}

Sample accept and close dispute request

JSON

{
  "action": "ACCEPT_AND_CLOSE",
  "created_by": "user_name",
  "memo": "accept and close",
  "network_details": {
    "prearbitration_details": {
      "amount": 112.0,
      "attached_contents": [
        "content_token"
      ],
      "why_are_you_initiating_prearbitration": "string",
      "are_you_providing_new_information": true,
      "summary_of_new_information": "string"
    },
    "prearbitration_response_details": {
      "attached_contents": [
        "string"
      ],
      "prearb_response_decision": "ACCEPT_PARTIAL",
      "amount": "string",
      "whyAreYouNotAcceptingLiability": "string",
      "certifyThatYouHaveContactedCardholderAndReviewedTheCompellingEvidenceWithThemAndCardholderContinuesDispute": true,
      "explanationOfWhyCardholderContinuesDispute": "string",
      "certifyThatCardholderNameAndAddressProvidedByAcquirerDoesNotMatchIssuerRecords": true,
      "explanationOfWhyYouAreContinuingTheDispute": "string"
    },
    "arbitration_details": {
      "attached_contents": [
        "string"
      ]
    },
    "representment_details": {
      "amount": 0.1,
      "attached_contents": [
        "string"
      ]
    },
    "case_close_details": {
      "write_off": true,
      "write_off_actor": "PROGRAM"
    }
  }
}

Sample accept and close dispute response

JSON

{
  "token": "my_dispute_transition_token",
  "created_time": "2022-07-20T22:10:57.423Z",
  "last_modified_time": "2022-07-20T22:10:57.423Z",
  "case_token": "my_case_token",
  "action": "ACCEPT_AND_CLOSE",
  "created_by": "user_name",
  "memo": "accept and close",
  "from_network_status": "string",
  "to_network_status": "string",
  "network_dispute_id": "network_dispute_id",
  "system_error_message": "string",
  "network_error_message": "string",
  "network_details": {
    "prearbitration_details": {
      "amount": 112.5,
      "attached_contents": [
        "content_token"
      ],
      "why_are_you_initiating_prearbitration": "string",
      "are_you_providing_new_information": true,
      "summary_of_new_information": "string"
    },
    "prearbitration_response_details": {
      "attached_contents": [
        "content_token"
      ],
      "prearb_response_decision": "ACCEPT_PARTIAL",
      "amount": "string",
      "whyAreYouNotAcceptingLiability": "string",
      "certifyThatYouHaveContactedCardholderAndReviewedTheCompellingEvidenceWithThemAndCardholderContinuesDispute": true,
      "explanationOfWhyCardholderContinuesDispute": "string",
      "certifyThatCardholderNameAndAddressProvidedByAcquirerDoesNotMatchIssuerRecords": true,
      "explanationOfWhyYouAreContinuingTheDispute": "string"
    },
    "arbitration_details": {
      "attached_contents": [
        "content_token"
      ]
    },
    "representment_details": {
      "amount": 112.5,
      "attached_contents": [
        "content_token"
      ]
    },
    "network_state_details": "string",
    "dispute_state": "INITIATED",
    "case_close_details": {
      "write_off": true,
      "write_off_actor": "PROGRAM"
    }
  }
}

Sample close with case won dispute request

JSON

{
  "action": "CLOSE_WITH_CASE_WON",
  "created_by": "user_name",
  "memo": "close with case won",
  "network_details": {
    "prearbitration_details": {
      "amount": 112.0,
      "attached_contents": [
        "content_token"
      ],
      "why_are_you_initiating_prearbitration": "string",
      "are_you_providing_new_information": true,
      "summary_of_new_information": "string"
    },
    "prearbitration_response_details": {
      "attached_contents": [
        "string"
      ],
      "prearb_response_decision": "ACCEPT_PARTIAL",
      "amount": "string",
      "whyAreYouNotAcceptingLiability": "string",
      "certifyThatYouHaveContactedCardholderAndReviewedTheCompellingEvidenceWithThemAndCardholderContinuesDispute": true,
      "explanationOfWhyCardholderContinuesDispute": "string",
      "certifyThatCardholderNameAndAddressProvidedByAcquirerDoesNotMatchIssuerRecords": true,
      "explanationOfWhyYouAreContinuingTheDispute": "string"
    },
    "arbitration_details": {
      "attached_contents": [
        "string"
      ]
    },
    "representment_details": {
      "amount": 0.1,
      "attached_contents": [
        "string"
      ]
    },
    "case_close_details": {
      "write_off": true,
      "write_off_actor": "PROGRAM"
    }
  }
}

Sample close with case won dispute response

JSON

{
  "token": "my_dispute_transition_token",
  "created_time": "2022-07-20T22:10:57.423Z",
  "last_modified_time": "2022-07-20T22:10:57.423Z",
  "case_token": "my_case_token",
  "action": "CLOSE_WITH_CASE_WON",
  "created_by": "user_name",
  "memo": "close with case won",
  "from_network_status": "string",
  "to_network_status": "string",
  "network_dispute_id": "network_dispute_id",
  "system_error_message": "string",
  "network_error_message": "string",
  "network_details": {
    "prearbitration_details": {
      "amount": 112.5,
      "attached_contents": [
        "content_token"
      ],
      "why_are_you_initiating_prearbitration": "string",
      "are_you_providing_new_information": true,
      "summary_of_new_information": "string"
    },
    "prearbitration_response_details": {
      "attached_contents": [
        "content_token"
      ],
      "prearb_response_decision": "ACCEPT_PARTIAL",
      "amount": "string",
      "whyAreYouNotAcceptingLiability": "string",
      "certifyThatYouHaveContactedCardholderAndReviewedTheCompellingEvidenceWithThemAndCardholderContinuesDispute": true,
      "explanationOfWhyCardholderContinuesDispute": "string",
      "certifyThatCardholderNameAndAddressProvidedByAcquirerDoesNotMatchIssuerRecords": true,
      "explanationOfWhyYouAreContinuingTheDispute": "string"
    },
    "arbitration_details": {
      "attached_contents": [
        "content_token"
      ]
    },
    "representment_details": {
      "amount": 112.5,
      "attached_contents": [
        "content_token"
      ]
    },
    "network_state_details": "string",
    "dispute_state": "INITIATED",
    "case_close_details": {
      "write_off": true,
      "write_off_actor": "PROGRAM"
    }
  }
}

Create ACCEPT_AND_CLOSE transition

This transition moves the network dispute state to CASE_LOST sets the case transition to CLOSE with reason code 42 (Case Lost). For Regulation E dispute cases, if the case is past 45 days, the callee must specify both write_off and write_off_actor. When this occurs, the dispute state is set to WRITE_OFF_PROGRAM and sets the case transition to CLOSE with reason code 45 (Write off Program).

Query parameters

Fields	Description
action string Required	The action taken. Allowable Values: ACCEPT_AND_CLOSE
created_by string Required	The user ID or name of the user who created the transition. Allowable Values: 256 char max
memo string Required	A memo regarding the transaction. Allowable Values: 16777215 char max
close_case_details.write_off boolean Conditionally required	Required if the 45-day Regulation E time limit has expired. Allowable Values: `true`, `false`
close_case_details.write_off_actor string Conditionally required	Triggers a `CLOSE` case transition with reason code 45. Required if the 45-day Regulation E time limit has expired. Allowable Values: `PROGRAM`

Response fields

See the Network dispute transition response table.

Error codes

Error Code	Error Message	Description
400301	Case is RegE and can only be accepted and closed with write off after it expires	Triggered when attempting to do an `ACCEPT_AND_CLOSE` action without write-off information for a case that has exceeded the 45-day milestone.

Sample ACCEPT_AND_CLOSE transition request

JSON

{
  "action": "ACCEPT_AND_CLOSE",
  "created_by": "string",
  "memo": "string",
  "network_details": {
    "case_close_details": {
      "write_off": true,
      "write_off_actor": "PROGRAM"
    }
  }
}

Sample ACCEPT_AND_CLOSE transition response

JSON

{
  "token": "string",
  "case_token": "string",
  "action": "ACCEPT_AND_CLOSE",
  "created_by": "string",
  "memo": "string",
  "from_network_status": "string",
  "to_network_status": "string",
  "network_dispute_id": "string",
  "system_error_message": "string",
  "network_error_message": "string",
  "created_time": "timestamp",
  "last_modified_time": "timestamp",
  "network_details": {
    "case_close_details": {
      "write_off": true,
      "write_off_actor": "PROGRAM"
    }
  }
}

Create CLOSE_WITH_CASE_WON transition

For Regulation E and non-Regulation E network dispute cases, the dispute state is set to CASE_WON and a CLOSE case transition with reason code 41 (Case Won) is created.

Sample CLOSE_WITH_CASE_WON transition request

JSON

{
  "action": "CLOSE_WITH_CASE_WON",
  "created_by": "string",
  "memo": "string"
}

Sample CLOSE_WITH_CASE_WON transition response

JSON

{
  "token": "string",
  "case_token": "string",
  "action": "ACCEPT_AND_CLOSE",
  "created_by": "string",
  "memo": "string",
  "from_network_status": "string",
  "to_network_status": "string",
  "network_dispute_id": "string",
  "system_error_message": "string",
  "network_error_message": "string",
  "created_time": "timestamp",
  "last_modified_time": "timestamp",
  "network_details": {
    "case_close_details": {
      "write_off": true,
      "write_off_actor": "PROGRAM"
    }
  }
}

Retrieve network dispute transition

Action: GET
Endpoint: /cases/{token}/disputetransitions/{transition_token} Retrieve a specific network dispute transition for a specific dispute. A network dispute transition is an event that changes the state of a dispute and triggers other related events. The new state of the dispute and which related events are triggered is determined by the action defined in the transition.

URL path parameters

Fields	Description
transition_token string Required	The token of the transition to retrieve. Allowable Values: 36 char max Send a `GET` request to `/cases/{token}/transitions` to retrieve dispute transition tokens.

Response fields

See the Network dispute transition response table.

Sample response body

JSON

{
  "token": "my_network_transition_id1",
  "created_time": "2022-07-21T19:32:01.326Z",
  "last_modified_time": "2022-07-21T19:32:01.326Z",
  "case_token": "my_case_token",
  "action": "CHARGEBACK_CREDIT",
  "created_by": "user_name",
  "memo": "Initiating chargeback",
  "from_network_status": "string",
  "to_network_status": "string",
  "network_dispute_id": "string",
  "system_error_message": "string",
  "network_error_message": "string",
  "network_details": {
    "prearbitration_details": {
      "amount": 120.0,
      "attached_contents": [
        "string"
      ],
      "why_are_you_initiating_prearbitration": "string",
      "are_you_providing_new_information": true,
      "summary_of_new_information": "string"
    },
    "prearbitration_response_details": {
      "attached_contents": [
        "string"
      ],
      "prearb_response_decision": "ACCEPT_PARTIAL",
      "amount": "string",
      "whyAreYouNotAcceptingLiability": "string",
      "certifyThatYouHaveContactedCardholderAndReviewedTheCompellingEvidenceWithThemAndCardholderContinuesDispute": true,
      "explanationOfWhyCardholderContinuesDispute": "string",
      "certifyThatCardholderNameAndAddressProvidedByAcquirerDoesNotMatchIssuerRecords": true,
      "explanationOfWhyYouAreContinuingTheDispute": "string"
    },
    "arbitration_details": {
      "attached_contents": [
        "string"
      ]
    },
    "representment_details": {
      "amount": 120.0,
      "attached_contents": [
        "string"
      ]
    },
    "network_state_details": "string",
    "dispute_state": "CHARGEBACK_INITIATED",
    "case_close_details": {
      "write_off": true,
      "write_off_actor": "PROGRAM"
    }
  }
}

List network dispute transitions

Action: GET
Endpoint: /cases/{token}/disputetransitions List existing network dispute transitions for the specified dispute, including details of the merchant/acquirer responses during the backend resolution process. This endpoint supports sorting and pagination.

URL path parameters

Fields	Description
token string Required	The token of the dispute associated with the transitions you want to list. Allowable Values: 36 char max Send a `GET` request to `/cases` to retrieve dispute tokens.

List network dispute transitions response fields

See the Network dispute transition response table.

Sample response body

JSON

{
  "count": 0,
  "start_index": 0,
  "end_index": 0,
  "is_more": true,
  "data": [
    {
      "token": "string",
      "created_time": "2022-07-21T17:37:37.792Z",
      "last_modified_time": "2022-07-21T17:37:37.792Z",
      "case_token": "string",
      "action": "SUBMIT",
      "created_by": "string",
      "memo": "string",
      "from_network_status": "string",
      "to_network_status": "string",
      "network_dispute_id": "string",
      "system_error_message": "string",
      "network_error_message": "string",
      "network_details": {
        "prearbitration_details": {
          "amount": 0,
          "attached_contents": [
            "string"
          ],
          "why_are_you_initiating_prearbitration": "string",
          "are_you_providing_new_information": true,
          "summary_of_new_information": "string"
        },
        "prearbitration_response_details": {
          "attached_contents": [
            "string"
          ],
          "prearb_response_decision": "ACCEPT_PARTIAL",
          "amount": "string",
          "whyAreYouNotAcceptingLiability": "string",
          "certifyThatYouHaveContactedCardholderAndReviewedTheCompellingEvidenceWithThemAndCardholderContinuesDispute": true,
          "explanationOfWhyCardholderContinuesDispute": "string",
          "certifyThatCardholderNameAndAddressProvidedByAcquirerDoesNotMatchIssuerRecords": true,
          "explanationOfWhyYouAreContinuingTheDispute": "string"
        },
        "arbitration_details": {
          "attached_contents": [
            "string"
          ]
        },
        "representment_details": {
          "amount": 0.1,
          "attached_contents": [
            "string"
          ]
        },
        "network_state_details": "string",
        "dispute_state": "INITIATED",
        "case_close_details": {
          "write_off": true,
          "write_off_actor": "PROGRAM"
        }
      }
    }
  ]
}

Create dispute case content

Action: POST
Endpoint: /cases/{token}/contents Upload and store documents related to a dispute, such as evidence for dispute or KYC verification documents. The supported document formats are pdf, tiff, and jpeg. Each uploaded file is restricted to 2 MB.

URL path parameter

Fields	Description
token string Required	The token that identifies the dispute case. Allowable Values: 36 char max Send a `GET` request to `/cases` to retrieve dispute case tokens.

Request body

Fields	Description
document_category string Required	The category of the document. The category is also forwarded to Visa. Allowable Values: `AFFIDAVIT_FRAUD`, `AUTHORIZATION_RECORD`, `BANK_STATEMENT`, `CANCELLED_CHECK`, `CARDHOLDER_LETTER`, `CREDIT_VOUCHER`, `FULFILLMENT`, `ISSUER_CERTIFICATION`, `MERCHANT_LETTER`, `NETWORK_DOCUMENT`, `NETWORK_EXHIBIT`, `OTHERS`, `RECEIPT`, `SALES_DRAFT`, `SECOND_OPTION`, `UPDATED_CARDHOLDER_LETTER`, `UPDATED_MERCHANT_LETTER`
document_name string Required	The name for the document. Allowable Values: Must include the file extension, as appropriate for a supported file format: pdf, tiff, or jpeg.
document_data binary Required	Base64-encoded file. Allowable Values: 2 MB max size

Create content response body

Fields	Description
token string Returned	The token identifying the document. Allowable Values: 36 char max
case_token string Returned	The token identifying the dispute case you want to upload documents against. Allowable Values: 36 char max
document_name string Returned	The name of the document. Allowable Values: 255 char max
document_category string Returned	The type of document. Allowable Values: `AFFIDAVIT_FRAUD`, `AUTHORIZATION_RECORD`, `BANK_STATEMENT`, `CANCELLED_CHECK`, `CARDHOLDER_LETTER`, `CREDIT_VOUCHER`, `FULFILLMENT`, `ISSUER_CERTIFICATION`, `MERCHANT_LETTER`, `NETWORK_DOCUMENT`, `NETWORK_EXHIBIT`, `OTHERS`, `RECEIPT`, `SALES_DRAFT`, `SECOND_OPTION`, `UPDATED_CARDHOLDER_LETTER`, `UPDATED_MERCHANT_LETTER`
document_content_type string Returned	The content type of the document. Allowable Values: `application/pdf`, `image/tiff`, `image/jpeg`
network_processing_type string Returned	Indicates the current status of the document at the network: `SUBMITTED` – Indicates it has been submitted to the network using the Dispute Case Transition or Network Dispute Transition endpoint. `RECEIVED` – Indicates that the document has been downloaded from the network, which occurs when the acquirer uploaded a document to support their claim. Allowable Values: `SUBMITTED`, `RECEIVED`
network_processing_phase string Returned	Indicates the status of the document in the dispute lifecycle. Allowable Values: `INITIATED`, `REPRESENTMENT`, `PRE_ARBITRATION`
network_processing_time datetime Returned	The date and time when the document has either been submitted by the user or received from the network. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ
created_time datetime Returned	The date and time when the dispute was created. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ
updated_time datetime Returned	The date and time when the dispute was last modified. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ
download_link string Returned	The link to download the file if it is included in the request. This only applies to the `GET` case content by token endpoint. Allowable Values: A valid URI.

Sample request body

JSON

Content-Type: multipart/form-data; boundary=marqeta_file_separator
Cache-Control: no-cache

--marqeta_file_separator
Content-Type: application/json; Content-Disposition: form-data; name="body"

{
  "document_category": "RECEIPT",
  "document_name": "receipt.pdf",
  "document_data": "string"
}

--marqeta_file_separator
Content-Type: image/jpeg; Content-Disposition: form-data; name="file"

file=@/Users/username/Downloads/online-receipt-location.jpg

--marqeta_file_separator--

Sample response body

JSON

{
  "token": "my_content_token",
  "case_token": "my_case_token",
  "document_name": "string",
  "document_category": "RECEIPT",
  "document_content_type": "application/pdf",
  "network_processing_type": "SUBMITTED",
  "network_processing_phase": "INITIATED",
  "network_processing_time": "2022-02-01T20:22:34.913Z",
  "created_time": "2022-02-01T20:22:34.913Z",
  "updated_time": "2022-02-01T20:22:34.913Z",
  "download_link": "download_link"
}

List contents uploaded against a dispute case

Action: GET
Endpoint: /cases/{token}/contents Get a list of uploaded contents for the specified dispute case.

URL path parameter

Fields	Description
token string Required	The token that identifies the dispute case for which to return the contents list. Allowable Values: 36 char max Send a `GET` request to `/cases` to retrieve dispute case tokens.

List contents response

For response details, see Create content response body.

Sample response body

JSON

{
  "count": 2,
  "start_index": 0,
  "end_index": 1,
  "is_more": false,
  "data": [
    {
      "token": "my_content_token",
      "case_token": "my_case_token",
      "document_name": "receipt.pdf",
      "document_category": "RECEIPT",
      "document_content_type": "image/jpeg",
      "network_processing_type": "RECEIVED",
      "network_processing_phase": "INITIATED",
      "network_processing_time": "2022-01-19T13:22:07Z",
      "created_time": "2022-01-19T13:22:07Z",
      "updated_time": "2022-02-19T12:22:07Z",
      "download_link": "uri"
    },
    {
      "token": "my_content_token",
      "case_token": "my_case_token",
      "document_name": "receipt.pdf",
      "document_category": "RECEIPT",
      "document_content_type": "image/jpeg",
      "network_processing_type": "RECEIVED",
      "network_processing_phase": "INITIATED",
      "network_processing_time": "2022-01-19T13:22:07Z",
      "created_time": "2022-01-19T13:22:07Z",
      "updated_time": "2022-02-19T14:22:07Z",
      "download_link": "uri"
    }
  ]
}

Get content and status

Action: GET
Endpoint: /cases/{case_token}/contents/{token} Get a specific document and its status, and optionally start returning a temporary link to download the file. If you include the download_link=true query parameter, a temporary link is returned in the response that you can use to download the document. The link is active for 15 minutes; after that time, you must call this endpoint again to generate a new link.

URL path parameters

Fields	Description
case_token string Required	The token that identifies the dispute case for which to return the contents list. Allowable Values: 36 char max Send a `GET` request to `/cases` to retrieve dispute case tokens.
token string Required	The token that identifies the document. Allowable Values: 36 char max
download_link string Optional	If set to `true`, this parameter causes a download link for the document to be included in the response. Allowable Values: `true`, `false`

Response body

For response details, see Create content response body.

Sample response body

JSON

{
  "token": "my_content_token",
  "case_token": "my_case_token",
  "document_name": "letter.pdf",
  "document_category": "CARDHOLDER_LETTER",
  "document_content_type": "string",
  "network_processing_type": "SUBMITTED",
  "network_processing_phase": "INITIATED",
  "network_processing_time": "2022-02-02T23:06:18.429Z",
  "created_time": "2022-02-02T23:06:18.429Z",
  "updated_time": "2022-02-02T23:06:18.429Z",
  "download_link": "uri"
}

Update document

Action: PUT
Endpoint: /cases/{token}/contents/{content_token} Change the name of a document or category. If the content has already been processed and is currently SUBMITTED or RECEIVED, an error is returned.

URL path parameter

Fields	Description
token string Required	The token that identifies the dispute case for which to return the contents list. Allowable Values: 36 char max Send a `GET` request to `/cases` to retrieve dispute case tokens.
content_token string Required	The content token that identifies the document. Allowable Values: 36 char max

Body field details

Fields	Description
document_name string Required	The name for the document. Allowable Values: 255 char max
document_category string Required	The category of the document. Allowable Values: `AFFIDAVIT_FRAUD`, `AUTHORIZATION_RECORD`, `BANK_STATEMENT`, `CANCELLED_CHECK`, `CARDHOLDER_LETTER`, `CREDIT_VOUCHER`, `FULFILLMENT`, `ISSUER_CERTIFICATION`, `MERCHANT_LETTER`, `NETWORK_DOCUMENT`, `NETWORK_EXHIBIT`, `OTHERS`, `RECEIPT`, `SALES_DRAFT`, `SECOND_OPTION`, `UPDATED_CARDHOLDER_LETTER`, `UPDATED_MERCHANT_LETTER`

Update document response body

For response details, see Create content response body.

Sample request body

JSON

{
  "document_name": "receipt.pdf",
  "document_category": "RECEIPT"
}

Sample response body

JSON

{
  "token": "my_content_token",
  "case_token": "my_case_token",
  "document_name": "letter.pdf",
  "document_category": "CARDHOLDER_LETTER",
  "document_content_type": "string",
  "network_processing_type": "SUBMITTED",
  "network_processing_phase": "INITIATED",
  "network_processing_time": "2022-02-02T23:06:18.429Z",
  "created_time": "2022-02-02T23:06:18.429Z",
  "updated_time": "2022-02-02T23:06:18.429Z",
  "download_link": "uri"
}

Delete a document

Action: DELETE
Endpoint: /cases/{token}/contents/{content_token} Delete a dispute case document. If the document has already been processed with the network_processing_type set to SUBMITTED or RECEIVED, an error is returned.

URL path parameter

Fields	Description
token string Required	The token that identifies the dispute case. Allowable Values: 255 char max
content_token string Required	The token that identifies the content to delete. This token is generated for the document when it is created. Allowable Values: 255 char max

Delete content response

This endpoint returns a 200 response code and success in the response body.

Sample response body

JSON

{
  "status": "success"
}

Create dispute case action

Action: POST
Endpoint: /cases/{token}/actions Create a dispute case action.

Path parameter

Fields	Description
token string Required	The token that identifies the dispute case. Allowable Values: 36 char max

Body field details

Fields	Description
action_type string Required	`GRANT_PROVISIONAL_CREDIT` - Grant provisional credit and trigger the event. `REVERT_PROVISIONAL_CREDIT` - Revert a previously granted provisional credit and trigger an event. Allowable Values: `GRANT_PROVISIONAL_CREDIT`, `REVERT_PROVISIONAL_CREDIT`
created_by string	Allowable Values:

Response body

Fields	Description
token string Returned	The unique identifier of the dispute case. Allowable Values: 36 char max
action_type string Returned	The action taken. Allowable Values: 255 char max
created_by string Returned	Allowable Values:

Sample request

JSON

{
  "action_type": "GRANT_PROVISIONAL_CREDIT",
  "created_by": "string"
}

Sample response

JSON

{
  "case_token": "<my_case_token>",
  "action_type": "GRANT_PROVISIONAL_CREDIT",
  "created_by": "string"
}

Create event

Action: POST
Endpoint: /cases/{token}/events Create a dispute case event. If you are a Managed by Marqeta (MxM) customer or a hybrid card program and you are submitting a dispute that falls under Regulation E, you must create a case event with evidence. For instructions on creating a case event with evidence, see Disputes Evidence Collection.

Path parameter

Fields	Description
token string Required	The token that identifies the dispute case. Allowable Values: 36 char max

Body field details

Fields	Description
name string Required	The name of the event. Allowable Values: 255 char max
event_date string Optional	When the event took place. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ssZ
created_by string Required	The user creating the event. Allowable Values: 255 char max

Response body

Fields	Description
token string Returned	The generated UUID of the event. Allowable Values: 36 char max
case_token string Returned	The associated case that triggered this event. Allowable Values: 36 char max
name string Returned	The name of the event. Allowable Values: 255 char max
category string Returned	The category to which the event belongs. Allowable Values: `REG_E`
created_by string Required	The user creating the event. Allowable Values: 255 char max
event_date string Returned	When the event took place. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ssZ
created_time string Returned	The timestamp when the event was created. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ssZ

Sample request

JSON

{
  "name": "string",
  "created_by": "string",
  "event_date": "timestamp",
  }
}

Sample response

JSON

{
    "token": "uuid",
    "case_token": "string",
    "name": "string",
    "category": "string",
    "created_by": "string",
    "event_date": "timestamp",
    "created_time": "timestamp"
}

List events

Action: GET
Endpoint: /cases/{token}/events List events.

Path parameter

Fields	Description
token string Required	The token that identifies the dispute case. Allowable Values: 36 char max

Response body

Fields	Description
token string Returned	The generated UUID of the event. Allowable Values: 36 char max
case_token string Returned	The associated case that triggered this event. Allowable Values: 36 char max
name string Returned	The name of the event. Allowable Values: 255 char max
category string Returned	The category to which the event belongs. Allowable Values: `REG_E`
created_by string Required	The user creating the event. Allowable Values: 255 char max
event_date string Returned	When the event took place. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ssZ
created_time string Returned	The timestamp when the event was created. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ssZ

Sample response

JSON

{
  "count": 30,
  "start_index": 0,
  "end_index": 29,
  "is_more": true,
  "data": [
    {
        "case_token": "string",
        "category": "string",
        "sub_category": "string",
        "milestone": "string",
        "next_milestone_due_date": "timestamp",
        "created_time": "timestamp",
        "last_modified_time": "timestamp"
    }
  ]
}

List dispute case milestones

Action: GET
Endpoint: /cases/{token}/milestones List dispute case milestones.

Path parameter

Fields	Description
token string Required	The token that identifies the dispute case. Allowable Values: 36 char max

Body field details

Fields	Description
name string Required	The name of the event. Allowable Values: 255 char max
event_date string Optional	When the event took place. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ssZ
created_by string Required	The user creating the event. Allowable Values: 255 char max
categories object Optional	The categories to which the event belongs. Allowable Values: `REG_E`
subcategories object Optional	The subcategories to which the event belongs. Allowable Values: `PROVISIONAL_CREDIT`, `CARDHOLDER_COMMS`

Response body

Fields	Description
case_token string Returned	The associated case that triggered this event. Allowable Values: 36 char max
category string Returned	The category to which the event belongs. Allowable Values: `REG_E`
sub_category string Returned	The subcategory to which the event belongs. Allowable Values: `REG_E`
milestone string Required	The milestone. Allowable Values: 255 char max
next_milestone_due_date datetime Returned	The date that the next milestone is due. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ssZ
created_time datetime Returned	The timestamp when the event was created. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ssZ
last_modified_time datetime Returned	The timestamp when the event was last modified. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ssZ

Sample response

JSON

{
  "count": 30,
  "start_index": 0,
  "end_index": 29,
  "is_more": true,
  "data": [
    {
        "case_token": "string",
        "category": "string",
        "sub_category": "string",
        "milestone": "string",
        "next_milestone_due_date": "timestamp",
        "created_time": "timestamp",
        "last_modified_time": "timestamp"
    }
  ]
}

Disputes (Mastercard)

Disputes (PULSE)

⌘I

​Create dispute case

​Body field details

​The dispute_details object

​The dispute_details.dispute_reason field

​The processing_error_type_dispute_details object

​The late_presentment_details object

​The incorrect_transaction_code_details object

​The incorrect_currency_details object

​The incorrect_account_number_details object

​The incorrect_transaction_amount_details object

​The consumer_dispute_type_dispute_details object

​The service_not_provided_merchandise_not_received_details object

​The cancelled_recurring_transaction_details object

​The not_as_described_or_defective_merchandise_details object

​The credit_not_processed_details object

​The cancelled_merchandise_or_services_details object

​The duplicate_processing_or_paid_by_other_means_details object

​The additional_dispute_details object

​The fraud_category_type_dispute_details object

​The fraud_classification_type_dispute_details object

​The fraud_dispute_type_details object

​The general_fraud_type_dispute_details object

​Response body

​Sample request body

​Sample response body

​Sample request body (FRAUD)

​Sample response body (FRAUD)

​Submit a batch of possibly associated transactions

​URL path parameters

​Body field details

​The associated_transactions object

​Associated transactions response

​The network_selection_form object

​Submission errors

​Sample request body

​Sample response body

​Update submitted associated transactions

​URL path parameters

​Body field details

​Update associated transactions response

​Submission errors

​Sample request body

​Sample response body

​List associated transactions

​URL path parameter

​Query parameter

​Associated transactions list response

​Submission errors

​Sample response body

​Retrieve dispute case

​URL path parameters

​Query parameter

​Response body

​List dispute cases

​Query parameters

​Response body

​The dispute_details_response object

​The network_case_status_details object

​The regulation_details object

​Sample response body

​Create dispute case transition

​URL path parameters

​Body field details

​The transition_details object

​The chargeback_details object

​Dispute case transitions

​The transition reason_code field

​Dispute transition response

​Sample request body (CHARGEBACK_CREDIT)

​Sample response body (CHARGEBACK_CREDIT)

​Sample request body (CHARGEBACK_NO_CREDIT)

​Sample response body (CHARGEBACK_NO_CREDIT)

​Response action/reason code changes

​Sample response body (ACTION/REASON CODE CHANGES)

​Transition failure response

​Error response

​Sample response body (TRANSITION FAILURE RESPONSE)

​Retrieve dispute case transition

​URL path parameters

​Retrieve dispute case transition response

Create dispute case

Body field details

The dispute_details object

The dispute_details.dispute_reason field

The processing_error_type_dispute_details object

The late_presentment_details object

The incorrect_transaction_code_details object

The incorrect_currency_details object

The incorrect_account_number_details object

The incorrect_transaction_amount_details object

The consumer_dispute_type_dispute_details object

The service_not_provided_merchandise_not_received_details object

The cancelled_recurring_transaction_details object

The not_as_described_or_defective_merchandise_details object

The credit_not_processed_details object

The cancelled_merchandise_or_services_details object

The duplicate_processing_or_paid_by_other_means_details object

The additional_dispute_details object

The fraud_category_type_dispute_details object

The fraud_classification_type_dispute_details object

The fraud_dispute_type_details object

The general_fraud_type_dispute_details object

Response body

Sample request body

Sample response body

Sample request body (FRAUD)

Sample response body (FRAUD)

Submit a batch of possibly associated transactions

URL path parameters

Body field details

The associated_transactions object

Associated transactions response

The network_selection_form object

Submission errors

Sample request body

Sample response body

Update submitted associated transactions

URL path parameters

Body field details

Update associated transactions response

Submission errors

Sample request body

Sample response body

List associated transactions

URL path parameter

Query parameter

Associated transactions list response

Submission errors

Sample response body

Retrieve dispute case

URL path parameters

Query parameter

Response body

List dispute cases

Query parameters

Response body

The dispute_details_response object

The network_case_status_details object

The regulation_details object

Sample response body

Create dispute case transition

URL path parameters

Body field details

The transition_details object

The chargeback_details object

Dispute case transitions

The transition reason_code field

Dispute transition response

Sample request body (CHARGEBACK_CREDIT)

Sample response body (CHARGEBACK_CREDIT)

Sample request body (CHARGEBACK_NO_CREDIT)

Sample response body (CHARGEBACK_NO_CREDIT)

Response action/reason code changes

Sample response body (ACTION/REASON CODE CHANGES)

Transition failure response

Error response

Sample response body (TRANSITION FAILURE RESPONSE)

Retrieve dispute case transition

URL path parameters

Retrieve dispute case transition response