Disputes (Visa) (Beta)
Note
This feature is currently in beta and subject to change. It also requires additional activation steps. To learn more about the Beta program for this feature and about activating it for your program, contact your Marqeta representative.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
Copy section link
Action: POST
Endpoint: /cases
Create a new dispute case by specifying the type and including the type-specific details object.
Body field details
Copy section link
| Fields | Description |
|---|---|
token
string
|
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
|
The type of case. Allowable Values:
|
memo
string
|
Free-form comments about the dispute. Allowable Values: 512 char max |
zendesk_ticket_id
string
|
ID for the Zendesk ticket. Allowable Values: 255 char max |
dispute_details
object
|
An object describing the disputed transaction, including the reason for the dispute. Allowable Values: See The dispute_details object table. |
The dispute_details object
Copy section link
Include this object in your request if the case type is DISPUTE.
| Fields | Description |
|---|---|
original_transaction_token
string
|
The token of the original transaction under dispute. Allowable Values: 36 char max |
original_transaction_id
integer
|
The ID of the original transaction under dispute. Allowable Values: Existing transaction ID. |
dispute_amount
number
|
The amount of funds under dispute. Allowable Values: Must be less than or equal to the original transaction amount. |
dispute_amount_change_reason
string
|
The reason the dispute amount has been changed from the transaction amount. Allowable Values:
Required if |
currency_code
string
|
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
|
The code describing the reason for the dispute. Allowable Values: See The dispute_details.dispute_reason field table. |
processing_error_type_dispute_details
object
|
An object providing details about processing error disputes. Allowable Values: |
consumer_dispute_type_dispute_details
object
|
An object providing consumer dispute type details. Allowable Values: |
duplicate_processing_or_paid_by_other_means_details
object
|
An object providing duplicate processing for paid by other means dispute type details. Allowable Values: |
additional_dispute_details
object
|
An object providing any additional information for a case. Allowable Values: See The additional_dispute_details object table. |
fraud_dispute_type_details
object
|
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
|
An object providing the fraud type request to the Visa network. Allowable Values: |
cardholder_contact_date
datetime
|
The contact date of the cardholder. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ |
The dispute_details.dispute_reason field
Copy section link
The following table describes the possible values for the dispute_details.dispute_reason field.
| Dispute Reason | Description |
|---|---|
SERVICE_NOT_PROVIDED_MERCHANDISE_NOT_ RECEIVED |
The goods or services were not provided. |
CANCELLED_RECURRING_TRANSACTION |
A recurring transaction was cancelled. |
NOT_AS_DESCRIBED_OR_DEFECTIVE_ MERCHANDISE |
The merchandise was not as described or defective. |
LATE_PRESENTMENT |
The card network cannot verify that the transaction amount was deposited within 30 days. |
NOT_AUTHORIZED_CARD_PRESENT |
An unauthorized user initiated the transaction and the card was present. |
NOT_AUTHORIZED_CARD_ABSENT |
An unauthorized user initiated the transaction and the card was not present. |
CREDIT_NOT_PROCESSED |
A credit was not processed. |
NON_RECEIPT_OF_CASH_OR_LOAD_ TRANSACTION_VALUE_AT_ATM |
The cardholder did not receive the full cash withdrawal or received only partial amount. |
NO_AUTHORIZATION |
|
INCORRECT_CURRENCY |
The currency is incorrect. |
INCORRECT_TRANSACTION_CODE |
The transaction code is incorrect. |
INCORRECT_CURRENCY_OR_TRANSACTION_ CODE |
The currency or transaction code is incorrect. |
INCORRECT_TRANSACTION_AMOUNT_OR_ ACCOUNT_NUMBER |
The transaction amount or transaction number is incorrect. |
INCORRECT_TRANSACTION_AMOUNT |
The transaction amount is incorrect. |
INCORRECT_ACCOUNT_NUMBER |
The account number is incorrect. |
EMV_LIABILITY_SHIFT_COUNTERFEIT_ FRAUD |
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 |
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. |
CANCELLED_MERCHANDISE_OR_SERVICES |
Merchandise or services were cancelled. |
DUPLICATE |
Duplicate processing or paid by other means. |
FRAUD_REPORT |
Report fraud to the Visa network. |
The processing_error_type_dispute_details object
Copy section link
| Fields | Description |
|---|---|
late_presentment_details
object
|
An object providing late presentment details. Allowable Values: See The late_presentment_details object table. |
incorrect_transaction_code_details
object
|
An object providing incorrect transaction code details. Allowable Values: |
incorrect_currency_details
object
|
An object providing incorrect currency details. Allowable Values: See The incorrect_currency_details object table. |
incorrect_account_number_details
object
|
An object providing incorrect account number details. Allowable Values: See The incorrect_account_number_details object table. |
incorrect_transaction_amount_details
object
|
An object providing incorrect transaction amount details. Allowable Values: |
duplicate_processing_or_paid_by_other_means_details
object
|
An object providing details about duplicate processing or paid by other means. Allowable Values: |
The late_presentment_details object
Copy section link
| Fields | Description |
|---|---|
account_status
string
|
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:
|
The incorrect_transaction_code_details object
Copy section link
| Fields | Description |
|---|---|
how_is_transaction_code_incorrect
string
|
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:
|
explain_why_the_credit_refund_was_processed_in_error
string
|
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
Copy section link
| Fields | Description |
|---|---|
incorrect_currency_reason
string
|
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:
|
what_was_the_correct_currency
integer
|
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
|
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:
|
The incorrect_account_number_details object
Copy section link
| Fields | Description |
|---|---|
is_the_account_number_on_the_issuers_master_file
boolean
|
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:
|
does_the_account_number_on_the_
receipt_match_the_cardholders_account_
number_or_token
boolean
|
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:
|
The incorrect_transaction_amount_details object
Copy section link
| Fields | Description |
|---|---|
what_is_the_amount_on_the_cardholders_receipt
number
|
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
|
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
|
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:
|
The consumer_dispute_type_dispute_details object
Copy section link
| Fields | Description |
|---|---|
service_not_provided_merchandise_not_
received_details
object
|
An object describing service or merchandise not provided details. Allowable Values: |
cancelled_recurring_transaction_details
object
|
An object providing cancelled recurring transaction details. Allowable Values: |
not_as_described_or_defective_
merchandise_details
object
|
An object providing not as described or defective merchandise details. Allowable Values: |
credit_not_processed_details
object
|
An object providing credit not processed details. Allowable Values: See The credit_not_processed_details object table. |
cancelled_merchandise_or_services_
details
object
|
An object providing cancelled merchandise or service details. Allowable Values: |
The service_not_provided_merchandise_not_received_details object
Copy section link
| Fields | Description |
|---|---|
detailed_description_of_what_was_
purchased_and_explanation_of_
the_dispute
string
|
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
|
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
|
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
|
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:
|
cancellation_date
date
|
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
|
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
|
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:
|
is_attempt_to_resolve_prohibited_by_
local_law_or_regulations
boolean
|
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:
|
provide_details_of_local_law_or_
regulations
string
|
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
|
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:
|
was_merchandise_delivered_to_wrong_
location
boolean
|
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:
|
address_of_agreed_location
string
|
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
|
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:
|
date_cardholder_returned_merchandise
date
|
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
|
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
|
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:
|
date_of_attempted_return
date
|
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
|
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
|
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:
|
visa_commercial_card_virtual_account_
indicator
boolean
|
Indicates whether the dispute involves a Visa Commercial Card Virtual Account. Allowable Values:
|
did_virtual_account_holder_suffer_
financial_loss
boolean
|
Indicates whether the virtual account holder suffered a financial loss. Allowable Values:
|
did_merchant_cancel_services
boolean
|
Indicates whether merchant/travel provider canceled services. Allowable Values:
|
date_merchant_cancelled_services
Date
|
Date merchant/travel provider cancelled services. Allowable Values: Format: yyyy-MM-dd |
explanation_dispute_prior_expected_
delivery_date
String
|
Explanation of dispute initiated prior to the expected delivery date. Allowable Values: |
The cancelled_recurring_transaction_details object
Copy section link
| Fields | Description |
|---|---|
date_cardholder_withdrew_permission_to_charge_the_payment_credential
date
|
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
|
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
|
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
|
The physical address of the merchant. Allowable Values: Valid |
contact_method_merchant_in_person_ind
boolean
|
Indicates if the merchant was contacted in person. Allowable Values:
|
contact_merchant_details
string
|
Contact details for the merchant. Allowable Values: |
contact_method_merchant_email_ind
boolean
|
Indicates if the merchant was contacted by email. Allowable Values:
|
contact_method_merchant_mail_ind
boolean
|
Indicates if the merchant was contacted by physical mail. Allowable Values:
|
contact_merchant_details_application_name
string
|
The application name. Allowable Values: 255 char max |
contact_method_merchant_webform_ind
boolean
|
Indicates if the merchant was contacted by webform. Allowable Values:
|
contact_merchant_details_phone_number
string
|
The phone number used to contact the merchant. Allowable Values: Valid phone number |
contact_merchant_details_email_address
string
|
The email address used to contact the merchant. Allowable Values: Valid email address |
contact_method_merchant_SMS_ind
string
|
Indicates if the merchant was contacted by SMS. Allowable Values:
|
contact_method_with_merchant_ind
boolean
|
Indicates if the method for contacting the merchant was provided. Allowable Values:
|
contact_method_merchant_call_center_ind
boolean
|
Indicates if the merchant was contacted by a call center. Allowable Values:
|
other_form_of_payment_ind
boolean
|
Indicates if another form of payment was provided. Allowable Values:
|
other_form_of_payment_desc
string
|
Description of the other form of payment.
Required if Allowable Values: 255 char max |
The not_as_described_or_defective_merchandise_details object
Copy section link
| Fields | Description |
|---|---|
merchant_refuse_advise
string
|
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:
|
not_as_described_or_defective
string
|
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:
|
merchandise_or_services
string
|
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:
|
date_the_cardholder_first_notified_
the_issuer_of_the_dispute
date
|
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
|
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:
|
is_attempt_to_resolve_prohibited_
by_local_law_or_regulations
boolean
|
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:
|
provide_details_of_local_law_
or_regulations
string
|
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
|
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:
|
date_cardholder_returned_the_
merchandise
date
|
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
|
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
|
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:
|
tracking_number
string
|
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
|
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
|
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
|
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:
|
explain_how_the_merchandise_
was_returned
string
|
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
|
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:
|
explain_prev_negotiation
string
|
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
|
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
|
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
|
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:
|
did_the_merchandise_or_services_
differ_from_what_was_described_
on_the_receipt
boolean
|
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:
|
provide_details_of_what_was_ordered_
and_not_as_described
string
|
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
|
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:
|
cancellation_date
date
|
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
|
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
|
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
|
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
Copy section link
| Fields | Description |
|---|---|
was_a_credit_voucher_voided_
transaction_receipt_or_refund_
acknowledgement_given
boolean
|
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:
|
is_the_credit_voucher_transaction_
receipt_or_refund_acknowledgement_
dated
boolean
|
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:
|
credit_voucher_transaction_receipt_or_
refund_acknowledgement_date
date
|
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
|
Date the cardholder cancelled the service or returned the merchandise. Allowable Values: Format: yyyy-MM-dd |
The cancelled_merchandise_or_services_details object
Copy section link
| Fields | Description |
|---|---|
merchandise_or_services
string
|
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:
|
describe_what_was_purchased
string
|
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
|
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
|
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:
|
is_attempt_to_resolve_prohibited_by_
local_law_or_regulations
boolean
|
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:
|
provide_details_of_local_law_
or_regulations
string
|
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
|
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:
|
date_of_return
date
|
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
|
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
|
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:
|
tracking_number
string
|
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
|
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
|
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:
|
date_of_attempted_return
date
|
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
|
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
|
Indicates whether the cardholder canceled. Allowable Values:
|
cancellation_date
date
|
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
|
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
|
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:
|
type_of_service
string
|
The type of service. Allowable Values:
|
date_of_service_or_expected_service
date
|
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
|
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:
|
merchant_refuse_advise
string
|
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:
|
The duplicate_processing_or_paid_by_other_means_details object
Copy section link
| Fields | Description |
|---|---|
error_type
string
|
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:
|
both_transactions_in_same_account
boolean
|
Indicates whether both transactions are for the same merchant and on the same card. Allowable Values:
|
other_transaction_reference_token
string
|
The clearing token of the duplicate original transaction.
Required when Allowable Values: 36 char max |
other_visa_transaction_reference_id
string
|
Used if the other transaction has been made with a different Visa card that has not been issued by Marqeta.
Required when Allowable Values: |
other_visa_transaction_mcsn
string
|
The MCSN of the duplicate transaction.
Required when Allowable Values: |
transaction_in_different_visa_account
boolean
|
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 Allowable Values:
|
is_other_transaction_with_same_merchant
boolean
|
Indicates whether the duplicate transaction is with the same merchant.
Required when Allowable Values:
|
provided_proof_of_other_means_type
string
|
The type of proof provided that the transaction was paid by other means.
Required when Allowable Values:
|
is_evidence_of_merchant_passed_funds_provided
boolean
|
If the user inputs Allowable Values:
|
cardholder_attempted_to_resolve
boolean
|
Indicates whether the cardholder attempted to resolve the dispute with the merchant.
Required when Allowable Values:
|
is_attempt_to_resolve_prohibited_by_local_law
boolean
|
Indicates whether the attempt to resolve prohibited by local law or regulations.
Required when Allowable Values:
|
other_visa_transaction_arn
string
|
The ARN from other transaction if it was paid with a Visa card.
Required when Allowable Values: |
other_visa_transaction_information
string
|
The transaction information from the other transaction if it was paid with a Visa card.
Required when Allowable Values: |
The additional_dispute_details object
Copy section link
| Fields | Description |
|---|---|
explanation_of_credit
string
|
Explanation of credit. Allowable Values: |
fraud_category_report_details
object
|
the fraud type request to the Visa network. Allowable Values: |
The fraud_category_type_dispute_details object
Copy section link
| Fields | Description |
|---|---|
fraud_type
string
|
The fraud type of a fraud dispute case. Allowable Values:
|
The fraud_dispute_type_details object
Copy section link
An object providing additional information for cases with a fraud dispute reason.
| Fields | Description |
|---|---|
general_fraud_type_dispute_details
object
|
An object describing general fraud type details. Allowable Values: |
The general_fraud_type_dispute_details object
Copy section link
| Fields | Description |
|---|---|
chip_on_card
boolean
|
This field is set to true if the card used for the original transaction had a chip. Allowable Values:
|
Response body
Copy section link
| Fields | Description |
|---|---|
token
string
|
The unique identifier of the dispute case. Allowable Values: 36 char max |
type
string
|
The type of case. Allowable Values:
|
memo
string
|
Free-form comments about the dispute. Allowable Values: 512 char max |
program_short_code
string
|
Indicates what program the case belongs to. Allowable Values: 10 char max |
user_token
string
|
Token that identifiers the user that made the original transaction. Allowable Values: 36 char max |
business_token
string
|
the token of the business involved in the dispute case. Allowable Values: 36 char max |
state
string
|
Indicates the current case state. Allowable Values:
|
assignee
string
|
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
|
ID for the Zendesk ticket. Allowable Values: 255 char max |
type_change_time
datetime
|
When the type was changed. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ |
dispute_details
object
|
The details of the dispute case. Allowable Values: See The dispute_details_response object table. |
created_time
datetime
|
The time that the dispute case was created. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ |
updated_time
datetime
|
The time that the dispute case was last updated. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ |
Sample request body (FRAUD)
Copy section link
The following shows a sample request body for submitting a fraud report.
Submit a batch of possibly associated transactions
Copy section link
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 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 dispute case.
Warning
Once an associated transaction selection form has been submitted, it cannot be resubmitted. The form can be updated.
URL path parameters
Copy section link
| Fields | Description |
|---|---|
token
string
|
The dispute case token. Allowable Values: 36 char max |
Body field details
Copy section link
| Fields | Description |
|---|---|
network_type
string
|
The card network. This should match the dispute case token provided in the path. Allowable Values:
|
credit_change_reason
string
|
The credit change reason.
This value is globally applied to all transactions in the list unless overridden by the Allowable Values: A valid credit change reason. |
auth_change_reason
string
|
The auth change reason.
This value is globally applied to all transactions in the list unless overridden by the Allowable Values: A valid authorization change reason. |
associated_transactions
array of objects
|
An array of transactions associated with the current dispute case.
Details for each transaction are defined in the Allowable Values: A valid array of associated_transaction objects. |
The associated_transactions object
Copy section link
| Fields | Description |
|---|---|
associated
boolean
|
Indicates whether the transaction is associated with the given transaction. Allowable Values:
|
associated_transaction_token
string
|
The unique identifier for the associated transaction. Allowable Values: A valid associated transaction token. |
credit_change_reason
string
|
The credit change reason for the specific associated transaction.
This value overrides the Allowable Values: A valid credit change reason. |
auth_change_reason
string
|
The auth change reason for the specific associated transaction.
This value overrides the Allowable Values: A valid authorization change reason. |
Associated transactions response
Copy section link
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
|
The card network. This matches the dispute case token provided in the path. Allowable Values:
|
token
string
|
Unique identifier for the associated transaction on the Marqeta platform. Allowable Values: 36 char max |
case_token
string
|
Token that indicates which dispute case this Associated Transaction belongs to. Allowable Values: 36 char max |
network_phase
string
|
The network dispute state. Allowable Values:
|
transaction_date
datetime
|
The date and time of the transaction. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ |
transaction_amount
number
|
The amount of money associated with this transaction. Allowable Values: A valid transaction amount. |
transaction_currency
string
|
Three-digit ISO 3166-1 numeric code for the currency used in the transaction. Allowable Values: 30 char max |
merchant_name
string
|
The name of the merchant associated with this transaction. Allowable Values: 22 char max |
network_submission_status
string
|
The status of the associated transaction on the network. Allowable Values:
|
first_network_submission_time
datetime
|
The date and time that 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
|
The date and time that 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
|
Visa-specific transaction type (for network use only). Allowable Values: 255 char max |
auth_code
string
|
Visa-specific authorization code (for network use only). Allowable Values: |
network_selection_form
object
|
Visa-specific network selection form, containing the Allowable Values: |
The network_selection_form object
Copy section link
| Fields | Description |
|---|---|
associated
boolean
|
Indicates whether the transaction is associated with the dispute case.
This field is set once the selection is submitted.
If Allowable Values:
|
credit_change_reason
string
|
The credit change reason.
Pattern: Allowable Values: A valid credit change reason code. |
auth_change_reason
string
|
The authorization change reason.
Pattern: Allowable Values: A valid auth change reason code. |
Submission errors
Copy section link
| Error Code | Description |
|---|---|
400 |
Indicates one of the following has occurred: One of the associated transaction forms was already submitted. A 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. |
Update submitted associated transactions
Copy section link
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
Copy section link
| Fields | Description |
|---|---|
token
string
|
The dispute case token. Allowable Values: 36 char max |
Body field details
Copy section link
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
Copy section link
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
Copy section link
| 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 (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. |
List associated transactions
Copy section link
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
Copy section link
| Fields | Description |
|---|---|
token
string
|
The dispute case token. Allowable Values: 36 char max |
Query parameter
Copy section link
| Fields | Description |
|---|---|
network_submission_status
string
|
The status of the associated transaction on the network. Allowable Values:
|
Associated transactions list response
Copy section link
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
Copy section link
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. |
Retrieve dispute case
Copy section link
Action: GET
Endpoint: /cases/{token}
Retrieve a specific dispute case.
URL path parameters
Copy section link
| Fields | Description |
|---|---|
token
string
|
The token of the dispute case to retrieve. Allowable Values: 36 char max |
Response body
Copy section link
| Fields | Description |
|---|---|
token
string
|
The unique identifier of the dispute case. Allowable Values: 36 char max |
type
string
|
The type of case. Allowable Values:
|
memo
string
|
Free-form comments about the dispute. Allowable Values: 512 char max |
program_short_code
string
|
Indicates what program the case belongs to. Allowable Values: 10 char max |
user_token
string
|
Token that identifiers the user that made the original transaction. Allowable Values: 36 char max |
business_token
string
|
The token of the business involved in the dispute case. Allowable Values: 36 char max |
state
string
|
Indicates the current case state. Allowable Values:
|
assignee
string
|
Indicates who is working on the case. This is updated by the case transition endpoint with reason code 22 and Allowable Values: 255 char max |
zendesk_ticket_id
string
|
ID for the Zendesk ticket. Allowable Values: 255 char max |
type_change_time
datetime
|
When the type was changed. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ |
dispute_details
object
|
The details of the dispute case. Allowable Values: |
created_time
datetime
|
The time that the dispute case was created. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ |
updated_time
datetime
|
The time that the dispute case was last updated. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ |
List dispute cases
Copy section link
Action: GET
Endpoint: /cases
List existing dispute cases. This endpoint supports sorting and pagination.
Query parameters
Copy section link
| Fields | Description |
|---|---|
3ds
boolean
|
Returns dispute cases that involve 3DS. Allowable Values:
|
assignee
string
|
Returns dispute cases associated with the specified assignee. Allowable Values: 255 char max |
associated_transaction_required
boolean
|
Returns dispute cases that have any associated transactions. Allowable Values:
|
chargeback_token
string
|
Returns dispute cases associated with the specified chargeback. Allowable Values: 36 char max |
dispute_state
array of strings
|
Returns a comma-separated list of dispute states that will be used to filter the resulting case. Allowable Values:
|
network_case_number
string
|
Returns dispute cases associated with the specified network case number. Allowable Values: A valid network case number. |
next_actor
string
|
Returns the dispute cases associated with the specified next actor, such as Allowable Values: An existing next actor. |
original_transaction_token
string
|
Returns dispute cases associated with the specified token. Allowable Values: 36 char max |
reason
string
|
Returns disputes that are using the provided dispute reason. Allowable Values: See Dispute reasons. |
state
string
|
Returns a comma-separated list of case states that will be used to filter the resulting case. Allowable Values:
|
type
string
|
Returns cases of the specified type. Allowable Values:
|
user_token
string
|
Returns dispute cases associated with the specified user. Allowable Values: 36 char max |
Response body
Copy section link
| Fields | Description |
|---|---|
token
string
|
The unique identifier of the dispute case. Allowable Values: 36 char max |
type
string
|
The type of case. Allowable Values:
|
memo
string
|
Free-form comments about the dispute. Allowable Values: 512 char max |
program_short_code
string
|
Indicates what program the case belongs to. Allowable Values: 10 char max |
user_token
string
|
Token that identifiers the user that made the original transaction. Allowable Values: 36 char max |
business_token
string
|
The token of the business involved in the dispute case. Allowable Values: 36 char max |
state
string
|
Indicates the current case state. Allowable Values:
|
assignee
string
|
Indicates who is working on the case. This is updated by the case transition endpoint with reason code 22 and Allowable Values: 255 char max |
zendesk_ticket_id
string
|
ID for the Zendesk ticket. Allowable Values: 255 char max |
type_change_time
datetime
|
When the type was changed. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ |
dispute_details
object
|
The details of the dispute case. Allowable Values: |
created_time
datetime
|
The time that the dispute case was created. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ |
updated_time
datetime
|
The time that the dispute case was last updated. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ |
The dispute_details_response object
Copy section link
| Fields | Description |
|---|---|
original_transaction_token
string
|
The token of the original transaction under dispute. Allowable Values: 36 char max |
original_transaction_id
integer
|
The ID of the original transaction under dispute. Allowable Values: 36 char max |
original_transaction_type
string
|
The type of the original transaction under dispute. Allowable Values: 255 char max |
dispute_amount
number
|
The amount of funds under dispute. Allowable Values: Must be less than or equal to the original transaction amount. |
dispute_amount_change_reason
string
|
The reason the dispute amount has been changed from the transaction amount. Allowable Values:
|
currency_code
string
|
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
|
The code describing the reason for the dispute. Allowable Values: See The dispute_details.dispute_reason field table. |
dispute_state
string
|
The current dispute state. Allowable Values:
|
chargeback_token
string
|
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 Allowable Values: 36 char max |
network
string
|
The network where the transaction took place. Allowable Values:
|
network_case_number
string
|
The network identifier for the dispute case. Allowable Values: A valid network case number. |
acquirer_fee
number
|
The acquirer fee for the transaction. Allowable Values: A valid number. |
associated_transaction_selection_
required
boolean
|
Indicates whether there are any transactions related to the original transaction. Allowable Values:
|
card_token
string
|
Unique identifier that maps back to the card that made the original transaction. Allowable Values: 36 char max |
processing_error_type_dispute_details
object
|
An object providing details about processing error disputes. Allowable Values: |
consumer_dispute_type_dispute_details
object
|
Indicates the latest error that has occurred while the case is processed. Allowable Values: |
network_case_status_details
object
|
Available once the case state has been successfully transitioned to Allowable Values: See The network_case_status_details object table. |
additional_dispute_details
object
|
An object providing any additional information for a case. Allowable Values: See The additional_dispute_details object table. |
fraud_dispute_type_details
object
|
Provides any additional information for cases with a fraud dispute reason.
Contains the Allowable Values:
|
network_failure_response
string
|
Indicates the latest error that has occurred while the case is processed. Allowable Values: 255 char max |
fraud_category_type_dispute_details
object
|
Additional information regarding a previously submitted fraud report in the network. Allowable Values: |
cardholder_contact_date
date
|
The contact date of the cardholder. Allowable Values: Format: yyyy-MM-dd |
provisional_credit_granted
boolean
|
Indicates whether the provisional credit was granted. Allowable Values:
|
regulation_type
string
|
The regulation type of the disputer case. Allowable Values: 255 char max |
The network_case_status_details object
Copy section link
| Fields | Description |
|---|---|
network
string
|
Network where the original transaction originated and is being processed. Allowable Values:
|
network_case_number
string
|
Network identifier for the case. Allowable Values: A valid network identifier. |
case_status
string
|
Network-specific value that represents the status of the case in the network. Allowable Values: A valid status value. |
current_case_amount
number
|
Current amount that has been disputed in the network. Allowable Values: A valid number. |
next_actor
string
|
Who is currently expected to act upon the case. Allowable Values:
|
days_to_act
integer
|
The number of days left to act for the Allowable Values: A valid integer. |
last_action_date
date
|
When the case was last updated in the network. Allowable Values: Format: yyyy-MM-dd |
case_opened_date
date
|
Date when the case was opened in the network. Allowable Values: Format: yyyy-MM-dd |
last_refresh_date
date
|
When the case was last refreshed from the network to the Marqeta system. Allowable Values: Format: yyyy-MM-dd |
allowable_actions
string
|
The actions allowed for the dispute case in the current dispute state. Allowable Values:
|
Create dispute case transition
Copy section link
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
Copy section link
| Fields | Description |
|---|---|
token
string
|
The token of the dispute case associated with the transition you want to create. Allowable Values: 36 char max Send a |
Body field details
Copy section link
| Fields | Description |
|---|---|
token
string
|
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
|
The action taken on the dispute case. Allowable Values: |
reason_code
string
|
Identifies the standardized reason for the transition. Allowable Values: See The reason_code field table. |
created_by
string
|
The user ID or name of the user who created the transition. Allowable Values: 255 char max |
assignee
string
|
The user ID or name of the user assigned to the dispute case. Allowable Values: 255 char max |
memo
string
|
Additional notes about the transition. Allowable Values: 16777215 char max |
transition_details
object
|
An object containing the transition details. Allowable Values: |
The transition_details object
Copy section link
| Fields | Description |
|---|---|
chargeback_details
object
|
An object containing the chargeback details. Allowable Values: |
The chargeback_details object
Copy section link
| Fields | Description |
|---|---|
attached_contents
string
|
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
Copy section link
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 | Resulting State | Description |
|---|---|---|
CREATE |
|
Creates a new dispute case.
A default action when a |
RE_OPEN |
|
Reopens a dispute case to get additional information or documents.
Dispute case state changes to |
NON_CHARGEBACK_CREDIT |
|
Smaller amount, no chargeback needed. |
CHARGEBACK_CREDIT |
|
Sends a Dispute case state changes to |
CHARGEBACK_NO_CREDIT |
|
Sends a Dispute case state changes to |
CHARGEBACK_SUBMIT |
|
Submitting dispute to the network. |
REVIEW |
|
Dispute case is ready to review.
Dispute case state changes to |
ASSIGN |
No change |
Assigns a dispute case to a user.
An |
KYC_OVERRIDE |
|
Documents are verified and the case is being closed. |
CLOSE |
|
Closes the dispute case.
Dispute case state changes to |
DOCUMENTS_DELETED |
No change |
Invalid documents were uploaded, documents are not in readable format or quality, or documents are corrupted and not human readable. |
REINSTATE_USER |
|
Failed to reinstate the user. |
REINSTATE_BUSINESS |
|
Failed to reinstate the business. |
WITHDRAW_AND_CLOSE |
|
No further action is needed, closing the case by withdrawing. |
WRITE_OFF |
No change |
Written off either by user or program. |
GRANT_CREDIT |
No change |
Granting provisional credit. |
REVERT_CREDIT |
No change |
Reverting provisional credit. |
CHANGE_CASE_TYPE |
No change |
Change case from |
The reason_code field
Copy section link
| Reason Code | Description | Related Actions |
|---|---|---|
00 |
The dispute case was created. |
|
05 |
The dispute case is under review. |
|
14 |
The Marqeta platform updated the dispute case. |
|
22 |
The dispute case was assigned to a user. |
|
23 |
The dispute case was reopened. |
|
24 |
The dispute case was reopened to gather more information. |
|
26 |
The customer closed the dispute case. |
|
28 |
A chargeback was created and the card holder was credited. |
|
29 |
A chargeback was created and the card holder was not credited. |
|
30 |
The dispute case was closed automatically due to inactivity. |
|
31 |
Invalid documents were uploaded. |
|
32 |
Unreadable documents were uploaded. |
|
33 |
Corrupted documents were uploaded. |
|
34 |
The chargeback failed. |
|
35 |
The chargeback failed at the card network. |
|
Dispute transition response
Copy section link
| Fields | Description |
|---|---|
case_token
string
|
The unique identifier of the dispute case. Allowable Values: 36 char max |
token
string
|
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
|
The action taken on the dispute case. Allowable Values: |
reason_code
string
|
Identifies the standardized reason for the transition. Allowable Values: See The reason_code field table. |
reason_description
string
|
A descriptive reason for the transition. Allowable Values: 36 char max |
created_by
string
|
The user ID or name of the user who created the transition. Allowable Values: 36 char max |
from_state
string
|
The state of the dispute case before the case transition was created. Allowable Values:
|
state
string
|
The resulting state of the dispute case after the transition was created. Allowable Values:
|
assignee
string
|
The user ID or name of the user assigned to the dispute case. Allowable Values: 255 char max |
memo
string
|
Additional notes about the transition. Allowable Values: 512 char max |
failure_reason
string
|
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
|
An object containing the transition details. Allowable Values: |
Retrieve dispute case transition
Copy section link
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
Copy section link
| Fields | Description |
|---|---|
token
string
|
The token of the dispute case associated with the transitions you want to retrieve. Allowable Values: 36 char max Send a |
transition_token
string
|
The token of the transition to retrieve. Allowable Values: 36 char max Send a |
Retrieve dispute case transition response
Copy section link
List dispute case transitions
Copy section link
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
Copy section link
| Fields | Description |
|---|---|
token
string
|
The token of the dispute case associated with the transitions you want to list. Allowable Values: 36 char max Send a |
Query parameters
Copy section link
| Fields | Description |
|---|---|
state
string
|
Filter dispute case transitions that contain the specified resulting state. Allowable Values:
|
List dispute case transition response
Copy section link
Create network dispute transition
Copy section link
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
Copy section link
| Fields | Description |
|---|---|
token
string
|
The token of the dispute associated with the transition you want to create. Allowable Values: 36 char max |
Request body
Copy section link
| Fields | Description |
|---|---|
action
string
|
The action to take:
Allowable Values:
|
created_by
string
|
The user who is creating the transition. Allowable Values: 255 char max |
memo
string
|
A memo regarding the transaction. Allowable Values: 16777215 char max |
network_details
object
|
The network details. Allowable Values: See The network_details object table. |
The network_details object
Copy section link
Depending on the transition, contains the prearbitration_details object or arbitration_details object.
| Fields | Description |
|---|---|
prearbitration_details
object
|
Object defining the prearbitration details. Allowable Values: See The prearbitration_details object table. |
prearbitration_response_details
object
|
Object defining the prearbitration response details. Allowable Values: See The prearbitration_response_details object table. |
arbitration_details
object
|
Object defining the arbitration details. Allowable Values: See The arbitration_details object table. |
representment_details
object
|
Object defining the network state details. Allowable Values: See The network_state_details object table. |
case_close_details
string
|
The new dispute state. Allowable Values: See The case_close_details object table. |
The prearbitration_details object
Copy section link
The details for prearbitration.
| Fields | Description |
|---|---|
amount
number
|
The amount in dispute. Allowable Values: 32 bytes |
attached_contents
string
|
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
|
The reason you are initiating prearbitration. Allowable Values: |
are_you_providing_new_information
boolean
|
Indicates whether this state change includes new information useful for the dispute. Allowable Values:
|
summary_of_new_information
string
|
A summary of the new information provided. Allowable Values: |
The prearbitration_response_details object
Copy section link
The details for prearbitration response.
| Fields | Description |
|---|---|
attached_contents
string
|
Content token for documents to be submitted to the network at the current dispute state. Allowable Values: 256 char max |
prearbitration_response_decision
string
|
The prearbitration response decision. Allowable Values:
|
amount
string
|
The partial acceptance amount. Allowable Values: 32 bytes |
why_are_you_not_accepting_liability
string
|
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
|
Indicates whether you have contacted the cardholder and reviewed the evidence and that the cardholder is continuing the dispute. Allowable Values:
|
explanation_of_why_cardholder_
continues_dispute
string
|
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
|
Indicates whether the cardholder’s name and address from the acquirer does not match issuer records. Allowable Values:
|
explanation_of_why_you_are_
continuing_the_dispute
string
|
An explanation of why you are continuing the dispute. Allowable Values: |
The arbitration_details object
Copy section link
The details for arbitration.
| Fields | Description |
|---|---|
attached_contents
string
|
Content token for documents to be submitted to the network at the current dispute state. Allowable Values: 256 char max |
The representment_details object
Copy section link
The details for representment transition.
| Fields | Description |
|---|---|
amount
number
|
The amount in dispute. Allowable Values: Min: 0.1 |
attached_contents
string
|
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
Copy section link
The details for case close transition details.
| Fields | Description |
|---|---|
write_off
boolean
|
Indicates whether the write-off due to the case lost happened. Allowable Values:
|
write_off_actor
string
|
The actor who performed the write-off. Allowable Values:
|
Network dispute transition response body
Copy section link
| Fields | Description |
|---|---|
token
string
|
The unique identifier of the dispute transition. Allowable Values: 36 char max |
created_time
datetime
|
The date and time that the transition was created. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ |
last_modified_time
datetime
|
The date and time that the transition was last modified. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ |
case_token
string
|
The token identifying the dispute case for the created the dispute transition. Allowable Values: 36 char max |
action
string
|
The action taken. Allowable Values:
|
created_by
string
|
The user ID or name of the user who created the transition. Allowable Values: 256 char max |
memo
string
|
A memo regarding the transaction. Allowable Values: 16777215 char max |
from_network_status
string
|
The network status before the transition. Allowable Values: 255 char max |
to_network_status
string
|
The new network status after the transition. Allowable Values: 255 char max |
network_dispute_id
string
|
The ID assigned to the dispute by the network. Allowable Values: 36 char max |
system_error_message
string
|
The error message for the system error. Allowable Values: 16777215 char max |
network_error_message
string
|
The error message for the network error. Allowable Values: 16777215 char max |
network_details
object
|
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
Copy section link
Depending on the transition, contains the prearbitration_details object or arbitration_details object.
| Fields | Description |
|---|---|
prearbitration_details
object
|
Object defining the prearbitration details. Allowable Values: See The prearbitration_details object table. |
prearbitration_response_details
object
|
Object defining the prearbitration response details. Allowable Values: See The prearbitration_response_details object table. |
arbitration_details
object
|
Object defining the arbitration details. Allowable Values: See The arbitration_details object table. |
representment_details
object
|
Object defining the network state details. Allowable Values: See The network_state_details object table. |
network_state_details
string
|
A JSON object, containing the details, received from the network. Allowable Values: |
dispute_state
string
|
Once the case’s state has been moved to Allowable Values:
|
case_close_details
string
|
The new dispute state. Allowable Values: See The case_close_details object table. |
Retrieve network dispute transition
Copy section link
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
Copy section link
| Fields | Description |
|---|---|
transition_token
string
|
The token of the transition to retrieve. Allowable Values: 36 char max Send a |
Response fields
Copy section link
See the Network dispute transition response table.
List network dispute transitions
Copy section link
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
Copy section link
| Fields | Description |
|---|---|
token
string
|
The token of the dispute associated with the transitions you want to list. Allowable Values: 36 char max Send a |
List network dispute transitions response fields
Copy section link
See the Network dispute transition response table.