/

40 minute read

July 22, 2020

Cases (Visa) (Beta)

Use the /cases endpoint to manage transaction disputes on the Visa network.

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.

Each case object includes a type field that defines the purpose of the case. You can upload supporting documents and associate them with a specific case. The DISPUTE type initiates a review of a transaction that is under dispute. Qualifying disputes result in the creation of a dispute transaction.

Create case

Action: POST
Endpoint: /cases

Create a new 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 case.

If you do not include a token, the system will generate one automatically. This token is necessary for use in other API calls, so we recommend that rather than let the system generate one, 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

dispute_details

object
Optional

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

Allowable Values:

memo

string
Optional

Free-form comments about the case.

Allowable Values:

512 char max

The dispute_details object

For Visa cases, 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:

FRAUD, AUTH, PROCESSING, CONSUMER

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:

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

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

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

Allowable Values:

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

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

Allowable Values:

CURRENCY_DIFFERENCE, DCC_DISPUTE, CREDIT_INSTEAD_OF_REVERSAL_OR_ADJUSTMENT, CREDIT_POSTED_AS_DEBIT, DEBIT_POSTED_AS_CREDIT

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

Allowable Values:

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

certification_that_the_cardholder_did_ not_agree_to_dynamic_currency_ conversion_and_did_not_make_an_ active_choice

boolean
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 Cases.

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

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

Allowable Values:

true, false

what_is_the_account_number_on_the_ cardholders_receipt

string
Conditionally required

The account number on the cardholder’s receipt. 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 Cases.

Allowable Values:

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

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

Allowable Values:

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

what_is_the_amount_on_the_cardholders_receipt

bigDecimal
Conditionally required

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

Allowable Values:

32 bytes

does_the_account_number_on_the_ receipt_match_the_cardholders_ account_number_or_token

string
Conditionally required

Indicates whether the amount on the receipt matches the cardholder’s account number or token. To determine whether this field is required, see the decision tree for Consumer Disputes in Managing Visa Cases.

Allowable Values:

true, false

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 Consumer Disputes in Managing Visa Cases.

Allowable Values:

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

Allowable Values:

expected_receipt_date_and_time

date
Conditionally required

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

Allowable Values:

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

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

Allowable Values:

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 transaction was cancelled. To determine whether this field is required, see the decision tree for Consumer Disputes in Managing Visa Cases.

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

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

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

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

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

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

Allowable Values:

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

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

Allowable Values:

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

Allowable Values:

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

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

Allowable Values:

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'

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

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

Allowable Values:

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

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

Allowable Values:

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

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

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

Allowable Values:

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

Allowable Values:

true, false

attempt_to_resolve_prohibited_by_ local_law_or_regulations

boolean
Conditionally required

Indicates whether an attempt was made to resolve the dispute by local law or regulations. To determine whether this field is required, see the decision tree for Consumer Disputes in Managing Visa Cases.

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

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

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

Allowable Values:

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

Allowable Values:

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

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

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

Allowable Values:

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

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

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

Allowable Values:

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

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

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

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

Allowable Values:

did_the_cardholder_cancel_the_services

boolean
Conditionally required

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

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

Allowable Values:

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 services were cancelled. To determine whether this field is required, see the decision tree for Consumer Disputes in Managing Visa Cases.

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

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

Allowable Values:

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

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

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

Allowable Values:

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

merchandise_or_services

date
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 Cases.

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

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

Allowable Values:

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

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

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

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

Allowable Values:

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

Allowable Values:

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 by the cardholder to return the merchandise. To determine whether this field is required, see the decision tree for Consumer Disputes in Managing Visa Cases.

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

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

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

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

Allowable Values:

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

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

Allowable Values:

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 for the cancellation. To determine whether this field is required, see the decision tree for Consumer Disputes in Managing Visa Cases.

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

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

Allowable Values:

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'

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

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

The state field (response only)

The state of the case.

New cases begin in the OPEN state and can change to other states based on actions. Actions are defined in case transition events, which are managed by the Marqeta platform. Depending on the action, the state of a case changes to represent its updated status.

Note
Actions are only associated with the case transition event, not the case itself. For more information on actions that can be performed on a case, see "The actions field (response only)" on this page.
State Description

Delivered/100.00% Acq Liability

The dispute has been sent to acquirer and is awaiting a response.

Delivered

The dispute has been sent to acquirer and is awaiting a response.

Accepted by Acq

The dispute has been accepted by acquirer.

Declined by Acq

The dispute has been declined by acquirer.

Pre-Arb Timeframe Expired

The prearbitration timeframe has expired.

Pre-Arb Received

The prearbitration proposal has been received.

Pre-Arb Declined

The prearbitration proposal is declined.

Accepted Full by Acq

Preabitration has been accepted in full by the acquirer.

Pre-Arb Delivered

Preabitration has been delivered.

Pre-Arb Accepted Full

Preabitration has been accepted in full.

Pre-Arb Declined

Preabitration has been declined.

Response Timeframe Expired - 100% Acq Liability

The response timeframe has expired, resulting in 100% liability for the acquirer.

Sample request body

{
  "token": "my_case_token",
  "type": "DISPUTE",
  "dispute_details":{
    "original_transaction_token": "111",
    "dispute_amount": 100.00,
    "dispute_reason": "FRAUD",
  },
  "memo": "Multiple browser submission"
}

Is this helpful?

Sample response body

{
  "token": "my_case_token",
  "type": "DISPUTE",
  "dispute_details":{
    "original_transaction_token": "111",
    "dispute_amount": 100.00,
    "currency_code": "USD",
    "dispute_reason": "FRAUD",
  },
  "memo": "Multiple browser submission",
  "state": "OPEN",
  "folder_id": "123456",
  "user_token": "my_user_123",
  "created_time": "2018-03-19T13:22:07Z",
  "last_modified_time": "2018-03-19T13:22:07Z"
}

Is this helpful?

Retrieve case

Action: GET
Endpoint: /cases/{token}

Retrieve a specific case.

URL path parameters

Fields Description

token

string
Required

The token of the case to retrieve.

Allowable Values:

An existing case token.

Query parameters

Fields Description

create_access_token

boolean
Optional

Set to true to include a new folder access token in the response; you can use the access token to manage documents associated with the case. The token expires after one hour.

Allowable Values:

true, false

Default value: false

create_shared_link

boolean
Optional

Set to true to include a new shared link in the response; you can use the shared link to view documents associated with the case. The link expires after one hour.

Allowable Values:

true, false

Default value: false

Sample response body

{
  "token": "my_case_token",
  "type": "DISPUTE",
  "dispute_details": {
    "original_transaction_token": "111",
    "dispute_amount": 100.00,
    "currency_code": "USD",
    "dispute_reason": "FRAUD",
    "chargeback_token": "my_chargeback_id"
  },
  "memo": "Multiple browser submission",
  "state": "READY",
  "assignee": "janes",
  "folder_id": "123456",
  "folder_access_token": "abcdeffedcba12345678900987654321",
  "folder_shared_link": "h9ygyjqgd11wpfnf3cp6exk5ywjo065l",
  "user_token": "my_user_123",
  "created_time": "2018-03-19T13:22:07Z",
  "last_modified_time": "2018-03-20T09:22:07Z"
}

Is this helpful?

Retrieve network case status

Action: GET
Endpoint: /network/casestatus/{case_token}

After action is taken with the Visa network, such as case initiation or prearbitration, the acquirer and the network have a certain amount of time to respond (usually 30 days for the acquirer and 10 days for the network). Also, periodically the acquirer or network takes action on the case and its status is updated. This requires that the status of active cases be regularly retrieved from the network so that action can be taken on the case.

This endpoint supports sorting and pagination.

Query parameters

Fields Description

refresh

boolean
Optional

Indicates whether to refresh the result. If the query parameter refresh is true, get the status from the network; if false, get the status stored in the database.

Allowable Values:

true, false

Default: true

network_case_status_details (response)

Fields Description

network

string
Conditionally returned

The card network.

Allowable Values:

VISA

network_case_number

string
Conditionally returned

The network case number for this dispute.

Allowable Values:

A valid case number.

case_status

string
Conditionally returned

The current status of the case.

Allowable Values:

See the Visa transitions table.

days_to_act

long
Conditionally returned

The number of days left to act.

Allowable Values:

true, false

last_action_date

date
Conditionally returned

The last date that an action was taken.

Allowable Values:

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

date
Conditionally returned

The date the case was opened.

Allowable Values:

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'

last_refresh_date

date
Conditionally returned

The date the case information was last refreshed.

Allowable Values:

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'

created_time

date
Conditionally returned

The date the case was created.

Allowable Values:

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'

last_modified_time

date
Conditionally returned

The date the case was last modified.

Allowable Values:

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'

Sample response body

{
    "network": "Visa",
    "network_case_number" : "Network_case_number",
    "case_status": "Delivered",
    "days_to_act": "30",
    "last_action_date": "2020-03-05T16:00:03Z",
    "case_opened_date": "2020-02-12T16:00:03ZZ",
    "last_refresh_date": "2020-03-05T16:00:03Z",
    "created_time": "2020-02-12T16:00:03Z",
    "last_modified_time": "2020-03-05T16:00:03Z"
}

Is this helpful?

List cases

Action: GET
Endpoint: /cases

List existing cases. This endpoint supports sorting and pagination.

Query parameters

Fields Description

type

string
Optional

Returns cases of the specified type.

Allowable Values:

DISPUTE

original_transaction_token

string
Optional

Returns cases associated with the specified token.

Allowable Values:

Existing transaction token.

state

string
Optional

Returns cases that are in the specified state.

Allowable Values:

Delivered/100.00% Acq Liability, Delivered, Accepted by Acq, Declined by Acq, Pre-Arb Timeframe Expired, Pre-Arb Received, Pre-Arb Declined, Accepted Full by Acq, Pre-Arb Delivered, Pre-Arb Accepted Full, Pre-Arb Declined, Response Timeframe Expired - 100% Acq Liability

assignee

string
Optional

Returns cases associated with the specified assignee.

Allowable Values:

user_token

string
Optional

Returns cases associated with the specified user.

Allowable Values:

Existing user token.

chargeback_token

string
Optional

Returns cases associated with the specified chargeback.

Allowable Values:

Existing chargeback token.

network_case_status_details (response)

Fields Description

id

BIGINT
Required

The case identifier.

Allowable Values:

network

VARCHAR(36)
Required

The unique key (with networkCaseNumber)

Allowable Values:

networkCaseNumber

VARCHAR(36)
Required

The case number within the Visa network.

Allowable Values:

caseStatus

VARCHAR(255)
Required

The current case status.

Allowable Values:

daysToAct

BIGINT
Required

The number of days remaining to act.

Allowable Values:

lastActionDate

date
Optional

The last date that an action on the case was taken.

Allowable Values:

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'

caseOpenedDate

date
Optional

The date the case was opened.

Allowable Values:

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'

lastRefreshDate

date
Required

The date the case was last refreshed.

Allowable Values:

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'

createdTime

date
Optional

The date the case was created.

Allowable Values:

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'

lastModifiedTime

date
Optional

The last time the case was modified.

Allowable Values:

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'

Sample response body

{
  "network_case_status_details": {
    "created_time": "2020-02-21T22:19:00Z",
    "last_modified_time": "2020-03-05T16:00:05Z",
    "case_status": "Authorization Dispute - Delivered / 100.00% Acq Liability",
    "next_actor": "ACQUIRER",
    "days_to_act": 18,
    "last_action_date": "2020-02-21T22:52:15Z",
    "case_opened_date": "2020-02-21T00:00:00Z",
    "last_refresh_date": "2020-03-05T16:00:03Z",
    "allowable_actions": [
      "WAIT"
    ]
  }
}

Is this helpful?

Create case transition

Action: POST
Endpoint: /cases/{token}/disputetransitions

Create a case transition.

A case transition is an event that changes the state of a case and triggers other related events. The new state of the case and which related events are triggered is determined by the action defined in the case transition.

URL path parameters

Fields Description

token

string
Required

The token of the case associated with the transition you want to create.

Allowable Values:

An existing case token.

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

action

string
Required

The action to create.

Allowable Values:

ACCEPT_AND_CLOSE, RESPOND_WITH_PREARB, RESPOND_WITH_PREARB_RESPONSE, WAIT

created_by

string
Optional

The user who is creating the transition.

Allowable Values:

memo

string
Optional

A memo regarding the transaction.

Allowable Values:

prearbitration_details

object
Required

The details for prearbitration.

Allowable Values:

prearbitration_response_details

object
Required

The details of the prearbitration response.

Allowable Values:

The prearbitration_details object

Fields Description

prearbitration_amount

bigDecimal
Required

The prearbitration amount.

Allowable Values:

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

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

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:

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

RESPOND_WITH_PREARB

Respond to the proposed solution with prearbitration.

RESPOND_WITH_PREARB_RESPONSE

Respond to the prearbitation response.

RESPOND_WITH_ARB

Respond with arbitration.

WAIT

Do nothing.

Visa transitions

The following table shows Visa transitions:

Status Description Allowable Dispute Transition Actions

Delivered/100.00% Acq Liability

The dispute has been sent to acquirer and is awaiting a response.

WAIT

Delivered

The dispute has been sent to acquirer and is awaiting a response.

WAIT

Accepted by Acq

The dispute has been accepted by acquirer.

ACCEPT_AND_CLOSE

Declined by Acq

The dispute has been declined by acquirer.

RESPOND_WITH_PREARB, ACCEPT_AND_CLOSE

Pre-Arb Timeframe Expired

The prearbitration timeframe has expired.

ACCEPT_AND_CLOSE

Pre-Arb Received

The prearbitration proposal has been received.

RESPOND_WITH_PREARB_RESPONSE, ACCEPT_AND_CLOSE

Pre-Arb Declined

The prearbitration proposal is declined.

WAIT

Accepted Full by Acq

Preabitration has been accepted in full by the acquirer.

ACCEPT_AND_CLOSE

Pre-Arb Delivered

Preabitration has been delivered.

WAIT

Pre-Arb Accepted Full

Preabitration has been accepted in full.

ACCEPT_AND_CLOSE

Pre-Arb Declined

Preabitration has been declined.

RESPOND_WITH_ARB

Response Timeframe Expired - 100% Acq Liability

The response timeframe has expired, resulting in 100% liability for the acquirer.

ACCEPT_AND_CLOSE

Sample request body

{
    "token": "my_casetransition_id",
    "case_token": "my_case_id",
    "action": "RESPOND_WITH_PREARB",
    "created_by": "user_name1",
    "memo": "Sample memo text",
    "prearbitration_details": {
        "prearbitration_amount": "150.65",
        "why_are_you_initiating_prearbitration" : "Text describing reason",
        "are_you_providing_new_information" : "Yes",
        "summary_of_new_information" : "Text summarizing new information"
    },
    "prearbitration_response_details": {
        "prearbitration_response_decision" : "ACCEPT_PARTIAL",
        "partial_acceptance_amount" : "75.00",
        "why_are_you_not_accepting_liability" :  "Text describing reason",
        "certify_that_you_have_contacted_cardholder_and_reviewed_the_compelling_evidence_with_them_and_cardholder_continues_dispute" : "Yes",
        "explanation_of_why_cardholder_continues_dispute" : "Text describing reason",
        "certify_that_cardholder_name_and_address_provided_by_acquirer_does_not_match_issuer_records" : "Yes",
        "explanation_of_why_you_are_continuing_the_dispute" : "Text describing reason"
    }
}

Is this helpful?

Sample response body

{
    "id": "id",
    "token": "token",
    "case_token": "my_case_id",
    "action": "RESPOND_WITH_PREARB",
    "created_by": "user_name1",
    "memo": "Sample memo text",
    "from_network_status": "Network status",
    "to_network_status": "Network status",
    "prearbitration_details": {
        "prearbitration_amount": "150.65",
        "why_are_you_initiating_prearbitration" : "Text describing reason",
        "are_you_providing_new_information" : "Yes",
        "summary_of_new_information" : "Text summarizing new information"
    },
    "prearbitration_response_details": {
        "prearbitration_response_decision" : "ACCEPT_PARTIAL",
        "partial_acceptance_amount" : "75.00",
        "why_are_you_not_accepting_liability" :  "Text describing reason",
        "certify_that_you_have_contacted_cardholder_and_reviewed_the_compelling_evidence_with_them_and_cardholder_continues_dispute" : "Yes",
        "explanation_of_why_cardholder_continues_dispute" :  "Text describing reason",
        "certify_that_cardholder_name_and_address_provided_by_acquirer_does_not_match_issuer_records" : "Yes",
        "explanation_of_why_you_are_continuing_the_dispute" : "Text describing reason"
    },
    "created_time": "2020-02-21T04:04:10Z",
    "last_modified_time": "2020-03-10T09:53:01Z"
}

Is this helpful?

Retrieve case transition

Action: GET
Endpoint: /cases/{token}/transitions/{transition_token}

Retrieve a specific case transition for a specific case.

A case transition is an event that changes the state of a case and triggers other related events. The new state of the case and which related events are triggered is determined by the action defined in the case transition.

URL path parameters

Fields Description

token

string
Required

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

Allowable Values:

An existing case token.

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

transition_token

string
Required

The token of the transition to retrieve.

Allowable Values:

An existing case transition token.

Send a GET request to /cases/{token}/transitions to retrieve case 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 case.

RESPOND_WITH_PREARB

Respond to the proposed solution with prearbitration.

RESPOND_WITH_PREARB_RESPONSE

Respond to the prearbitation response.

RESPOND_WITH_ARB

Respond with arbitration.

WAIT

Do nothing.

The reason_code field (response only)

Reason Code Description Related Actions

00

The case was created.

CREATE

05

The case is under review.

REVIEW

14

The Marqeta platform updated the case.

CLOSE

22

The case was assigned to a user.

ASSIGN

23

The case was reopened.

RE_OPEN

24

The case was reopened to gather more information.

RE_OPEN

26

The customer closed the 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 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

Sample response body

{
  "token": "my_casetransition_id1",
  "case_token": "my_case_token",
  "action": "CHARGEBACK_CREDIT",
  "reason_code": "27",
  "created_by": "janes",
  "memo": "Initiating chargeback",
  "assignee": "janes",
  "reason_description": "Smaller Amount",
  "state": "CHARGEBACK_INITIATED",
  "created_time": "2018-03-19T13:22:07Z",
  "last_modified_time": "2018-03-20T09:22:07Z"
}

Is this helpful?

List case transitions

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

List existing case transitions for the specified case. This endpoint supports sorting and pagination.

URL path parameters

Fields Description

token

string
Required

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

Allowable Values:

An existing case token.

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

Sample response body

{
  "count": 2,
  "start_index": 0,
  "end_index": 1,
  "is_more": false,
  "data": [
    {
      "token": "my_casetransition_id",
      "case_token": "my_case_token",
      "action": "ASSIGN",
      "reason_code": "05",
      "created_by": "janes",
      "memo": "Assigned to user",
      "assignee": "janes",
      "reason_description": "Under Review",
      "state": "READY",
      "created_time": "2018-03-19T13:22:07Z",
      "last_modified_time": "2018-03-20T09:22:07Z"
    },
    {
      "token": "my_casetransition_id1",
      "case_token": "my_case_token",
      "action": "CHARGEBACK_CREDIT",
      "reason_code": "27",
      "created_by": "janes",
      "memo": "Initiating chargeback",
      "assignee": "janes",
      "reason_description": "Smaller Amount",
      "state": "CHARGEBACK_INITIATED",
      "created_time": "2018-03-19T13:22:07Z",
      "last_modified_time": "2018-03-20T09:22:07Z"
    }
  ]
}

Is this helpful?

Create case content

Action: POST
Endpoint: /cases/{token}/contents

Upload and store documents related to a case, such as evidence for dispute or KYC verification documents. This endpoint uses the multipart post method to complete all upload tasks. Format the request body according to the "multipart/related" content type, which contains two parts:

  • Metadata: Must come first, and must have a Content-Type header set to application/json. Add the file’s metadata to this part in JSON format.

  • Media: Must come second, and must have a Content-Type header, which may have any MIME type. Add the file’s data to this part.

Identify each part with a boundary string, preceded by two hyphens. Add two hyphens after the final boundary string.

Each uploaded file is restricted to 2 MB.

Query parameters

Fields Description

token

string
Optional

The token identifying the document. If a token is not passed into the request, a token is generated.

Allowable Values:

An existing case token.

case_token

string
Required

The token identifying the case you want to upload documents against

Allowable Values:

An existing case token.

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

document_category

string
Required

The type of document.

Allowable Values:

RECEIPT, CUSTOMER_SIGNATURE, CUSTOMER_DL, CUSTOMER_SSN, CUSTOMER_PASSPORT, UTILITY_BILL, CUSTOMER_COMMUNICATION, DISPUTE_FORM, BANK_STATEMENT, TAX_DOCUMENTS, INCORPORATION_CERTIFICATE, LEASE_AGREEMENT, OTHERS

document_name

string
Required

The name of the document.

Allowable Values:

created_time

string
Required

(Response only) The date and time when dispute is created.

Allowable Values:

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

last_modified_time

string
Required

(Response only) The date and time when dispute is last modified.

Allowable Values:

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

Accepted document types

The following document types are accepted.

Format Name Extension

Portable Document

.pdf

Microsoft Word

.doc/.docx

Plain Text

.txt

Joint Photographic Expert Group

.jpg/.jpeg

Graphics Interchange Format

.gif

Portable Network Graphic

.png

Tagged Image

.tiff/.tif

Sample request body

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

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

{
    "token": "my_upload_id",
    "document_category": "RECEIPT",
    "document_name": "receipt.jpg"
}

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

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

--marqeta_file_separator--

Is this helpful?

Sample response body

{
    "token": "my_content_id",
    "case_token": "111",
    "document_category": "RECEIPT",
    "document_name": "receipt.jpg",
    "created_time": "2018-03-19T13:22:07Z",
    "last_modified_time": "2018-03-19T13:22:07Z"
}

Is this helpful?

List contents uploaded against a case

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

Get a list of uploaded contents for the specified case.

URL path parameter

Fields Description

token

string
Required

The token that identifies the case for which to return the contents list.

Allowable Values:

An existing case token.

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

Sample response body

{
    "count": 2,
    "start_index": 0,
    "end_index": 1,
    "is_more": false,
    "data": [
    {
        "token": "my_content_id",
        "case_token": "111",
        "document_category": "RECEIPT",
        "document_name": "receipt.jpg",
        "created_time": "2018-03-19T13:22:07Z",
        "last_modified_time": "2018-03-19T13:22:07Z"
    },
    {
        "token": "my_content_id1",
        "case_token": "111",
        "document_category": "CUSTOMER_SIGNATURE",
        "document_name": "signature.jpg",
        "created_time": "2018-03-19T13:22:07Z",
        "last_modified_time": "2018-03-19T13:22:07Z"
    }
    ]
}

Is this helpful?

Delete a document

Action: PUT
Endpoint: /cases/contents/{document_token}/delete

Delete a case document.

URL path parameter

Fields Description

document_token

string
Required

The token that identifies the document to delete. This token is generated for the document when it is created.

Allowable Values:

An existing document token.

Sample response body

{"status" : "success"}

Is this helpful?

Have any feedback on this page?

If you feel we can do anything better, please let our team know.

We strive for the best possible developer experience.