DOCS
Developer resources
Community

Collaborate on your project with other Marqeta developers

Sales

Speak with an expert to learn more about Marqeta

/
Guides
Core API

Launch and manage your company's payment card program

Core API Reference

Endpoint definitions and field-level reference

Core API Explorer

Try out all endpoints from your browser

DiVA API

Access the production data behind Marqeta's reporting and analytics tools

DiVA API Reference

Endpoint definitions and field-level reference

30 minute read
December 15, 2022

Disputes (Mastercard) (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 Mastercard network.

For specific details on how to integrate with the Mastercard network, see Managing Mastercard Disputes. For general information on disputes, chargebacks, and best practices, see About Disputes.

Create dispute case
Copy section link

Action: POST
Endpoint: /cases

Create a new dispute case by specifying the type and including the type-specific details object.

Body field details
Copy section link

Fields Description

token

string
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

The reason for the dispute.

Allowable Values:

See The dispute_details object table.

The dispute_details object
Copy section link

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

Fields Description

original_transaction_token

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

36 char max

dispute_amount

number
Required

The amount of funds under dispute.

Allowable Values:

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

dispute_amount_change_reason

string
Conditionally required

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

Allowable Values:

MERCHANT_ISSUED_PARTIAL_REFUND, PARTIAL_DISPUTE, NOT_AS_DESCRIBED_PARTIAL, PARTIAL_SERVICE, PRORATED_REFUND, NOT_AUTHORIZED_FOR_FULL_AMOUNT

Required if dispute_amount is not equal to transaction amount.

currency_code

string
Optional

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

Allowable Values:

30 char max

dispute_reason

string
Required

The code describing the reason for the dispute.

Allowable Values:

See Dispute case reasons.

cardholder_contact_date

datetime
Optional

The contact date of the cardholder.

Allowable Values:

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

Dispute case reasons
Copy section link

The following are the possible dispute reasons for a case and the equivalent Mastercard reasons and reason codes.

Dispute Reason Mastercard Reason and Code

ACCOUNT_NUMBER_NOT_ON_FILE

Account Number No on File 4812

AUTHORIZATION_RELATED_FOR_DUAL_MESSAGE_ SYSTEM

Authorization-related Chargeback 4808

CANCELLED_RECURRING_TRANSACTION

Cancelled Recurring and Digital Goods Transactions 4841

CARDHOLDER_DISPUTE

Cardholder Dispute 4853

CARDHOLDER_DISPUTE_US_ONLY

Cardholder Dispute. Not Elsewhere Classified (U.S. Region Only) 4854

CHIP_LIABILITY_SHIFT

Chip Liability Shift 4870

CHIP_PIN_LIABILITY_SHIFT_LOST_STOLEN

Chip Liability Shift - Lost/Stolen/Never Received Issue (NRI) Fraud 4871

CHIP_READ_POS_LATE_PRESENTMENT

Chip Read POS Late Presentment 4880

CREDIT_NOT_PROCESSED

Credit Not Processed 4860

DOMESTIC_CHARGEBACK_INTRA_EUROPEAN_USE

Domestic Chargeback Dispute Reserved for intra-European Use 4999

INCORRECT_CURRENCY, INCORRECT_TRANSACTION_CODE, INCORRECT_CURRENCY_OR_TRANSACTION_CODE

Correct Transaction Currency Code Not Provided 4846

INCORRECT_TRANSACTION_AMOUNT_OR_ACCOUNT_NUMBER

Transaction Amount Differs 4831

INSTALLMENT_BILLING_DISPUTE

Installment Billing Dispute 4850

LATE_PRESENTMENT

Late Presentment 4842

NO_AUTHORIZATION

Cardholder claims that they did not authorize or participate in the transaction 4808

NO_SHOW_ADDENDUM_OR_ATM_DISPUTE

No-show, Addendum, or ATM Dispute 4859

NON_RECEIPT_OF_CASH_OR_LOAD_TRANSACTION_VALUE_AT_ATM

The cardholder disputes a charge that they are not responsible for the transaction in question 4859

NOT_AUTHORIZED_CARD_PRESENT, NOT_AUTHORIZED_CARD_ABSENT

No Cardholder Authorization 4837

NOT_AS_DESCRIBED_OR_DEFECTIVE_MERCHANDISE

Goods or services damaged or defective, Counterfeit goods 4853

POINT_OF_INTERACTION_ERRORS

Point of Interaction Error 4834

QUESTIONABLE_MERCHANT_ACTIVITY

Questionable Merchant Activity 4849

SERVICE_NOT_PROVIDED_MERCHANDISE_NOT_ RECEIVED

Goods or Services Not Provided 4855

WARNING_BULLETIN_FILE

Warning Bulletin File 4807

Response body
Copy section link

Fields Description

token

string
Returned

The unique identifier of the dispute case.

Allowable Values:

36 char max

type

string
Returned

The type of case.

Allowable Values:

DISPUTE

memo

string
Returned

Free-form comments about the dispute.

Allowable Values:

512 char max

program_short_code

string
Returned

Indicates what program the case belongs to.

Allowable Values:

10 char max

user_token

string
Returned

Token that identifiers the user that made the original transaction.

Allowable Values:

36 char max

business_token

string
Returned

the token of the business involved in the dispute case.

Allowable Values:

36 char max

state

string
Returned

Indicates the current case state.

Allowable Values:

OPEN, OPEN_WITH_ACTION_REQUIRED, READY, CHARGEBACK_INITIATED, CLOSED

assignee

string
Returned

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

Allowable Values:

255 char max

zendesk_ticket_id

string
Optional

ID for the Zendesk ticket.

Allowable Values:

255 char max

type_change_time

datetime
Optional

When the type was changed.

Allowable Values:

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

dispute_details

object
Returned

The details of the dispute case.

Allowable Values:

See The dispute_details_response object table.

created_time

datetime
Returned

The time 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
Copy section link

JSON
Copied

Is this helpful?

Yes
No

Sample response body
Copy section link

JSON
Copied

Is this helpful?

Yes
No

Retrieve dispute case
Copy section link

Action: GET
Endpoint: /cases/{token}

Retrieve a specific dispute case.

URL path parameters
Copy section link

Fields Description

token

string
Required

The token of the dispute case to retrieve.

Allowable Values:

36 char max

Response body
Copy section link

Fields Description

token

string
Returned

The unique identifier of the dispute case.

Allowable Values:

36 char max

type

string
Returned

The type of case.

Allowable Values:

DISPUTE

memo

string
Returned

Free-form comments about the dispute.

Allowable Values:

512 char max

program_short_code

string
Returned

Indicates what program the case belongs to.

Allowable Values:

10 char max

user_token

string
Returned

Token that identifiers the user that made the original transaction.

Allowable Values:

36 char max

business_token

string
Returned

the token of the business involved in the dispute case.

Allowable Values:

36 char max

state

string
Returned

Indicates the current case state.

Allowable Values:

OPEN, OPEN_WITH_ACTION_REQUIRED, READY, CHARGEBACK_INITIATED, CLOSED

assignee

string
Returned

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

Allowable Values:

255 char max

zendesk_ticket_id

string
Optional

ID for the Zendesk ticket.

Allowable Values:

255 char max

type_change_time

datetime
Optional

When the type was changed.

Allowable Values:

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

dispute_details

object
Returned

The details of the dispute case.

Allowable Values:

See The dispute_details_response object table.

created_time

datetime
Returned

The time 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 response body
Copy section link

JSON
Copied

Is this helpful?

Yes
No

List dispute cases
Copy section link

Action: GET
Endpoint: /cases

List existing dispute cases. This endpoint supports sorting and pagination.

Query parameters
Copy section link

Fields Description

3ds

boolean
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

chargeback_token

string
Optional

Returns dispute cases associated with the specified chargeback.

Allowable Values:

36 char max

dispute_state

array of strings
Optional

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

Allowable Values:

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

network_case_number

string
Optional

Returns dispute cases associated with the specified network case number.

Allowable Values:

A valid network case number.

next_actor

string
Optional

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

Allowable Values:

An existing next actor.

original_transaction_token

string
Optional

Returns dispute cases associated with the specified token.

Allowable Values:

36 char max

reason

string
Optional

Returns disputes that are using the provided dispute reason.

Allowable Values:

See Dispute case reasons.

state

string
Optional

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

Allowable Values:

OPEN, OPEN_WITH_ACTION_REQUIRED, READY, CHARGEBACK_INITIATED, CLOSED

type

string
Optional

Returns cases of the specified type.

Allowable Values:

DISPUTE

user_token

string
Optional

Returns dispute cases associated with the specified user.

Allowable Values:

36 char max

Response body
Copy section link

Fields Description

token

string
Returned

The unique identifier of the dispute case.

Allowable Values:

36 char max

type

string
Returned

The type of case.

Allowable Values:

DISPUTE

memo

string
Returned

Free-form comments about the dispute.

Allowable Values:

512 char max

program_short_code

string
Returned

Indicates what program the case belongs to.

Allowable Values:

10 char max

user_token

string
Returned

Token that identifiers the user that made the original transaction.

Allowable Values:

36 char max

business_token

string
Returned

the token of the business involved in the dispute case.

Allowable Values:

36 char max

state

string
Returned

Indicates the current case state.

Allowable Values:

OPEN, OPEN_WITH_ACTION_REQUIRED, READY, CHARGEBACK_INITIATED, CLOSED

assignee

string
Returned

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

Allowable Values:

255 char max

zendesk_ticket_id

string
Optional

ID for the Zendesk ticket.

Allowable Values:

255 char max

type_change_time

datetime
Optional

When the type was changed.

Allowable Values:

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

dispute_details

object
Returned

The details of the dispute case.

Allowable Values:

See The dispute_details_response object table.

created_time

datetime
Returned

The time 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
Copy section link

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:

Existing transaction ID.

original_transaction_type

string
Returned

The type of the original transaction under dispute.

Allowable Values:

255 char max

dispute_amount

number
Returned

The amount of funds under dispute.

Allowable Values:

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

dispute_amount_change_reason

string
Returned

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

Allowable Values:

MERCHANT_ISSUED_PARTIAL_REFUND, PARTIAL_DISPUTE, NOT_AS_DESCRIBED_PARTIAL, PARTIAL_SERVICE, PRORATED_REFUND, NOT_AUTHORIZED_FOR_FULL_AMOUNT

currency_code

string
Returned

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

Allowable Values:

30 char max

dispute_reason

string
Returned

The code describing the reason for the dispute.

Allowable Values:

See the Dispute case reasons table.

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:

MASTERCARD

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

network_failure_response

string
Returned

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

Allowable Values:

255 char max

cardholder_contact_date

datetime
Returned

The contact date of the cardholder.

Allowable Values:

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

provisional_credit_granted

boolean
Returned

Indicates whether the provisilal credit was granted.

Allowable Values:

true, false

regulation_type

string
Returned

The regulation type of the disputer case.

Allowable Values:

255 char max

Sample response body
Copy section link

JSON
Copied

Is this helpful?

Yes
No

Create dispute case transition
Copy section link

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

Transition a dispute case to another state or initiate a chargeback against the dispute case.

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

URL path parameters
Copy section link

Fields Description

token

string
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
Copy section link

Fields Description

token

string
Optional

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

Allowable Values:

36 char max

action

string
Required

The action taken on the dispute case.

Allowable Values:

See Dispute case transitions.

reason_code

string
Required

Identifies the standardized reason for the transition.

Allowable Values:

See The reason_code field table.

created_by

string
Required

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

Allowable Values:

255 char max

assignee

string
Optional

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

Allowable Values:

255 char max

memo

string
Optional

Additional notes about the transition.

Allowable Values:

16777215 char max

transition_details

object
Required

An object containing the transition details.

Allowable Values:

See The transition_details object.

The transition_details object
Copy section link

Fields Description

chargeback_details

object
Required

An object containing the chargeback details.

Allowable Values:

See The chargeback_details object.

The chargeback_details object
Copy section link

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
Copy section link

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

Action Resulting State Description

CREATE

OPEN, OPEN_WITH_ACTION_REQUIRED

Creates a new dispute case. A default action when a POST request is sent to the /cases endpoint. The OPEN_WITH_ACTION_REQUIRED state results if additional information is needed from the user.

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

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

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
Copy section link

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
Copy section link

Fields Description

case_token

string
Returned

The unique identifier of the dispute case.

Allowable Values:

36 char max

token

string
Returned

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

Allowable Values:

36 char max

action

string
Returned

The action taken on the dispute case.

Allowable Values:

See Dispute case transitions.

reason_code

string
Returned

Identifies the standardized reason for the transition.

Allowable Values:

See The reason_code field table.

reason_description

string
Returned

A descriptive reason for the transition.

Allowable Values:

36 char max

created_by

string
Returned

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

Allowable Values:

36 char max

from_state

string
Returned

The state of the dispute case before the case transition was created.

Allowable Values:

OPEN, OPEN_WITH_ACTION_REQUIRED, READY, CHARGEBACK_INITIATED, CLOSED

state

string
Returned

The resulting state of the dispute case after the transition was created.

Allowable Values:

OPEN, OPEN_WITH_ACTION_REQUIRED, READY, CHARGEBACK_INITIATED, CLOSED

assignee

string
Returned

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

Allowable Values:

255 char max

memo

string
Returned

Additional notes about the transition.

Allowable Values:

512 char max

failure_reason

string
Returned

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

Allowable Values:

512 char max

transition_details

object
Returned

An object containing the transition details.

Allowable Values:

See The transition_details object.

Sample request body (CHARGEBACK_CREDIT)
Copy section link

JSON
Copied

Is this helpful?

Yes
No

Sample response body (CHARGEBACK_CREDIT)
Copy section link

JSON
Copied

Is this helpful?

Yes
No

Sample request body (CHARGEBACK_NO_CREDIT)
Copy section link

JSON
Copied

Is this helpful?

Yes
No

Sample response body (CHARGEBACK_NO_CREDIT)
Copy section link

JSON
Copied

Is this helpful?

Yes
No

Retrieve dispute case transition
Copy section link

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

Retrieve a specific dispute case transition for a specific dispute case.

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

URL path parameters
Copy section link

Fields Description

token

string
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
Copy section link

See Dispute transition response.

Sample response body
Copy section link

JSON
Copied

Is this helpful?

Yes
No

List dispute case transitions
Copy section link

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

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

URL path parameters
Copy section link

Fields Description

token

string
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
Copy section link

Fields Description

state

string
Optional

Filter dispute case transitions that contains the specified resulting state.

Allowable Values:

OPEN, OPEN_WITH_ACTION_REQUIRED, READY, CHARGEBACK_INITIATED, CLOSED

List dispute case transition response
Copy section link

See Dispute transition response.

Sample response body
Copy section link

JSON
Copied

Is this helpful?

Yes
No

Create network dispute transition
Copy section link

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

Create a network dispute transition.

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

URL path parameters
Copy section link

Fields Description

token

string
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
Copy section link

Fields Description

action

string
Required

The action to take:

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

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

  • RESPOND_WITH_PREARB_RESPONSE: Respond to the prearbitration response.

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

  • CLOSE_WITH_CASE_WON: Close with case won dispute transition.

  • CLOSE_WITH_NETWORK_REJECTED: Close with network rejected.

  • REPRESENTMENT_RECEIVED: Indicates that representment was received.

Allowable Values:

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

created_by

string
Optional

The user who is creating the transition.

Allowable Values:

255 char max

memo

string
Optional

A memo regarding the transaction.

Allowable Values:

16777215 char max

network_details

object
Conditionally required

The network details.

Allowable Values:

See The network_details object table.

The network_details object
Copy section link

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:

See The prearbitration_details object table.

prearbitration_response_details

object
Optional

Object defining the prearbitration response details.

Allowable Values:

See The prearbitration_response_details object table.

arbitration_details

object
Optional

Object defining the arbitration details.

Allowable Values:

See The arbitration_details object table.

representment_details

object
Optional

Object defining the network state details.

Allowable Values:

See The network_state_details object table.

case_close_details

string
Optional

The new dispute state.

Allowable Values:

See The case_close_details object table.

The prearbitration_details object
Copy section link

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

filed_against_ica

string
Required

Filing ICA of the acquirer/merchant.

Allowable Values:

256 char max

filing_ica

string
Required

Filing ICA of the issuer.

Allowable Values:

256 char max

network_memo

string
Optional

Memo from the network pertaining to the dispute case.

Allowable Values:

256 char max

merchant_name

string
Optional

The merchant name.

Allowable Values:

22 char max

The prearbitration_response_details object
Copy section link

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

The arbitration_details object
Copy section link

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
Copy section link

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
Copy section link

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
Copy section link

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:

255 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 thansition.

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:

See The network_details_response object table.

The network_details_response object
Copy section link

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

Fields Description

prearbitration_details

object
Optional

Object defining the prearbitration details.

Allowable Values:

See The prearbitration_details object table.

prearbitration_response_details

object
Optional

Object defining the prearbitration response details.

Allowable Values:

See The prearbitration_response_details object table.

arbitration_details

object
Optional

Object defining the arbitration details.

Allowable Values:

See The arbitration_details object table.

representment_details

object
Optional

Object defining the network state details.

Allowable Values:

See The network_state_details object table.

network_state_details

string
Optional

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

Allowable Values:

16777215 char max

dispute_state

string
Optional

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

Allowable Values:

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

case_close_details

string
Optional

The new dispute state.

Allowable Values:

See The case_close_details object table.

Sample request with prearbitration
Copy section link

JSON
Copied

Is this helpful?

Yes
No

Sample response with prearbitration
Copy section link

JSON
Copied

Is this helpful?

Yes
No

Sample request with arbitration
Copy section link

JSON
Copied

Is this helpful?

Yes
No

Sample response with arbitration
Copy section link

JSON
Copied

Is this helpful?

Yes
No

Sample accept and close dispute request
Copy section link

JSON
Copied

Is this helpful?

Yes
No

Sample accept and close dispute response
Copy section link

JSON
Copied

Is this helpful?

Yes
No

Sample close with case won dispute request
Copy section link

JSON
Copied

Is this helpful?

Yes
No

Sample close with case won dispute response
Copy section link

JSON
Copied

Is this helpful?

Yes
No

Retrieve network dispute transition
Copy section link

Action: GET
Endpoint: /cases/disputetransitions/{transition_token}

Retrieve a specific network dispute transition for a specific dispute case.

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

URL path parameters
Copy section link

Fields Description

transition_token

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

Response fields
Copy section link

See the Network dispute transition response table.

Sample response body
Copy section link

JSON
Copied

Is this helpful?

Yes
No

List network dispute transitions
Copy section link

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

List existing network dispute transitions for the specified dispute, including details of the merchant/acquirer responses during the backend resolution process. This endpoint supports sorting and pagination.

URL path parameters
Copy section link

Fields Description

token

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

List network dispute transitions response fields
Copy section link

See the Network dispute transition response table.

Sample response body
Copy section link

JSON
Copied

Is this helpful?

Yes
No

Create dispute case content
Copy section link

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

Upload and store documents related to a dispute, such as evidence for dispute or KYC verification documents.

The supported document formats are pdf, tiff, jpeg, and zip. A zip file must contain a pdf, tiff, or jpeg file. Each uploaded file is restricted to 2 MB.

URL path parameter
Copy section link

Fields Description

token

string
Required

The token that identifies the dispute case.

Allowable Values:

36 char max

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

Request body
Copy section link

Fields Description

document_category

string
Required

The category of the document.

Allowable Values:

AFFIDAVIT_FRAUD, AUTHORIZATION_RECORD, BANK_STATEMENT, CANCELLED_CHECK, CARDHOLDER_LETTER, CREDIT_VOUCHER, FULFILLMENT, ISSUER_CERTIFICATION, MERCHANT_LETTER, NETWORK_DOCUMENT, NETWORK_EXHIBIT, OTHERS, RECEIPT, SALES_DRAFT, SECOND_OPTION, UPDATED_CARDHOLDER_LETTER, UPDATED_MERCHANT_LETTER

document_name

string
Required

The name for the document. Must include the document extension as appropriate for a supported file format: pdf, tiff, or jpeg.

Allowable Values:

255 char max

document_data

binary
Required

Base64-encoded file.

Allowable Values:

2 MB max size

Create content response body
Copy section link

Fields Description

token

string
Returned

The token identifying the document.

Allowable Values:

36 char max

case_token

string
Returned

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

Allowable Values:

36 char max

document_name

string
Returned

The name of the document.

Allowable Values:

255 char max

document_category

string
Returned

The type of document.

Allowable Values:

AFFIDAVIT_FRAUD, AUTHORIZATION_RECORD, BANK_STATEMENT, CANCELLED_CHECK, CARDHOLDER_LETTER, CREDIT_VOUCHER, FULFILLMENT, ISSUER_CERTIFICATION, MERCHANT_LETTER, NETWORK_DOCUMENT, NETWORK_EXHIBIT, OTHERS, RECEIPT, SALES_DRAFT, SECOND_OPTION, UPDATED_CARDHOLDER_LETTER, UPDATED_MERCHANT_LETTER

document_content_type

string
Returned

The content type of the document.

Allowable Values:

application/pdf, image/tiff, image/jpeg

network_processing_type

string
Returned

Indicates the current status of the document at the network:

SUBMITTED - Indicates it has been submitted to the network using the Dispute Case Transition or Network Dispute Transition endpoint.

RECEIVED - Indicates that the document has been downloaded from the network, which occurs when the acquirer uploaded a document to support their claim.

Allowable Values:

SUBMITTED, RECEIVED

network_processing_phase

string
Returned

Indicates the status of the document in the dispute lifecycle.

Allowable Values:

INITIATED, REPRESENTMENT, PRE_ARBITRATION

network_processing_time

datetime
Returned

The date and time when the document has either been submitted by the user or received from the network.

Allowable Values:

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

created_time

datetime
Returned

The date and time when dispute was created.

Allowable Values:

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

updated_time

datetime
Returned

The date and time when dispute was last modified.

Allowable Values:

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

download_link

string
Returned

The link to download the file if it is included in the request. This only applies to the GET case content by token endpoint.

Allowable Values:

A valid URI.

Sample request body
Copy section link

JSON
Copied

Is this helpful?

Yes
No

Sample response body
Copy section link

JSON
Copied

Is this helpful?

Yes
No

List contents uploaded against a case
Copy section link

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

Get a list of uploaded contents for the specified dispute case.

URL path parameter
Copy section link

Fields Description

token

string
Required

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

Allowable Values:

36 char max

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

List contents response
Copy section link

For response details, see Create content response body.

Sample response body
Copy section link

JSON
Copied

Is this helpful?

Yes
No

Get content and status
Copy section link

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

Get a specific document and its status, and optionally start returning a temporary link to download the file.

If you include the download_link=true query parameter, a temporary link is returned in the response that you can use to download the document. The link is active for 15 minutes; after that time you must call this endpoint again to generate a new link.

URL path parameters
Copy section link

Fields Description

case_token

string
Required

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

Allowable Values:

36 char max

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

token

string
Required

The token that identifies the document.

Allowable Values:

36 char max

download_link

string
Optional

If set to true, this parameter causes a download link for the document to be included in the response.

Allowable Values:

true, false

Response body
Copy section link

For response details, see Create content response body.

Sample response body
Copy section link

JSON
Copied

Is this helpful?

Yes
No

Update document
Copy section link

Action: PUT
Endpoint: /cases/{token}/contents/{content_token}

Change the name of a document or category. If the document has already been processed with the network_processing_type set to SUBMITTED or RECEIVED, an error is returned.

URL path parameter
Copy section link

Fields Description

token

string
Required

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

Allowable Values:

36 char max

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

content_token

string
Required

The content token that identifies the document.

Allowable Values:

36 char max

Body field details
Copy section link

Fields Description

document_name

string
Required

The name for the document.

Allowable Values:

255 char max

document_category

string
Required

The category of the document.

Allowable Values:

AFFIDAVIT_FRAUD, AUTHORIZATION_RECORD, BANK_STATEMENT, CANCELLED_CHECK, CARDHOLDER_LETTER, CREDIT_VOUCHER, FULFILLMENT, ISSUER_CERTIFICATION, MERCHANT_LETTER, NETWORK_DOCUMENT, NETWORK_EXHIBIT, OTHERS, RECEIPT, SALES_DRAFT, SECOND_OPTION, UPDATED_CARDHOLDER_LETTER, UPDATED_MERCHANT_LETTER

Update document response body
Copy section link

For response details, see Create content response body.

Sample request body
Copy section link

JSON
Copied

Is this helpful?

Yes
No

Sample response body
Copy section link

JSON
Copied

Is this helpful?

Yes
No

Delete a document
Copy section link

Action: DELETE
Endpoint: /cases/{token}/contents/{content_token}

Delete a dispute case document. If the document has already been processed with the network_processing_type set to SUBMITTED or RECEIVED, an error is returned.

URL path parameter
Copy section link

Fields Description

token

string
Required

The token that identifies the dispute case.

Allowable Values:

36 char max

content_token

string
Required

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

Allowable Values:

36 char max

Delete content response
Copy section link

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

Sample response body
Copy section link

JSON
Copied

Is this helpful?

Yes
No

Related materials

Join our developer newsletter

© 2023 Marqeta, Inc.

• Terms • API Terms • Privacy • Cookies
Back to Marqeta.com