/
75 minute read
June 5, 2023

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

zendesk_ticket_id

string
Optional

ID for the Zendesk ticket.

Allowable Values:

255 char max

dispute_details

object
Required

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

Allowable Values:

The dispute_details object

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

Fields Description

original_transaction_token

string
Required

The token of the original transaction under dispute.

Allowable Values:

36 char max

original_transaction_id

integer
Optional

The ID of the original transaction under dispute.

Allowable Values:

Existing transaction ID.

dispute_amount

number
Required

The amount of funds under dispute.

Allowable Values:

Must be less than or equal to the original transaction amount.

dispute_amount_change_reason

string
Conditionally required

The reason the dispute amount has been changed from the transaction amount.

Allowable Values:

MERCHANT_ISSUED_PARTIAL_REFUND, PARTIAL_DISPUTE, NOT_AS_DESCRIBED_PARTIAL, PARTIAL_SERVICE, PRORATED_REFUND, NOT_AUTHORIZED_FOR_FULL_AMOUNT

Required if dispute_amount is not equal to transaction amount.

currency_code

string
Optional

The currency in which the original transaction was made. Currently, only 480, which is USD, is supported.

Allowable Values:

30 char max

dispute_reason

string
Required

The code describing the reason for the dispute.

Allowable Values:

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

Allowable Values:

duplicate_processing_or_paid_by_other_means_details

object
Optional

An object providing duplicate processing for paid by other means dispute type details.

Allowable Values:

additional_dispute_details

object
Optional

An object providing any additional information for a case.

Allowable Values:

fraud_dispute_type_details

object
Optional

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

Allowable Values:

fraud_category_type_dispute_details

object
Optional

An object providing the fraud type request to the Visa network.

Allowable Values:

cardholder_contact_date

datetime
Optional

The contact date of the cardholder.

Allowable Values:

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

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.

DUPLICATE

Duplicate processing or paid by other means.

FRAUD_REPORT

Report fraud to the Visa network.

The processing_error_type_dispute_details object

Fields Description

late_presentment_details

object
Conditionally required

An object providing late presentment details.

Allowable Values:

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:

duplicate_processing_or_paid_by_other_means_details

object
Conditionally required

An object providing details about duplicate processing or paid by other means.

Allowable Values:

The late_presentment_details object
Fields Description

account_status

string
Conditionally required

The account status. Whether this field is optional or required depends on previous answers provided by the cardholder. To determine whether this field is required, see the decision tree for Processing Errors in Managing Visa Disputes.

Allowable Values:

ACCOUNT_CLOSED, CREDIT_PROBLEM, FRAUD, NONSUFFICIENT_FUNDS

The incorrect_transaction_code_details object
Fields Description

how_is_transaction_code_incorrect

string
Conditionally required

The token of the original transaction under dispute. Whether this field is optional or required depends on previous answers provided by the cardholder. To determine whether this field is required, see the decision tree for Processing Errors in Managing Visa Disputes.

Allowable Values:

CREDIT_INSTEAD_OF_REVERSAL_OR_ADJUSTMENT, CREDIT_POSTED_AS_DEBIT, DEBIT_POSTED_AS_CREDIT

explain_why_the_credit_refund_was_processed_in_error

string
Conditionally required

An explanation for why the credit refund was incorrectly processed. Whether this field is optional or required depends on previous answers provided by the cardholder. To determine whether this field is required, see the decision tree for Processing Errors in Managing Visa Disputes.

Allowable Values:

The incorrect_currency_details object
Fields Description

incorrect_currency_reason

string
Conditionally required

The reason for the incorrect currency. Whether this field is optional or required depends on previous answers provided by the cardholder. To determine whether this field is required, see the decision tree for Processing Errors in Managing Visa Disputes.

Allowable Values:

CURRENCY_DIFFERENCE, DCC_DISPUTE

what_was_the_correct_currency

integer
Conditionally required

An explanation for why the credit refund was incorrectly processed. Whether this field is optional or required depends on previous answers provided by the cardholder. To determine whether this field is required, see the decision tree for Processing Errors in Managing Visa Disputes.

Allowable Values:

An ISO 4217 currency number

certification_that_the_cardholder_did_ not_agree_to_dynamic_currency_ conversion_and_did_not_make_an_ active_choice

string
Conditionally required

Indicates that the cardholder did not agree to or make an active choice for dynamic currency conversion. Whether this field is optional or required depends on previous answers provided by the cardholder. To determine whether this field is required, see the decision tree for Processing Errors in Managing Visa Disputes.

Allowable Values:

true, false

The incorrect_account_number_details object
Fields Description

is_the_account_number_on_the_issuers_master_file

boolean
Conditionally required

Indicates whether the cardholder’s account number is also in the issuer’s file. Whether this field is optional or required depends on previous answers provided by the cardholder. To determine whether this field is required, see the decision tree for Processing Errors in Managing Visa Disputes.

Allowable Values:

true, false

does_the_account_number_on_the_ receipt_match_the_cardholders_account_ number_or_token

boolean
Conditionally required

Indicates whether the account numbers match. Whether this field is optional or required depends on previous answers provided by the cardholder. To determine whether this field is required, see the decision tree for Processing Errors in Managing Visa Disputes.

Allowable Values:

true, false

The incorrect_transaction_amount_details object
Fields Description

what_is_the_amount_on_the_cardholders_receipt

number
Conditionally required

The amount on the cardholder’s receipt. To determine whether this field is required, see the decision tree for Processing Errors in Managing Visa Disputes.

Allowable Values:

32 bytes

what_is_the_currency_on_the_cardholders_receipt

string
Conditionally required

The currency on the cardholder’s receipt. To determine whether this field is required, see the decision tree for Processing Errors in Managing Visa Disputes.

Allowable Values:

A valid currency code.

is_the_dispute_due_to_the_difference_ between_quoted_price_and_actual_ charges_made_by_the_merchant

boolean
Conditionally required

Indicates whether the dispute appeared due to the difference between quoted price and actual charges made by the merchant. To determine whether this field is required, see the decision tree for Processing Errors in Managing Visa Disputes.

Allowable Values:

true, false

The consumer_dispute_type_dispute_details object

Fields Description

service_not_provided_merchandise_not_ received_details

object
Conditionally required

An object describing service or merchandise not provided details.

Allowable Values:

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

detailed_description_of_what_was_ purchased_and_explanation_of_ the_dispute

string
Conditionally required

A description of what was purchased and explanation of the dispute. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes.

Allowable Values:

expected_receipt_date

date
Conditionally required

The expected date of receipt. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes.

Allowable Values:

Format: yyyy-MM-dd

expected_receipt_time

string
Conditionally required

The expected time of receipt. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes.

Allowable Values:

Format: hh-mm-ss

did_cardholder_cancel_prior_to_ the_expected_date

boolean
Conditionally required

Indicates whether the cardholder cancelled before the expected date. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes.

Allowable Values:

true, false

cancellation_date

date
Conditionally required

The date the service was canceled. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes.

Allowable Values:

Format: yyyy-MM-dd

cancellation_reason

string
Conditionally required

The reason the transaction was cancelled. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes.

Allowable Values:

did_cardholder_attempt_to_resolve_ dispute_with_merchant

boolean
Conditionally required

Indicates whether the cardholder attempted to resolve the dispute with the merchant. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes.

Allowable Values:

true, false

is_attempt_to_resolve_prohibited_by_ local_law_or_regulations

boolean
Conditionally required

Indicates whether the attempt to resolve the dispute is prohibited by local laws or regulations. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes.

Allowable Values:

true, false

provide_details_of_local_law_or_ regulations

string
Conditionally required

A description of the local laws or regulations that prohibit resolution of the dispute. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes.

Allowable Values:

merchandise_or_services

string
Conditionally required

Indicates whether the dispute is over merchandise or services. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes.

Allowable Values:

MERCHANDISE, SERVICES

was_merchandise_delivered_to_wrong_ location

boolean
Conditionally required

Indicates whether merchandise was delivered to the wrong location. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes.

Allowable Values:

true, false

address_of_agreed_location

string
Conditionally required

The address where merchandise was intended to be delivered. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes.

Allowable Values:

255 char max

did_cardholder_return_merchandise

boolean
Conditionally required

Indicates whether the cardholder returned the merchandise. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes.

Allowable Values:

true, false

date_cardholder_returned_merchandise

date
Conditionally required

If the cardholder returned the merchandise, the date it was returned. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes.

Allowable Values:

Format: yyyy-MM-dd

date_merchant_received_returned_ merchandise

date
Conditionally required

The date the merchant received the returned merchandise. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes.

Allowable Values:

Format: yyyy-MM-dd

did_cardholder_attempt_to_return_ merchandise

boolean
Conditionally required

Indicates whether the cardholder attempted to return the merchandise to the merchant. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes.

Allowable Values:

true, false

date_of_attempted_return

date
Conditionally required

The date the cardholder attempted to return the merchandise to the merchant. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes.

Allowable Values:

Format: yyyy-MM-dd

explain_how_merchandise_was_ returned

string
Conditionally required

Describes how the merchandise was returned. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes.

Allowable Values:

third_party_gift_card_indicator

boolean
Conditionally required

Indicates whether the purchase is a third-party gift card without an expiration date, where the merchandise or services were not provided by the third party due to insolvency or bankruptcy.

Allowable Values:

true, false

visa_commercial_card_virtual_account_ indicator

boolean
Conditionally required

Indicates whether the dispute involves a Visa Commercial Card Virtual Account.

Allowable Values:

true, false

did_virtual_account_holder_suffer_ financial_loss

boolean
Conditionally required

Indicates whether the virtual account holder suffered a financial loss.

Allowable Values:

true, false

did_merchant_cancel_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

date_cardholder_withdrew_permission_to_charge_the_payment_credential

date
Conditionally required

The date the cardholder withdrew permission to charge the payment credential. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes.

Allowable Values:

Format: yyyy-MM-dd

cancellation_reason

string
Conditionally required

The reason the cardholder canceled the recurring transaction. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes.

Allowable Values:

date_issuer_informed_merchant_of_ account_closure

date
Conditionally required

The date the card issuer informed the merchant that the account was closed. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes.

Allowable Values:

Format: yyyy-MM-dd

contact_merchant_details_physical_address

object
Conditionally required

The physical address of the merchant.

Allowable Values:

Valid contact_merchant_details_physical_address object

contact_method_merchant_in_person_ind

boolean
Conditionally required

Indicates if the merchant was contacted in person.

Allowable Values:

true, false

contact_merchant_details

string
Conditionally required

Contact details for the merchant.

Allowable Values:

contact_method_merchant_email_ind

boolean
Conditionally required

Indicates if the merchant was contacted by email.

Allowable Values:

true, false

contact_method_merchant_mail_ind

boolean
Conditionally required

Indicates if the merchant was contacted by physical mail.

Allowable Values:

true, false

contact_merchant_details_application_name

string
Conditionally required

The application name.

Allowable Values:

255 char max

contact_method_merchant_webform_ind

boolean
Conditionally required

Indicates if the merchant was contacted by webform.

Allowable Values:

true, false

contact_merchant_details_phone_number

string
Conditionally required

The phone number used to contact the merchant.

Allowable Values:

Valid phone number

contact_merchant_details_email_address

string
Conditionally required

The email address used to contact the merchant.

Allowable Values:

Valid email address

contact_method_merchant_SMS_ind

string
Conditionally required

Indicates if the merchant was contacted by SMS.

Allowable Values:

true, false

contact_method_with_merchant_ind

boolean
Conditionally required

Indicates if the method for contacting the merchant was provided.

Allowable Values:

true, false

contact_method_merchant_call_center_ind

boolean
Conditionally required

Indicates if the merchant was contacted by a call center.

Allowable Values:

true, false

other_form_of_payment_ind

boolean
Optional

Indicates if another form of payment was provided.

Allowable Values:

true, false

other_form_of_payment_desc

string
Conditionally required

Description of the other form of payment. Required if other_form_of_payment_ind is true.

Allowable Values:

255 char max

The not_as_described_or_defective_merchandise_details object
Fields Description

merchant_refuse_advise

string
Conditionally required

Provides clarification as to why merchant refused advise. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes.

Allowable Values:

MERCHANT_REFUSED_RETURN_AUTHORIZATION, MERCHANT_REFUSED_TO_ACCEPT_RETURNED_MERCHANDISE, MERCHANT_INFORMED_CARDHOLDER_NOT_TO_RETURN_MERCHANDISE

not_as_described_or_defective

string
Conditionally required

Indicates whether the merchandise was not as described or defective. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes.

Allowable Values:

NOT_AS_DESCRIBED, DEFECTIVE

merchandise_or_services

string
Conditionally required

Indicates whether the transaction involves merchandise or services. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes.

Allowable Values:

MERCHANDISE, SERVICES

date_the_cardholder_first_notified_ the_issuer_of_the_dispute

date
Conditionally required

The date the cardholder first notified the card issuer of the dispute. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes.

Allowable Values:

Format: yyyy-MM-dd

did_the_cardholder_attempt_to_ resolve_the_dispute_with_the_ merchant

boolean
Conditionally required

Indicates whether the cardholder attempted to resolve the dispute with the merchant. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes.

Allowable Values:

true, false

is_attempt_to_resolve_prohibited_ by_local_law_or_regulations

boolean
Conditionally required

Indicates whether the attempt to resolve the dispute is prohibited by local laws or regulations. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes.

Allowable Values:

true, false

provide_details_of_local_law_ or_regulations

string
Conditionally required

A detailed explanation of local laws or regulations that prevent resolution. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes.

Allowable Values:

did_the_cardholder_return_the_ merchandise

boolean
Conditionally required

Indicates whether the cardholder returned the merchandise. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes.

Allowable Values:

true, false

date_cardholder_returned_the_ merchandise

date
Conditionally required

The date the cardholder returned the merchandise. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes.

Allowable Values:

Format: yyyy-MM-dd

date_merchant_received_the_returned_ merchandise

date
Conditionally required

The date the merchant received the returned merchandise. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes.

Allowable Values:

Format: yyyy-MM-dd

return_method

string
Conditionally required

The method used to return the merchandise. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes.

Allowable Values:

FACE_TO_FACE, FED_EX, DHL, UPS, POSTAL_SERVICE, OTHER

tracking_number

string
Conditionally required

The tracking number of the returned merchandise. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes.

Allowable Values:

date_of_attempted_return

date
Conditionally required

The date the return was attempted. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes.

Allowable Values:

Format: yyyy-MM-dd

provide_a_detailed_description_ of_how_the_cardholder_attempted_ to_return_and_the_disposition_ of_the_merchandise

string
Conditionally required

A detailed description of how the cardholder attempted to return them merchandise and its current disposition. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes.

Allowable Values:

did_the_cardholder_attempt_to_return_ the_merchandise

boolean
Conditionally required

Indicates whether the cardholder attempted to return the merchandise to the merchant. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes.

Allowable Values:

true, false

explain_how_the_merchandise_ was_returned

string
Conditionally required

A description of how the merchandise was returned by the cardholder. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes.

Allowable Values:

cardholder_merchant_previous_negotiation_evidence

boolean
Conditionally required

Indicates whether the cardholder and merchant have negotiated. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes.

Allowable Values:

true, false

explain_prev_negotiation

string
Conditionally required

A description of the negotiation between the cardholder and the merchant. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes.

Allowable Values:

when_negotiations_begin

string
Conditionally required

The date when negotiations between the cardholder and merchant began. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes.

Allowable Values:

Format: yyyy-MM-dd

date_merchandise_or_service_was_ received

date
Conditionally required

The date the merchandise or service was received by the cardholder. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes.

Allowable Values:

Format: yyyy-MM-dd

does_the_dispute_involve_ merchandise_or_services_provided_ that_do_not_match_the_merchants_ verbal_description

boolean
Conditionally required

Indicates whether the dispute involves merchandise or services that do not match the merchant’s verbal description. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes.

Allowable Values:

true, false

did_the_merchandise_or_services_ differ_from_what_was_described_ on_the_receipt

boolean
Conditionally required

Indicates whether the merchandise or services differ from what was described on the receipt. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes.

Allowable Values:

true, false

provide_details_of_what_was_ordered_ and_not_as_described

string
Conditionally required

A description of what the cardholder ordered and how it is different from what was described by the merchant. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes.

Allowable Values:

did_the_cardholder_cancel_the_services

boolean
Conditionally required

Indicates whether the cardholder cancelled the services. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes.

Allowable Values:

true, false

cancellation_date

date
Conditionally required

The date the services were cancelled. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes.

Allowable Values:

Format: yyyy-MM-dd

cancellation_reason

string
Conditionally required

The reason the services were cancelled. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes.

Allowable Values:

what_was_ordered_and_how_it_was_ damaged_or_defective

string
Conditionally required

Describes what was ordered and whether it was damaged or defective. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes.

Allowable Values:

date_merchandise_was_received

date
Conditionally required

The date the merchandise was received. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes.

Allowable Values:

Format: yyyy-MM-dd

The credit_not_processed_details object
Fields Description

was_a_credit_voucher_voided_ transaction_receipt_or_refund_ acknowledgement_given

boolean
Conditionally required

Indicates whether a credit voucher voided the transaction receipt or a refund acknowledgment was given. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes.

Allowable Values:

true, false

is_the_credit_voucher_transaction_ receipt_or_refund_acknowledgement_ dated

boolean
Conditionally required

Indicates whether the credit voucher transaction receipt or refund acknowledgment has a date. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes.

Allowable Values:

true, false

credit_voucher_transaction_receipt_or_ refund_acknowledgement_date

date
Conditionally required

The date of the credit voucher transaction receipt or refund acknowledgment. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes.

Allowable Values:

Format: yyyy-MM-dd

date_cardholder_returned_cancelled_ merchandise

Date
Conditionally required

Date the cardholder cancelled the service or returned the merchandise.

Allowable Values:

Format: yyyy-MM-dd

The cancelled_merchandise_or_services_details object
Fields Description

merchandise_or_services

string
Conditionally required

Indicates whether the dispute is about merchandise or services. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes.

Allowable Values:

MERCHANDISE, SERVICE

describe_what_was_purchased

string
Conditionally required

A description of what was purchased. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes.

Allowable Values:

date_cardholder_received_or_expected_ to_receive_merchandise

date
Conditionally required

The date the cardholder received or expected to receive the merchandise. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes.

Allowable Values:

Format: yyyy-MM-dd

did_the_cardholder_attempt_to_resolve_ the_dispute_with_the_merchant

boolean
Conditionally required

Indicates whether the cardholder attempted to resolve the dispute with the merchant. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes.

Allowable Values:

true, false

is_attempt_to_resolve_prohibited_by_ local_law_or_regulations

boolean
Conditionally required

Indicates whether the attempt to resolve the dispute is prohibited by local laws or regulations. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes.

Allowable Values:

true, false

provide_details_of_local_law_ or_regulations

string
Conditionally required

A description of local laws or regulations that affect the dispute. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes.

Allowable Values:

did_the_cardholder_return_ the_merchandise

boolean
Conditionally required

Indicates whether the cardholder returned the merchandise. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes.

Allowable Values:

true, false

date_of_return

date
Conditionally required

The date the merchandise was returned by the cardholder. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes.

Allowable Values:

Format: yyyy-MM-dd

date_merchant_received_returned_ merchandise

date
Conditionally required

The date the returned merchandise was received by the merchant. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes.

Allowable Values:

Format: yyyy-MM-dd

return_method

string
Conditionally required

The method used by the cardholder to return the merchandise. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes.

Allowable Values:

FACE_TO_FACE, FED_EX, DHL, UPS, POSTAL_SERVICE, OTHER

tracking_number

string
Conditionally required

The tracking number of the returned merchandise. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes.

Allowable Values:

explain_how_the_merchandise_was_ returned

string
Conditionally required

Describes how the merchandise was returned by the cardholder. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes.

Allowable Values:

did_the_cardholder_attempt_to_return_ the_merchandise

boolean
Conditionally required

Indicates whether the cardholder attempted to return the merchandise. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes.

Allowable Values:

true, false

date_of_attempted_return

date
Conditionally required

The date of the attempted return of merchandise to the merchant. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes.

Allowable Values:

Format: yyyy-MM-dd

detailed_description_of_how_ the_cardholder_attempted_ to_return_and_the_disposition_ of_the_merchandise

string
Conditionally required

A detailed description of how the cardholder attempted to return the merchandise and its current disposition. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes.

Allowable Values:

did_cardholder_cancel

boolean
Conditionally required

Indicates whether the cardholder canceled.

Allowable Values:

true, false

cancellation_date

date
Conditionally required

The date the cardholder canceled the purchase. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes.

Allowable Values:

Format: yyyy-MM-dd

cancellation_reason

string
Conditionally required

The reason for the cancellation. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes.

Allowable Values:

was_cancellation_policy_provided

boolean
Conditionally required

Indicates whether a cancellation policy was provided to the cardholder. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes.

Allowable Values:

true, false

type_of_service

string
Conditionally required

The type of service.

Allowable Values:

TIMESHARE, GUARANTEED_RESERVATION, OTHER

date_of_service_or_expected_service

date
Conditionally required

The date of the service or expected service. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes.

Allowable Values:

Format yyyy-MM-dd

cancelled_guaranteed_reservation_ certification_selection

string
Conditionally required

Indicates the cancelled guaranteed reservation selection. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes.

Allowable Values:

CARDHOLDER_PROPERLY_CANCELLED, CARDHOLDER_ATTEMPTED_TO_CANCEL_WITHIN_24_HOURS_OF_CONFIRMATION, MERCHANT_BILLED_A_NO_SHOW_TRANSACTION_FOR_MORE_THAN_ONE_DAYS_ACCOMODATION

merchant_refuse_advise

string
Conditionally required

Provides clarification as to why merchant refused advise. To determine whether this field is required, see the decision tree for Consumer disputes in Managing Visa Disputes.

Allowable Values:

MERCHANT_REFUSED_RETURN_AUTHORIZATION, MERCHANT_REFUSED_TO_ACCEPT_RETURNED_MERCHANDISE, MERCHANT_INFORMED_CARDHOLDER_NOT_TO_RETURN_MERCHANDISE

The duplicate_processing_or_paid_by_other_means_details object

Fields Description

error_type

string
Required

Indicates whether the dispute is a duplicate or paid by other means. For more information on whether this field is required, see the decision tree for Processing errors in Managing Visa Disputes.

Allowable Values:

DUPLICATE, PAID_BY_OTHER_MEANS

both_transactions_in_same_account

boolean
Required

Indicates whether both transactions are for the same merchant and on the same card.

Allowable Values:

true, false

other_transaction_reference_token

string
Conditionally required

The clearing token of the duplicate original transaction. Required when both_transactions_in_same_account is set to true.

Allowable Values:

36 char max

other_visa_transaction_reference_id

string
Conditionally required

Used if the other transaction has been made with a different Visa card that has not been issued by Marqeta. Required when both_transactions_in_same_account is set to true and transaction_reference_token is not provided.

Allowable Values:

other_visa_transaction_mcsn

string
Conditionally required

The MCSN of the duplicate transaction. Required when visa_transaction_reference_id is provided and the visa_transaction_reference_id has an MSCN field.

Allowable Values:

transaction_in_different_visa_account

boolean
Conditionally required

This should be set if the other transaction is for the same merchant and on a different Visa card owned by the same issuer or cardholder. Required when both_transactions_in_same_account is set to false.

Allowable Values:

true, false

is_other_transaction_with_same_merchant

boolean
Conditionally required

Indicates whether the duplicate transaction is with the same merchant. Required when transaction_in_different_visa_account is set to false.

Allowable Values:

true, false

provided_proof_of_other_means_type

string
Conditionally required

The type of proof provided that the transaction was paid by other means. Required when is_other_transaction_with_same_merchant is set to false. For CASH_RECEIPT, THIRD_PARTY_VOUCHER, OTHER_CARD_STATEMENT, and OTHER a document must be uploaded and attached when submitting to the network. COPY_OF_CHECK must include a copy of the front and back of the check.

Allowable Values:

OTHER_TRANSACTION_ARN, OTHER_TRANSACTION_INFORMATION, CASH_RECEIPT, COPY_OF_CHECK, THIRD_PARTY_VOUCHER, OTHER_CARD_STATEMENT, OTHER

is_evidence_of_merchant_passed_funds_provided

boolean
Conditionally required

If the user inputs true, the attachments docs are required. If user inputs false, the case will be network rejected when submitted to the network and will be moved to OPEN_WITH_ACTION_REQUIRED. Required when provided_proof_of_other_means_type is set to THIRD_PARTY_VOUCHER.

Allowable Values:

true, false

cardholder_attempted_to_resolve

boolean
Conditionally required

Indicates whether the cardholder attempted to resolve the dispute with the merchant. Required when error_type is set to PAID_BY_OTHER_MEANS and when either transaction_in_different_visa_account is set to true or if is_other_transaction_with_same_merchant is set to true. Optional when error_type is set to DUPLICATE and when either transaction_in_different_visa_account is set to true or if is_other_transaction_with_same_merchant is set to true.

Allowable Values:

true, false

is_attempt_to_resolve_prohibited_by_local_law

boolean
Conditionally required

Indicates whether the attempt to resolve prohibited by local law or regulations. Required when cardholder_attempted_to_resolve is set to false. Visa requires for the cardholder to attempt to resolve the issue before submitting to the network. If the user inputs false and cardholder_attempted_to_resolve is also false, the case will be network rejected when submitted to the network and will be moved to OPEN_WITH_ACTION_REQUIRED.

Allowable Values:

true, false

other_visa_transaction_arn

string
Conditionally required

The ARN from other transaction if it was paid with a Visa card. Required when provided_proof_of_other_means_type is set to OTHER_TRANSACTION_ARN.

Allowable Values:

other_visa_transaction_information

string
Conditionally required

The transaction information from the other transaction if it was paid with a Visa card. Required when provided_proof_of_other_means_type is set to OTHER_TRANSACTION_INFORMATION.

Allowable Values:

The additional_dispute_details object

Fields Description

explanation_of_credit

string
Optional

Explanation of credit.

Allowable Values:

fraud_category_report_details

object
Optional

the fraud type request to the Visa network.

Allowable Values:

The fraud_category_type_dispute_details object

Fields Description

fraud_type

string
Optional

The fraud type of a fraud dispute case.

Allowable Values:

LOST, STOLEN, CARD_NOT_RECEIVED_AS_ISSUED, FRAUDULENT_APPLICATION, ISSUER_REPORTED_COUNTERFEIT, MISCELLANEOUS, FRAUDULENT_USE_OF_ACCOUNT_NUMBER, ACQUIRER_REPORTED_COUNTERFEIT, INCORRECT_PROCESSING, ACCOUNT_OR_CREDENTIALS_TAKEOVER, MERCHANT_MISREPRESENTATION, MANIPULATION_OF_ACCOUNT_HOLDER

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

Response body

Fields Description

token

string
Returned

The unique identifier of the dispute case.

Allowable Values:

36 char max

type

string
Returned

The type of case.

Allowable Values:

DISPUTE

memo

string
Returned

Free-form comments about the dispute.

Allowable Values:

512 char max

program_short_code

string
Returned

Indicates what program the case belongs to.

Allowable Values:

10 char max

user_token

string
Returned

Token that identifiers the user that made the original transaction.

Allowable Values:

36 char max

business_token

string
Returned

the token of the business involved in the dispute case.

Allowable Values:

36 char max

state

string
Returned

Indicates the current case state.

Allowable Values:

OPEN, OPEN_WITH_ACTION_REQUIRED, READY, CHARGEBACK_INITIATED, CLOSED

assignee

string
Returned

Indicates who is working on the case. This is updated by the case transition endpoint with reason_code 22 and ASSIGN action.

Allowable Values:

255 char max

zendesk_ticket_id

string
Optional

ID for the Zendesk ticket.

Allowable Values:

255 char max

type_change_time

datetime
Optional

When the type was changed.

Allowable Values:

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

dispute_details

object
Returned

The details of the dispute case.

Allowable Values:

created_time

datetime
Returned

The time that the dispute case was created.

Allowable Values:

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

updated_time

datetime
Returned

The time that the dispute case was last updated.

Allowable Values:

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

Sample request body

JSON
Copied

Is this helpful?

Yes
No

Sample response body

JSON
Copied

Is this helpful?

Yes
No

Sample request body (FRAUD)

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

JSON
Copied

Is this helpful?

Yes
No

Sample response body (FRAUD)

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

JSON
Copied

Is this helpful?

Yes
No

Submit a batch of possibly associated transactions

Action: POST
Endpoint: /cases/{token}/associated_transactions/selections

Submit a batch of possibly associated transactions to the VISA Network.

If the dispute case has any associated transactions, these are updated in the associated_transactions field for each transaction. If the submission is successful, the network_submission_status field is set to SUBMITTED.

You can globally set credit_change_reason and auth_change_reason values for all transactions included in the post. These values can be overridden for each associated transaction.

Each associated transaction is validated before submitting the batch to the network. If one associated transaction fails validation, the entire request fails. The failure occurs at the first violation and the validation 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

token

string
Required

The dispute case token.

Allowable Values:

36 char max

Body field details

Fields Description

network_type

string
Required

The card network. This should match the dispute case token provided in the path.

Allowable Values:

VISA

credit_change_reason

string
Optional

The credit change reason. This value is globally applied to all transactions in the list unless overridden by the credit_change_reason value for a specific transaction in the associated transaction object. Pattern: ^\d+$

Allowable Values:

A valid credit change reason.

auth_change_reason

string
Optional

The auth change reason. This value is globally applied to all transactions in the list unless overridden by the auth_change_reason value for a specific transaction in the associated transaction object. Pattern: ^\d+$

Allowable Values:

A valid authorization change reason.

associated_transactions

array of objects
Required

An array of transactions associated with the current dispute case. Details for each transaction are defined in the associated_transactions object table.

Allowable Values:

A valid array of associated_transaction objects.

The associated_transactions object

Fields Description

associated

boolean
Required

Indicates whether the transaction is associated with the given transaction.

Allowable Values:

true, false

associated_transaction_token

string
Required

The unique identifier for the associated transaction.

Allowable Values:

A valid associated transaction token.

credit_change_reason

string
Optional

The credit change reason for the specific associated transaction. This value overrides the credit_change_reason global value. Pattern: ^\d+$

Allowable Values:

A valid credit change reason.

auth_change_reason

string
Optional

The auth change reason for the specific associated transaction. This value overrides the auth_change_reason global value.

Allowable Values:

A valid authorization change reason.

Associated transactions response

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

Fields Description

network_type

string
Returned

The card network. This matches the dispute case token provided in the path.

Allowable Values:

VISA

token

string
Returned

Unique identifier for the associated transaction on the Marqeta platform.

Allowable Values:

36 char max

case_token

string
Returned

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

Allowable Values:

36 char max

network_phase

string
Returned

The network dispute state.

Allowable Values:

DISPUTE

transaction_date

datetime
Returned

The date and time of the transaction.

Allowable Values:

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

transaction_amount

number
Returned

The amount of money associated with this transaction.

Allowable Values:

A valid transaction amount.

transaction_currency

string
Returned

Three-digit ISO 3166-1 numeric code for the currency used in the transaction.

Allowable Values:

30 char max

merchant_name

string
Returned

The name of the merchant associated with this transaction.

Allowable Values:

22 char max

network_submission_status

string
Returned

The status of the associated transaction on the network.

Allowable Values:

PENDING—The initial value before the associated transaction is submitted to the network.

SUBMISSION_FAILED—The submission of the associated transaction to the network failed.

SUBMITTED—The associated transaction was successfully submitted to the network.

UPDATE_FAILED—The update to the associated transaction failed.

first_network_submission_time

datetime
Returned

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

255 char max

auth_code

string
Returned

Visa-specific authorization code (for network use only).

Allowable Values:

network_selection_form

object
Returned

Visa-specific network selection form, containing the credit_change_reason and auth_change_reason code values that were set during the associated transaction selection in the POST or PUT request. These values are overwritten whenever an attempt is made to update the selection.

Allowable Values:

The network_selection_form object

Fields Description

associated

boolean
Returned

Indicates whether the transaction is associated with the dispute case. This field is set once the selection is submitted. If true, the transaction is associated with the dispute case.

Allowable Values:

True, False

credit_change_reason

string
Returned

The credit change reason. Pattern: ^\d+$

Allowable Values:

A valid credit change reason code.

auth_change_reason

string
Returned

The authorization change reason. Pattern: ^\d+$

Allowable Values:

A valid auth change reason code.

Submission errors

Error Code Description

400

Indicates one of the following has occurred:

One of the associated transaction forms was already submitted.

A network_type value does not match the one for the dispute.

One of the associated transaction forms has a missing required field.

404

Indicates one of the following has occurred:

The dispute case token was not found.

One of the associated transactions was not found.

The user attempts to submit a form for a dispute case that doesn’t belong to the specified program short code.

One of the associated transactions does not belong to the dispute case.

Sample request body

JSON
Copied

Is this helpful?

Yes
No

Sample response body

JSON
Copied

Is this helpful?

Yes
No

Update submitted associated transactions

Action: PUT
Endpoint: /cases/{token}/associated_transactions/selections

Update a list of selection forms that have already been submitted for a given dispute case.

You can globally set credit_change_reason and auth_change_reason values for all transactions included in the post. These values can be overridden for each associated transaction.

Each associated transaction is validated before submitting the batch to the network. If one associated transaction fails validation, the entire request fails. The failure occurs at the first violation and the remaining payload is not validated. The response includes the list of affected associated transactions. If one of the potentially associated transactions has already been submitted to the network, an error is returned.

The response provides a list of transactions. Those with the associated field set to true are associated with the case.

URL path parameters

Fields Description

token

string
Required

The dispute case token.

Allowable Values:

36 char max

Body field details

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

Update associated transactions response

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

Submission errors

Error Code Description

400

Indicates one of the following has occurred:

The user attempted to update the associated transactions of a dispute case that has moved to the CHARGEBACK_INITIATED state.

(Phase 2) The user attempted to update the associated transactions of a dispute case with a dispute transition that has moved beyond PreArbitration.

The user attempted to update an associated transaction with a network type that doesn’t match the network type for the dispute.

One of the associated transactions has a missing required field.

404

Indicates one of the following has occurred:

The dispute case token was not found.

One of the associated transactions was not found.

The user attempted to update a dispute case that doesn’t belong to the specified program.

One of the associated transactions does not belong to the dispute case.

Sample request body

JSON
Copied

Is this helpful?

Yes
No

Sample response body

JSON
Copied

Is this helpful?

Yes
No

List associated transactions

Action: GET
Endpoint: /cases/{token}/associated_transactions

Get a list of transactions associated with a given dispute case. Use the network_phase query field to help distinguish associated transactions between the different phases in the network.

URL path parameter

Fields Description

token

string
Required

The dispute case token.

Allowable Values:

36 char max

Query parameter

Fields Description

network_submission_status

string
Optional

The status of the associated transaction on the network.

Allowable Values:

DISPUTE

Associated transactions list response

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

Submission errors

Error Code

Description

400

Indicates that one of the query parameters has invalid values.

404

Indicates one of the following has occurred:

The dispute case token was not found.

The user attempted to list the associated transactions of a dispute case that doesn’t belong to their program.

Sample response body

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

36 char max

Response body

Fields Description

token

string
Returned

The unique identifier of the dispute case.

Allowable Values:

36 char max

type

string
Returned

The type of case.

Allowable Values:

DISPUTE

memo

string
Returned

Free-form comments about the dispute.

Allowable Values:

512 char max

program_short_code

string
Returned

Indicates what program the case belongs to.

Allowable Values:

10 char max

user_token

string
Returned

Token that identifiers the user that made the original transaction.

Allowable Values:

36 char max

business_token

string
Returned

The token of the business involved in the dispute case.

Allowable Values:

36 char max

state

string
Returned

Indicates the current case state.

Allowable Values:

OPEN, OPEN_WITH_ACTION_REQUIRED, READY, CHARGEBACK_INITIATED, CLOSED

assignee

string
Returned

Indicates who is working on the case. This is updated by the case transition endpoint with reason code 22 and ASSIGN action.

Allowable Values:

255 char max

zendesk_ticket_id

string
Optional

ID for the Zendesk ticket.

Allowable Values:

255 char max

type_change_time

datetime
Optional

When the type was changed.

Allowable Values:

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

dispute_details

object
Returned

The details of the dispute case.

Allowable Values:

created_time

datetime
Returned

The time that the dispute case was created.

Allowable Values:

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

updated_time

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

255 char max

associated_transaction_required

boolean
Optional

Returns dispute cases that have any associated transactions.

Allowable Values:

true, false

chargeback_token

string
Optional

Returns dispute cases associated with the specified chargeback.

Allowable Values:

36 char max

dispute_state

array of strings
Optional

Returns a comma-separated list of dispute states that will be used to filter the resulting case.

Allowable Values:

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

network_case_number

string
Optional

Returns dispute cases associated with the specified network case number.

Allowable Values:

A valid network case number.

next_actor

string
Optional

Returns the dispute cases associated with the specified next actor, such as ISSUER, ACQUIRER, COURT, or DISPUTE_COMPLETED.

Allowable Values:

An existing next actor.

original_transaction_token

string
Optional

Returns dispute cases associated with the specified token.

Allowable Values:

36 char max

reason

string
Optional

Returns disputes that are using the provided dispute reason.

Allowable Values:

state

string
Optional

Returns a comma-separated list of case states that will be used to filter the resulting case.

Allowable Values:

OPEN, OPEN_WITH_ACTION_REQUIRED, READY, CHARGEBACK_INITIATED, CLOSED

type

string
Optional

Returns cases of the specified type.

Allowable Values:

DISPUTE

user_token

string
Optional

Returns dispute cases associated with the specified user.

Allowable Values:

36 char max

Response body

Fields Description

token

string
Returned

The unique identifier of the dispute case.

Allowable Values:

36 char max

type

string
Returned

The type of case.

Allowable Values:

DISPUTE

memo

string
Returned

Free-form comments about the dispute.

Allowable Values:

512 char max

program_short_code

string
Returned

Indicates what program the case belongs to.

Allowable Values:

10 char max

user_token

string
Returned

Token that identifiers the user that made the original transaction.

Allowable Values:

36 char max

business_token

string
Returned

The token of the business involved in the dispute case.

Allowable Values:

36 char max

state

string
Returned

Indicates the current case state.

Allowable Values:

OPEN, OPEN_WITH_ACTION_REQUIRED, READY, CHARGEBACK_INITIATED, CLOSED

assignee

string
Returned

Indicates who is working on the case. This is updated by the case transition endpoint with reason code 22 and ASSIGN action.

Allowable Values:

255 char max

zendesk_ticket_id

string
Optional

ID for the Zendesk ticket.

Allowable Values:

255 char max

type_change_time

datetime
Optional

When the type was changed.

Allowable Values:

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

dispute_details

object
Returned

The details of the dispute case.

Allowable Values:

created_time

datetime
Returned

The time that the dispute case was created.

Allowable Values:

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

updated_time

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

36 char max

original_transaction_id

integer
Returned

The ID of the original transaction under dispute.

Allowable Values:

36 char max

original_transaction_type

string
Returned

The type of the original transaction under dispute.

Allowable Values:

255 char max

dispute_amount

number
Returned

The amount of funds under dispute.

Allowable Values:

Must be less than or equal to the original transaction amount.

dispute_amount_change_reason

string
Returned

The reason the dispute amount has been changed from the transaction amount.

Allowable Values:

MERCHANT_ISSUED_PARTIAL_REFUND, PARTIAL_DISPUTE, NOT_AS_DESCRIBED_PARTIAL, PARTIAL_SERVICE, PRORATED_REFUND, NOT_AUTHORIZED_FOR_FULL_AMOUNT

currency_code

string
Returned

The currency in which the original transaction was made. Currently, only 480, which is USD, is supported.

Allowable Values:

30 char max

dispute_reason

string
Returned

The code describing the reason for the dispute.

Allowable Values:

dispute_state

string
Returned

The current dispute state.

Allowable Values:

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

chargeback_token

string
Returned

Indicates what is the associated chargeback in the legacy system. This is useful to map the current chargeback webhooks back a dispute case. This field is populated once the case state has moved to CHARGEBACK_INITIATED.

Allowable Values:

36 char max

network

string
Returned

The network where the transaction took place.

Allowable Values:

VISA

network_case_number

string
Returned

The network identifier for the dispute case.

Allowable Values:

A valid network case number.

acquirer_fee

number
Returned

The acquirer fee for the transaction.

Allowable Values:

A valid number.

associated_transaction_selection_ required

boolean
Returned

Indicates whether there are any transactions related to the original transaction.

Allowable Values:

true, false

card_token

string
Returned

Unique identifier that maps back to the card that made the original transaction.

Allowable Values:

36 char max

processing_error_type_dispute_details

object
Returned

An object providing details about processing error disputes.

Allowable Values:

consumer_dispute_type_dispute_details

object
Returned

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

Allowable Values:

network_case_status_details

object
Returned

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

Allowable Values:

additional_dispute_details

object
Optional

An object providing any additional information for a case.

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_failure_response

string
Returned

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

Allowable Values:

255 char max

fraud_category_type_dispute_details

object
Returned

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

Allowable Values:

cardholder_contact_date

date
Returned

The contact date of the cardholder.

Allowable Values:

Format: yyyy-MM-dd

provisional_credit_granted

boolean
Returned

Indicates whether the provisional credit was granted.

Allowable Values:

true, false

regulation_type

string
Returned

The regulation type of the disputer case.

Allowable Values:

255 char max

The network_case_status_details object

Fields Description

network

string
Returned

Network where the original transaction originated and is being processed.

Allowable Values:

VISA

network_case_number

string
Returned

Network identifier for the case.

Allowable Values:

A valid network identifier.

case_status

string
Returned

Network-specific value that represents the status of the case in the network.

Allowable Values:

A valid status value.

current_case_amount

number
Returned

Current amount that has been disputed in the network.

Allowable Values:

A valid number.

next_actor

string
Returned

Who is currently expected to act upon the case.

Allowable Values:

ISSUER, ACQUIRER, DISPUTE_COMPLETED, UNKNOWN

days_to_act

integer
Returned

The number of days left to act for the next_actor before the dispute case defaults.

Allowable Values:

A valid integer.

last_action_date

date
Returned

When the case was last updated in the network.

Allowable Values:

Format: yyyy-MM-dd

case_opened_date

date
Returned

Date when the case was opened in the network.

Allowable Values:

Format: yyyy-MM-dd

last_refresh_date

date
Returned

When the case was last refreshed from the network to the Marqeta system.

Allowable Values:

Format: yyyy-MM-dd

allowable_actions

string
Returned

The actions allowed for the dispute case in the current dispute state.

Allowable Values:

SUBMIT, ACCEPT_AND_CLOSE, RESPOND_WITH_PREARB, RESPOND_WITH_PREARB_RESPONSE, RESPOND_WITH_ARB, WAIT, ALLOCATION_ACKNOWLEDGED, REPRESENTMENT_RECEIVED, PREARB_RECEIVED, PREARB_ACCEPTED, PREARB_DECLINED, PREARB_RESPONSE_DECLINED, ADJUSTMENT, CLOSE_WITH_CASE_WON, CLOSE_WITH_NETWORK_REJECTED

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:

36 char max

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

Body field details

Fields Description

token

string
Optional

The unique identifier of the dispute case transition. If you do not include a token, the system generates a token automatically.

Allowable Values:

36 char max

action

string
Required

The action taken on the dispute case.

Allowable Values:

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:

255 char max

assignee

string
Optional

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

Allowable Values:

255 char max

memo

string
Optional

Additional notes about the transition.

Allowable Values:

16777215 char max

transition_details

object
Required

An object containing the transition details.

Allowable Values:

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.

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.

NON_CHARGEBACK_CREDIT

CLOSED

Smaller amount, no chargeback needed.

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.

CHARGEBACK_SUBMIT

CHARGEBACK_INITIATED

Submitting dispute 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.

KYC_OVERRIDE

CLOSED

Documents are verified and the case is being closed.

CLOSE

CLOSED

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

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

CLOSED

Failed to reinstate the user.

REINSTATE_BUSINESS

CLOSED

Failed to reinstate the business.

WITHDRAW_AND_CLOSE

CLOSED

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 DISPUTE type to the LEGACY_DISPUTE type.

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:

OPEN, OPEN_WITH_ACTION_REQUIRED, READY, CHARGEBACK_INITIATED, CLOSED

assignee

string
Returned

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

Allowable Values:

255 char max

memo

string
Returned

Additional notes about the transition.

Allowable Values:

512 char max

failure_reason

string
Returned

If an error occurred while attempting to transition the dispute case, this field provides a brief description of the failure.

Allowable Values:

512 char max

transition_details

object
Returned

An object containing the transition details.

Allowable Values:

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:

36 char max

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

transition_token

string
Required

The token of the transition to retrieve.

Allowable Values:

36 char max

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

Retrieve dispute case transition response

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:

36 char max

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

Query parameters

Fields Description

state

string
Optional

Filter dispute case transitions that contain the specified resulting state.

Allowable Values:

OPEN, OPEN_WITH_ACTION_REQUIRED, READY, CHARGEBACK_INITIATED, CLOSED

List dispute case transition response

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:

36 char max

Submit a GET request to /cases to retrieve case tokens.

Request body

Fields Description

action

string
Required

The action to take:

  • RESPOND_WITH_PREARB: Action to move a dispute to prearbitration with Visa.

  • RESPOND_WITH_ARB: Action to move a prearbitration disputes to arbitration.

  • RESPOND_WITH_PREARB_RESPONSE: Respond to the prearbitration response.

  • ACCEPT_AND_CLOSE: Action to accept the dispute decision and close the dispute.

  • CLOSE_WITH_CASE_WON: Close with case won dispute transition.

  • CLOSE_WITH_NETWORK_REJECTED: Close with network rejected.

  • REPRESENTMENT_RECEIVED: Indicates that representment was received.

Allowable Values:

RESPOND_WITH_PREARB, RESPOND_WITH_ARB, RESPOND_WITH_PREARB_RESPONSE, ACCEPT_AND_CLOSE, CLOSE_WITH_CASE_WON, CLOSE_WITH_NETWORK_REJECTED, REPRESENTMENT_RECEIVED

created_by

string
Optional

The user who is creating the transition.

Allowable Values:

255 char max

memo

string
Optional

A memo regarding the transaction.

Allowable Values:

16777215 char max

network_details

object
Conditionally required

The network details.

Allowable Values:

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:

prearbitration_response_details

object
Optional

Object defining the prearbitration response details.

Allowable Values:

arbitration_details

object
Optional

Object defining the arbitration details.

Allowable Values:

representment_details

object
Optional

Object defining the network state details.

Allowable Values:

case_close_details

string
Optional

The new dispute state.

Allowable Values:

The prearbitration_details object

The details for prearbitration.

Fields Description

amount

number
Required

The amount in dispute.

Allowable Values:

32 bytes

attached_contents

string
Optional

Content token for documents to be submitted to the network at the current dispute state.

Allowable Values:

256 char max

why_are_you_initiating_prearbitration

string
Required

The reason you are initiating prearbitration.

Allowable Values:

are_you_providing_new_information

boolean
Required

Indicates whether this state change includes new information useful for the dispute.

Allowable Values:

true, false

summary_of_new_information

string
Conditionally required.

A summary of the new information provided.

Allowable Values:

The prearbitration_response_details object

The details for prearbitration response.

Fields Description

attached_contents

string
Optional

Content token for documents to be submitted to the network at the current dispute state.

Allowable Values:

256 char max

prearbitration_response_decision

string
Required

The prearbitration response decision.

Allowable Values:

ACCEPT_PARTIAL, DECLINE

amount

string
Required

The partial acceptance amount.

Allowable Values:

32 bytes

why_are_you_not_accepting_liability

string
Required

The reason you are not accepting liability.

Allowable Values:

certify_that_you_have_contacted_ cardholder_and_reviewed_the_ compelling_evidence_with_them_ and_cardholder_continues_dispute

boolean
Required

Indicates whether you have contacted the cardholder and reviewed the evidence and that the cardholder is continuing the dispute.

Allowable Values:

true, false

explanation_of_why_cardholder_ continues_dispute

string
Required

A description of why the cardholder is continuing the dispute.

Allowable Values:

certify_that_cardholder_name_and_ address_provided_by_acquirer_does_ not_match_issuer_records

boolean
Required

Indicates whether the cardholder’s name and address from the acquirer does not match issuer records.

Allowable Values:

true, false

explanation_of_why_you_are_ continuing_the_dispute

string
Required

An explanation of why you are continuing the dispute.

Allowable Values:

The arbitration_details object

The details for arbitration.

Fields Description

attached_contents

string
Optional

Content token for documents to be submitted to the network at the current dispute state.

Allowable Values:

256 char max

The representment_details object

The details for representment transition.

Fields Description

amount

number
Required

The amount in dispute.

Allowable Values:

Min: 0.1

attached_contents

string
Optional

Content token for documents to be submitted to the network at the current dispute state.

Allowable Values:

256 char max

The case_close_details object

The details for case close transition details.

Fields Description

write_off

boolean
Optional

Indicates whether the write-off due to the case lost happened.

Allowable Values:

true, false

write_off_actor

string
Optional

The actor who performed the write-off.

Allowable Values:

PROGRAM, ISSUER

Network dispute transition response body

Fields Description

token

string
Returned

The unique identifier of the dispute transition.

Allowable Values:

36 char max

created_time

datetime
Returned

The date and time that the transition was created.

Allowable Values:

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

last_modified_time

datetime
Returned

The date and time that the transition was last modified.

Allowable Values:

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

case_token

string
Returned

The token identifying the dispute case for the created the dispute transition.

Allowable Values:

36 char max

action

string
Returned

The action taken.

Allowable Values:

SUBMIT, ACCEPT_AND_CLOSE, RESPOND_WITH_PREARB, RESPOND_WITH_PREARB_RESPONSE, RESPOND_WITH_ARB, WAIT, ALLOCATION_ACKNOWLEDGED, REPRESENTMENT_RECEIVED, PREARB_RECEIVED, PREARB_ACCEPTED, PREARB_DECLINED, PREARB_RESPONSE_DECLINED, ADJUSTMENT, CLOSE_WITH_CASE_WON, CLOSE_WITH_NETWORK_REJECTED

created_by

string
Returned

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

Allowable Values:

256 char max

memo

string
Conditionally returned

A memo regarding the transaction.

Allowable Values:

16777215 char max

from_network_status

string
Returned

The network status before the transition.

Allowable Values:

255 char max

to_network_status

string
Returned

The new network status after the transition.

Allowable Values:

255 char max

network_dispute_id

string
Returned

The ID assigned to the dispute by the network.

Allowable Values:

36 char max

system_error_message

string
Conditionally returned

The error message for the system error.

Allowable Values:

16777215 char max

network_error_message

string
Conditionally returned

The error message for the network error.

Allowable Values:

16777215 char max

network_details

object
Returned

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

Allowable Values:

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

prearbitration_response_details

object
Optional

Object defining the prearbitration response details.

Allowable Values:

arbitration_details

object
Optional

Object defining the arbitration details.

Allowable Values:

representment_details

object
Optional

Object defining the network state details.

Allowable Values:

network_state_details

string
Optional

A JSON object, containing the details, received from the network.

Allowable Values:

dispute_state

string
Optional

Once the case’s state has been moved to CHARGEBACK_INITIATED this field will be updated as it progresses in the backend lifecycle.

Allowable Values:

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

case_close_details

string
Optional

The new dispute state.

Allowable Values:

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

transition_token

string
Required

The token of the transition to retrieve.

Allowable Values:

36 char max

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

Response fields

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:

36 char max

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

List network dispute transitions response fields

Sample response body