/
65 minute read
July 6, 2022

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

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

dispute_details

object
Required

An object describing the disputed transaction, including the reason for the dispute.

Allowable Values:

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:

Existing transaction token.

dispute_amount

decimal
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.

dispute_reason

string
Required

The code describing the reason for the dispute.

Allowable Values:

processing_error_type_dispute_details

object
Optional

An object providing details about processing error disputes.

Allowable Values:

consumer_dispute_type_dispute_details

object
Optional

An object providing consumer dispute type dispute details.

Allowable Values:

fraud_dispute_type_details

object
Optional

An object providing fraud dispute type dispute details.

Allowable Values:

The dispute_details.dispute_reason field

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

  • 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_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.

The processing_error_type_dispute_details object
Fields Description

late_presentment_details

object
Conditionally required

An object providing late presentment details.

Allowable Values:

incorrect_transaction_code_details

object
Conditionally required

An object providing incorrect transaction code details.

Allowable Values:

incorrect_currency_details

object
Conditionally required

An object providing incorrect currency details.

Allowable Values:

incorrect_account_number_details

object
Conditionally required

An object providing incorrect account number details.

Allowable Values:

incorrect_transaction_amount_details

object
Conditionally required

An object providing incorrect transaction amount details.

Allowable Values:

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:

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

bigDecimal
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.

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:

cancelled_recurring_transaction_details

object
Conditionally required

An object providing cancelled recurring transaction details.

Allowable Values:

not_as_described_or_defective_ merchandise_details

object
Conditionally required

An object providing not as described or defective merchandise details.

Allowable Values:

credit_not_processed_details

object
Conditionally required

An object providing credit not processed details.

Allowable Values:

cancelled_merchandise_or_services_ details

object
Conditionally required

An object providing cancelled merchandise or service details.

Allowable Values:

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:

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

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

string
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 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 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_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.

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

cancellation_date

date
Conditionally required

The date the recurring transaction was 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, yyyy-MM-dd’T’HH:mm:ss.SSSZ, yyyy-MM-dd’T’HH:mm:ss.SSS’Z', EEE' or 'dd MMM yyyy HH:mm:ss zzz'

cancellation_reason

string
Conditionally required

The reason the cardholder cancelled 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, yyyy-MM-dd’T’HH:mm:ss.SSSZ, yyyy-MM-dd’T’HH:mm:ss.SSS’Z', EEE' or 'dd MMM yyyy HH:mm:ss zzz'

The not_as_described_or_defective_merchandise_details object
Fields Description

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, yyyy-MM-dd’T’HH:mm:ss.SSSZ, yyyy-MM-dd’T’HH:mm:ss.SSS’Z', EEE' or 'dd MMM yyyy HH:mm:ss zzz'

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, yyyy-MM-dd’T’HH:mm:ss.SSSZ, yyyy-MM-dd’T’HH:mm:ss.SSS’Z', EEE' or 'dd MMM yyyy HH:mm:ss zzz'

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, yyyy-MM-dd’T’HH:mm:ss.SSSZ, yyyy-MM-dd’T’HH:mm:ss.SSS’Z', EEE' or 'dd MMM yyyy HH:mm:ss zzz'

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, yyyy-MM-dd’T’HH:mm:ss.SSSZ, yyyy-MM-dd’T’HH:mm:ss.SSS’Z', EEE' or 'dd MMM yyyy HH:mm:ss zzz'

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:

yyyy-MM-dd

date_merchandise_or_service_was_ received

string
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:

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, SERVICES

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: yyyyy-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, yyyy-MM-dd’T’HH:mm:ss.SSSZ, yyyy-MM-dd’T’HH:mm:ss.SSS’Z', EEE' or 'dd MMM yyyy HH:mm:ss zzz'

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 cancelled.

Allowable Values:

true, false

cancellation_date

date
Conditionally required

The date the cardholder cancelled 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

Sample request body
JSON
Copied

Is this helpful?

Yes
No
Sample response body
JSON
Copied

Is this helpful?

Yes
No

Submit a batch of possibly associated transactions

Action: POST
Endpoint: /cases/{case_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
Fields Description

case_token

string
Required

The dispute case token.

Allowable Values:

A valid dispute case token.

Body field details
Fields Description

network_type

string
Required

The card network.

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.

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.

Allowable Values:

A valid authorization change reason.

associated_transactions

object
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.

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.

Allowable Values:

VISA

token

string
Returned

Unique identifier for the associated transaction on the Marqeta platform.

Allowable Values:

A valid uuid.

case_token

string
Returned

Token that indicates which dispute case this Associated Transaction belongs to.

Allowable Values:

A valid dispute case token.

network_phase

string
Returned

The network dispute state.

Allowable Values:

DISPUTE

transaction_date

string
Returned

The date 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:

A valid currency code.

merchant_name

string
Returned

The name of the merchant associated with this transaction.

Allowable Values:

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

string
Returned

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

string
Returned

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
Returned

Visa-specific transaction type (for network use only).

Allowable Values:

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:

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.

Allowable Values:

A valid credit change reason code.

auth_change_reason

string
Returned

The authorization change reason.

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
Copied

Is this helpful?

Yes
No
Sample response body
JSON
Copied

Is this helpful?

Yes
No

Update submitted associated transactions

Action: PUT
Endpoint: /cases/{case_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

case_token

string
Required

The dispute case token.

Allowable Values:

A valid dispute case token.

Body field details

For a description of the body field details and the fields in the associated_transactions object, see Submit a batch of possibly associated transactions.

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
Copied

Is this helpful?

Yes
No
Sample response body
JSON
Copied

Is this helpful?

Yes
No

List associated transactions

Action: GET
Endpoint: /cases/{case_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 parameters
Fields Description

case_token

string
Required

The dispute case token.

Allowable Values:

A valid dispute case token.

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.

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
Copied

Is this helpful?

Yes
No

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:

Existing dispute case token.

Response body
Fields Description

token

string
Returned

The unique identifier of the dispute case.

Allowable Values:

Existing transaction token.

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:

A valid short code.

user_token

string
Returned

Token that identifiers the user that made the original transaction.

Allowable Values:

A valid user uuid.

business_token

string
Returned

The token of the business involved in the dispute case.

Allowable Values:

A valid business uuid.

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:

A valid user.

dispute_details

object
Returned

The details of the dispute case.

Allowable Values:

created_time

date
Returned

The time that the dispute case was created.

Allowable Values:

Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ

updated_time

date
Returned

The time that the dispute case was last updated.

Allowable Values:

Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ

JSON
Copied

Is this helpful?

Yes
No

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:

An existing assignee.

associated_transaction_required

string
Optional

Returns dispute cases that have any associated transactions.

Allowable Values:

An existing associated transaction.

chargeback_token

string
Optional

Returns dispute cases associated with the specified chargeback.

Allowable Values:

Existing chargeback token.

dispute_state

string
Optional

Returns dispute cases that are in the specified dispute state.

Allowable Values:

INITIATED, REPRESENTMENT, PRE_ARBITRATION, ARBITRATION, CASE_WON, CASE_LOST, NETWORK_REJECTED, CLOSED

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 dispute cases in the CHARGEBACK_INITIATED case state and who are associated with the provided next actor.

Allowable Values:

An existing next actor.

original_transaction_token

string
Optional

Returns dispute cases associated with the specified token.

Allowable Values:

Existing transaction token.

reason

string
Optional

Returns disputes that are using the provided dispute reason.

Allowable Values:

state

string
Optional

Returns disputes that are currently in the provided case state.

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:

Existing user token.

Response body
Fields Description

token

string
Returned

The unique identifier of the dispute case.

Allowable Values:

Existing transaction token.

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:

A valid short code.

user_token

string
Returned

Token that identifiers the user that made the original transaction.

Allowable Values:

A valid user uuid.

business_token

string
Returned

The token of the business involved in the dispute case.

Allowable Values:

A valid business uuid.

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:

A valid user.

dispute_details

object
Returned

The details of the dispute case.

Allowable Values:

created_time

date
Returned

The time that the dispute case was created.

Allowable Values:

Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ

updated_time

date
Returned

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
Fields Description

original_transaction_token

string
Returned

The token of the original transaction under dispute.

Allowable Values:

Existing transaction token.

original_transaction_type

string
Returned

The type of the original transaction under dispute.

Allowable Values:

Existing transaction token.

dispute_amount

Decimal
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 to which the original transaction was made. Currently, only 480, which is USD, is supported.

Allowable Values:

A valid currency code

dispute_reason

string
Returned

The code describing the reason for the dispute.

Allowable Values:

See the Dispute Reason table.

dispute_state

string
Returned

The current dispute state.

Allowable Values:

INITIATED, REPRESENTMENT, PRE_ARBITRATION, ARBITRATION, CASE_WON, CASE_LOST, NETWORK_REJECTED, CLOSED

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.

Allowable Values:

A valid uuid.

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:

A valid uuid.

network_failure_response

string
Returned

Indicates the latest error that has occurred while the case is processed.

Allowable Values:

An error message returned from the network.

processing_error_type_dispute_details

object
Returned

An object providing details about processing error disputes.

Allowable Values:

consumer_dispute_type_dispute_details

object
Returned

Indicates the latest error that has occurred while the case is processed.

Allowable Values:

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_case_status_details

object
Returned

Available once the case state has been successfully transitioned to CHARGEBACK_INITIATED.

Allowable Values:

fraud_category_type_dispute_details

object
Returned

Additional information regarding a previously submitted fraud report in the network.

Allowable Values:

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

string
Returned

When the case was last updated in the network.

Allowable Values:

Format: yyyy-MM-dd, yyyy-MM-dd’T’HH:mm:ss.SSSZ, yyyy-MM-dd’T’HH:mm:ss.SSS’Z', EEE' or ' dd MMM yyyy HH:mm:ss zzz'

case_opened_date

string
Returned

Date when the case was opened in the network.

Allowable Values:

Format: yyyy-MM-dd

last_refresh_date

string
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 fraud_category_type_dispute_details object

Provides additional information regarding a previously submitted fraud report from the network in the contained fraud_report_details object.

Fields Description

fraud_type

string
Returned

Fraud type for the 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

fraud_type_code

string
Returned

Fraud type code for the fraud dispute case.

Allowable Values:

A valid code.

fraud_report_id

integer
Returned

Network-specific fraud report ID in the network.

Allowable Values:

A valid fraud report ID.

fraud_type_category

string
Returned

Network-specific fraud type category in the network.

Allowable Values:

A valid fraud type category.

Sample response body
JSON
Copied

Is this helpful?

Yes
No

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:

Existing dispute case token.

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:

reason_code

string
Required

Identifies the standardized reason for the transition.

Allowable Values:

created_by

string
Required

The user ID or name of the user who created the transition.

Allowable Values:

36 char max

assignee

string
Optional

The user ID or name of the user assigned to the dispute case.

Allowable Values:

36 char max

memo

string
Optional

Additional notes about the transition.

Allowable Values:

512 char max

transition_details

object
Required

An object containing the transition details.

Allowable Values:

The transition_details object
Fields Description

chargeback_details

object
Required

An object containing the chargeback details.

Allowable Values:

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.

The transition_details object
Fields Description

chargeback_details

object
Required

An object containing the chargeback details.

Allowable Values:

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 Resulting State Description

CREATE

OPEN

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.

RE_OPEN

OPEN

Reopens a dispute case to get additional information or documents. Dispute case state changes to OPEN.

CHARGEBACK_CREDIT

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.

CHARGEBACK_NO_CREDIT

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.

REVIEW

READY

Dispute case is ready to review. Dispute case state changes to READY.

ASSIGN

No change

Assigns a dispute case to a user. An assignee value is required. Does not change dispute case state.

CLOSE

CLOSED

Closes the dispute case. Dispute case state changes to CLOSED.

The reason_code field
Reason Code Description Related Actions

00

The dispute case was created.

CREATE

05

The dispute case is under review.

REVIEW

14

The Marqeta platform updated the dispute case.

CLOSE

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

26

The customer closed the dispute case.

CLOSE

28

A chargeback was created and the card holder was credited.

CHARGEBACK_CREDIT

29

A chargeback was created and the card holder was not credited.

CHARGEBACK_NO_CREDIT

30

The dispute case was closed automatically due to inactivity.

CLOSE

31

Invalid documents were uploaded.

DOCUMENTS_DELETED

32

Unreadable documents were uploaded.

DOCUMENTS_DELETED

33

Corrupted documents were uploaded.

DOCUMENTS_DELETED

34

The chargeback failed.

CHARGEBACK_CREDIT, CHARGEBACK_NO_CREDIT

35

The chargeback failed at the card network.

CHARGEBACK_CREDIT, CHARGEBACK_NO_CREDIT

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:

reason_code

string
Returned

Identifies the standardized reason for the transition.

Allowable Values:

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:

36 char max

assignee

string
Returned

The user ID or name of the user assigned to the dispute case.

Allowable Values:

36 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:

Sample request body (CHARGEBACK_CREDIT)
JSON
Copied

Is this helpful?

Yes
No
Sample response body (CHARGEBACK_CREDIT)
JSON
Copied

Is this helpful?

Yes
No
Sample request body (CHARGEBACK_NO_CREDIT)
JSON
Copied

Is this helpful?

Yes
No
Sample response body (CHARGEBACK_NO_CREDIT)
JSON
Copied

Is this helpful?

Yes
No

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:

Existing dispute case token.

Send a GET request to /cases to retrieve dispute case tokens.

transition_token

string
Required

The token of the transition to retrieve.

Allowable Values:

Existing dispute case transition token.

Send a GET request to /cases/{token}/transitions to retrieve dispute case transition tokens.

Retrieve dispute case transition response
Sample response body
JSON
Copied

Is this helpful?

Yes
No

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:

Existing dispute case token.

Send a GET request to /cases to retrieve dispute case tokens.

List dispute case transition response
Sample response body
JSON
Copied

Is this helpful?

Yes
No

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:

Existing dispute token.

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.

Allowable Values:

RESPOND_WITH_PREARB, RESPOND_WITH_ARB, RESPOND_WITH_PREARB_RESPONSE, ACCEPT_AND_CLOSE, CLOSE_WITH_CASE_WON

created_by

string
Optional

The user who is creating the transition.

Allowable Values:

256 char max

memo

string
Optional

A memo regarding the transaction.

Allowable Values:

prearbitration_details

object
Conditionally required

The details for prearbitration.

Allowable Values:

prearbitration_response_details

object
Conditionally required

The details of the prearbitration response.

Allowable Values:

Response body
Fields Description

token

string
Returned

The network dispute transition token.

Allowable Values:

256 char max

created_time

date
Returned

The time that the transition was created.

Allowable Values:

Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ

last_modified_time

date
Returned

The time that the transition was last modified.

Allowable Values:

Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ

case_token

string
Returned

The dispute case token.

Allowable Values:

256 char max

action

string
Returned

The action taken.

Allowable Values:

created_by

string
Returned

The user transitioning the dispute.

Allowable Values:

256 char max

memo

string
Conditionally returned

Memo at the Marqeta level for record-keeping and tracking.

Allowable Values:

256 char max

from_network_status

string
Returned

The dispute status from the network.

Allowable Values:

256 char max

to_network_status

string
Returned

The dispute status sent to the network.

Allowable Values:

256 char max

network_dispute_id

string
Returned

The network dispute ID.

Allowable Values:

256 char max

network_details

object
Returned

Dispute details from the network. Contents depend on the network state.

Allowable Values:

system_error_message

string
Conditionally returned

System error message.

Allowable Values:

network_error_message

string
Conditionally returned

Error message from the network.

Allowable Values:

The network_details object

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

Fields Description

prearbitration_details

object
Optional

Object defining the prearbitration details.

Allowable Values:

arbitration_details

object
Optional

Object defining the arbitration details.

Allowable Values:

network_state_details

object
Optional

Object defining the network state details.

Allowable Values:

dispute_state

string
Optional

The new dispute state.

Allowable Values:

A valid dispute state.

The prearbitration_details object

An object defining prearbitration details.

Fields Description

prearbitration_amount

bigDecimal
Required

The prearbitration amount.

Allowable Values:

32 bytes

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

An object defining prearbitration response details.

Fields Description

prearbitration_response_decision

string
Required

The prearbitration response decision.

Allowable Values:

ACCEPT_PARTIAL, DECLINE

partial_acceptance_amount

bigDecimal
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 action field

The following are possible Dispute Transition actions.

Action Description

ACCEPT_AND_CLOSE

Accept the proposed solution and close the dispute.

RESPOND_WITH_PREARB

Respond to the proposed solution with prearbitration.

RESPOND_WITH_PREARB_RESPONSE

Respond to the prearbitration response.

RESPOND_WITH_ARB

Respond with arbitration.

WAIT

Do nothing.

Sample request with prearbitration
JSON
Copied

Is this helpful?

Yes
No
Sample response with prearbitration
JSON
Copied

Is this helpful?

Yes
No
Sample request with arbitration
JSON
Copied

Is this helpful?

Yes
No
Sample response with arbitration
JSON
Copied

Is this helpful?

Yes
No
Sample accept and close dispute request
JSON
Copied

Is this helpful?

Yes
No
Sample accept and close dispute response
JSON
Copied

Is this helpful?

Yes
No
Sample close with case won dispute request
JSON
Copied

Is this helpful?

Yes
No
Sample close with case won dispute response
JSON
Copied

Is this helpful?

Yes
No

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

token

string
Required

The token of the dispute associated with the transitions you want to retrieve.

Allowable Values:

Existing dispute token.

Send a GET request to /cases to retrieve dispute tokens.

transition_token

string
Required

The token of the transition to retrieve.

Allowable Values:

Existing dispute transition token.

Send a GET request to /cases/{token}/transitions to retrieve dispute transition tokens.

The action field (response only)

The following are possible Dispute Transition actions.

Action Description

ACCEPT_AND_CLOSE

Accept the proposed solution and close the dispute.

RESPOND_WITH_PREARB

Respond to the proposed solution with prearbitration.

RESPOND_WITH_PREARB_RESPONSE

Respond to the prearbitration response.

RESPOND_WITH_ARB

Respond with arbitration.

WAIT

Do nothing.

The reason_code field (response only)
Reason Code Description Related Actions

00

The dispute was created.

CREATE

05

The dispute is under review.

REVIEW

14

The Marqeta platform updated the dispute.

CLOSE

22

The dispute was assigned to a user.

ASSIGN

23

The dispute was reopened.

RE_OPEN

24

The dispute was reopened to gather more information.

RE_OPEN

26

The customer closed the dispute.

CLOSE

28

A chargeback was created and the card holder was credited.

CHARGEBACK_CREDIT

29

A chargeback was created and the card holder was not credited.

CHARGEBACK_NO_CREDIT

30

The dispute was closed automatically due to inactivity.

CLOSE

31

Invalid documents were uploaded.

DOCUMENTS_DELETED

32

Unreadable documents were uploaded.

DOCUMENTS_DELETED

33

Corrupted documents were uploaded.

DOCUMENTS_DELETED

34

The chargeback failed.

CHARGEBACK_CREDIT, CHARGEBACK_NO_CREDIT

35

The chargeback failed at the card network.

CHARGEBACK_CREDIT, CHARGEBACK_NO_CREDIT

Sample response body
JSON
Copied

Is this helpful?

Yes
No

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:

Existing dispute token.

Send a GET request to /cases to retrieve dispute tokens.

Response fields
Fields Description

case_token

string
Returned

The token of the dispute associated with the transitions you want to list.

Allowable Values:

256 char max

action

string
Returned

The current action:

  • SUBMIT

  • ACCEPT_AND_CLOSE

  • RESPOND_WITH_PREARB

  • RESPOND_WITH_PREARB_RESPONSE

  • RESPOND_WITH_ARB

  • WAIT

  • ALLOCATION_ACKNOWLEDGED

  • REPRESENTMENT_RECEIVED

  • PREARB_RECEIVED

  • PREARB_DECLINED

  • PREARB_RESPONSE_DECLINED

  • ADJUSTMENT

Allowable Values:

256 char max

created_by

string
Returned

The user who created the action.

Allowable Values:

256 char max

memo

string
Optional

Free-form comments about the dispute.

Allowable Values:

256 char max

from_network_status

string
Returned

The dispute status from the network.

Allowable Values:

256 char max

to_network_status

string
Returned

The dispute status sent to the network.

Allowable Values:

256 char max

network_dispute_id

string
Returned

The network dispute ID.

Allowable Values:

256 char max

network_details

string
Returned

Dispute details from the network. Contents depend on the network state.

Allowable Values:

dispute_transition_token

number
Returned

The identifier for the dispute transition.

Allowable Values:

256 char max

prearbitration_details

object
Conditionally returned

Depends on the current state.

Allowable Values:

arbitration_details

object
Conditionally returned

Depends on the current state.

Allowable Values:

network_state_details

object
Conditionally returned

Depends on the current state.

Allowable Values:

dispute_state

string
Optional

The current dispute state.

Allowable Values:

created_time

string
Optional

The time that the dispute was created.

Allowable Values:

Format: yyyy-MM-dd, yyyy-MM-dd’T’HH:mm:ss.SSSZ, yyyy-MM-dd’T’HH:mm:ss.SSS’Z', EEE' or ' dd MMM yyyy HH:mm:ss zzz'

The network_state_details object

The following fields are returned in the response for second presentment in the network_state_details field.

JSON
Copied

Is this helpful?

Yes
No
The prearbitration_details object

The following fields are returned in a prearb response for in the prearbitration_details field.

JSON
Copied

Is this helpful?

Yes
No
The arbitration_details object

The following fields are returned in a arbitration response for the arbitration_details field.

JSON
Copied

Is this helpful?

Yes
No
Sample response body
JSON
Copied

Is this helpful?

Yes
No
The prearbitration_response_details object
Fields Description

prearbitration_response_decision

string
Required

The prearbitration response decision.

Allowable Values:

ACCEPT_PARTIAL, DECLINE

partial_acceptance_amount

bigDecimal
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:

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:

Existing dispute case token.

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 fowarded 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 document extension as appropriate for a supported file format: pdf, tiff, or jpeg.

document_data

bye
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:

Existing dispute case token.

case_token

string
Returned

The token identifying the dispute case you want to upload documents against.

Allowable Values:

Existing dispute case token.

document_name

string
Returned

The name of the document.

Allowable Values:

A valid document name.

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

string
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

string
Returned

The date and time when dispute was created.

Allowable Values:

Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ

updated_time

string
Returned

The date and time when 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
Copied

Is this helpful?

Yes
No
Sample response body
JSON
Copied

Is this helpful?

Yes
No

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:

Existing dispute case token.

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
Copied

Is this helpful?

Yes
No

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