/
40 minute read
August 25, 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

Action: POST
Endpoint: /cases

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

Body field details
Fields Description

token

string
Optional

The unique identifier of the dispute case.

If you do not include a token, the system generates a token automatically. Because this token is necessary for use in other API calls, it is recommended that, rather than let the system generate the token, you use a simple string that is easy to remember. This value cannot be updated.

Allowable Values:

36 char max

type

string
Required

The type of case.

Allowable Values:

DISPUTE

memo

string
Optional

Free-form comments about the dispute.

Allowable Values:

512 char max

zendesk_ticket_id

string
Optional

ID for the Zendesk ticket.

Allowable Values:

255 char max

dispute_details

object
Required

The reason for the dispute.

Allowable Values:

The dispute_details object

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

Fields Description

original_transaction_token

string
Required

The token of the original transaction under dispute.

Allowable Values:

36 char max

original_transaction_id

integer
Optional

The ID of the original transaction under dispute.

Allowable Values:

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:

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

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

token

string
Returned

The unique identifier of the dispute case.

Allowable Values:

36 char max

type

string
Returned

The type of case.

Allowable Values:

DISPUTE

memo

string
Returned

Free-form comments about the dispute.

Allowable Values:

512 char max

program_short_code

string
Returned

Indicates what program the case belongs to.

Allowable Values:

10 char max

user_token

string
Returned

Token that identifiers the user that made the original transaction.

Allowable Values:

36 char max

business_token

string
Returned

the token of the business involved in the dispute case.

Allowable Values:

36 char max

state

string
Returned

Indicates the current case state.

Allowable Values:

OPEN, OPEN_WITH_ACTION_REQUIRED, READY, CHARGEBACK_INITIATED, CLOSED

assignee

string
Returned

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

Allowable Values:

255 char max

zendesk_ticket_id

string
Optional

ID for the Zendesk ticket.

Allowable Values:

255 char max

type_change_time

datetime
Optional

When the type was changed.

Allowable Values:

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

dispute_details

object
Returned

The details of the dispute case.

Allowable Values:

created_time

datetime
Returned

The time that the dispute case was created.

Allowable Values:

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

updated_time

datetime
Returned

The time that the dispute case was last updated.

Allowable Values:

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

Sample request body
JSON
Copied

Is this helpful?

Yes
No
Sample response body
JSON
Copied

Is this helpful?

Yes
No

Retrieve dispute case

Action: GET
Endpoint: /cases/{token}

Retrieve a specific dispute case.

URL path parameters
Fields Description

token

string
Required

The token of the dispute case to retrieve.

Allowable Values:

36 char max

Response body
Fields Description

token

string
Returned

The unique identifier of the dispute case.

Allowable Values:

36 char max

type

string
Returned

The type of case.

Allowable Values:

DISPUTE

memo

string
Returned

Free-form comments about the dispute.

Allowable Values:

512 char max

program_short_code

string
Returned

Indicates what program the case belongs to.

Allowable Values:

10 char max

user_token

string
Returned

Token that identifiers the user that made the original transaction.

Allowable Values:

36 char max

business_token

string
Returned

the token of the business involved in the dispute case.

Allowable Values:

36 char max

state

string
Returned

Indicates the current case state.

Allowable Values:

OPEN, OPEN_WITH_ACTION_REQUIRED, READY, CHARGEBACK_INITIATED, CLOSED

assignee

string
Returned

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

Allowable Values:

255 char max

zendesk_ticket_id

string
Optional

ID for the Zendesk ticket.

Allowable Values:

255 char max

type_change_time

datetime
Optional

When the type was changed.

Allowable Values:

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

dispute_details

object
Returned

The details of the dispute case.

Allowable Values:

created_time

datetime
Returned

The time that the dispute case was created.

Allowable Values:

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

updated_time

datetime
Returned

The time that the dispute case was last updated.

Allowable Values:

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

Sample response body
JSON
Copied

Is this helpful?

Yes
No

List dispute cases

Action: GET
Endpoint: /cases

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

Query parameters
Fields Description

3ds

boolean
Optional

Returns dispute cases that involve 3DS.

Allowable Values:

true, false

assignee

string
Optional

Returns dispute cases associated with the specified assignee.

Allowable Values:

255 char max

chargeback_token

string
Optional

Returns dispute cases associated with the specified chargeback.

Allowable Values:

36 char max

dispute_state

array of strings
Optional

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

Allowable Values:

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

network_case_number

string
Optional

Returns dispute cases associated with the specified network case number.

Allowable Values:

A valid network case number.

next_actor

string
Optional

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

Allowable Values:

An existing next actor.

original_transaction_token

string
Optional

Returns dispute cases associated with the specified token.

Allowable Values:

36 char max

reason

string
Optional

Returns disputes that are using the provided dispute reason.

Allowable Values:

state

string
Optional

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

Allowable Values:

OPEN, OPEN_WITH_ACTION_REQUIRED, READY, CHARGEBACK_INITIATED, CLOSED

type

string
Optional

Returns cases of the specified type.

Allowable Values:

DISPUTE

user_token

string
Optional

Returns dispute cases associated with the specified user.

Allowable Values:

36 char max

Response body
Fields Description

token

string
Returned

The unique identifier of the dispute case.

Allowable Values:

36 char max

type

string
Returned

The type of case.

Allowable Values:

DISPUTE

memo

string
Returned

Free-form comments about the dispute.

Allowable Values:

512 char max

program_short_code

string
Returned

Indicates what program the case belongs to.

Allowable Values:

10 char max

user_token

string
Returned

Token that identifiers the user that made the original transaction.

Allowable Values:

36 char max

business_token

string
Returned

the token of the business involved in the dispute case.

Allowable Values:

36 char max

state

string
Returned

Indicates the current case state.

Allowable Values:

OPEN, OPEN_WITH_ACTION_REQUIRED, READY, CHARGEBACK_INITIATED, CLOSED

assignee

string
Returned

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

Allowable Values:

255 char max

zendesk_ticket_id

string
Optional

ID for the Zendesk ticket.

Allowable Values:

255 char max

type_change_time

datetime
Optional

When the type was changed.

Allowable Values:

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

dispute_details

object
Returned

The details of the dispute case.

Allowable Values:

created_time

datetime
Returned

The time that the dispute case was created.

Allowable Values:

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

updated_time

datetime
Returned

The time that the dispute case was last updated.

Allowable Values:

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

The dispute_details_response object
Fields Description

original_transaction_token

string
Returned

The token of the original transaction under dispute.

Allowable Values:

36 char max

original_transaction_id

integer
Returned

The ID of the original transaction under dispute.

Allowable Values:

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

Is this helpful?

Yes
No

Update dispute case

Action: PUT
Endpoint: /cases/{token}

URL path parameter
Fields Description

token

string
Required

The token that identifies the dispute case to update.

Allowable Values:

36 char max

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

Body field details
Fields Description

memo

string
Optional

Additional notes about the case.

Allowable Values:

255 char max

type

string
Optional

The type of case.

Allowable Values:

DISPUTE

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:

Response body
Fields Description

token

string
Returned

The unique identifier of the dispute case.

Allowable Values:

36 char max

type

string
Returned

The type of case.

Allowable Values:

DISPUTE

memo

string
Returned

Free-form comments about the dispute.

Allowable Values:

512 char max

program_short_code

string
Returned

Indicates what program the case belongs to.

Allowable Values:

10 char max

user_token

string
Returned

Token that identifiers the user that made the original transaction.

Allowable Values:

36 char max

business_token

string
Returned

the token of the business involved in the dispute case.

Allowable Values:

36 char max

state

string
Returned

Indicates the current case state.

Allowable Values:

OPEN, OPEN_WITH_ACTION_REQUIRED, READY, CHARGEBACK_INITIATED, CLOSED

assignee

string
Returned

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

Allowable Values:

255 char max

zendesk_ticket_id

string
Optional

ID for the Zendesk ticket.

Allowable Values:

255 char max

type_change_time

datetime
Optional

When the type was changed.

Allowable Values:

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

dispute_details

object
Returned

The details of the dispute case.

Allowable Values:

created_time

datetime
Returned

The time that the dispute case was created.

Allowable Values:

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

updated_time

datetime
Returned

The time that the dispute case was last updated.

Allowable Values:

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

Sample request body
JSON
Copied

Is this helpful?

Yes
No
Sample response body
JSON
Copied

Is this helpful?

Yes
No

Create dispute case transition

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

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

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

URL path parameters
Fields Description

token

string
Required

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

Allowable Values:

36 char max

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

Body field details
Fields Description

token

string
Optional

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

Allowable Values:

36 char max

action

string
Required

The action taken on the dispute case.

Allowable Values:

reason_code

string
Required

Identifies the standardized reason for the transition.

Allowable Values:

created_by

string
Required

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

Allowable Values:

255 char max

assignee

string
Optional

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

Allowable Values:

255 char max

memo

string
Optional

Additional notes about the transition.

Allowable Values:

16777215 char max

transition_details

object
Required

An object containing the transition details.

Allowable Values:

The transition_details object
Fields Description

chargeback_details

object
Required

An object containing the chargeback details.

Allowable Values:

The chargeback_details object
Fields Description

attached_contents

string
Required

List of content tokens that should be submitted to the network when initiating a chargeback. The content tokens should be associated to the case. For more information about the uploading case documents, see Create dispute case content.

Allowable Values:

A list of valid uuid tokens.

Dispute case transitions

Dispute case transitions represent the workflow during the creation, information gathering, and submission 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
Reason Code Description Related Actions

00

The dispute case was created.

CREATE

05

The dispute case is under review.

REVIEW

14

The Marqeta platform updated the dispute case.

CLOSE

22

The dispute case was assigned to a user.

ASSIGN

23

The dispute case was reopened.

RE_OPEN

24

The dispute case was reopened to gather more information.

RE_OPEN

26

The customer closed the dispute case.

CLOSE

28

A chargeback was created and the card holder was credited.

CHARGEBACK_CREDIT

29

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

CHARGEBACK_NO_CREDIT

30

The dispute case was closed automatically due to inactivity.

CLOSE

31

Invalid documents were uploaded.

DOCUMENTS_DELETED

32

Unreadable documents were uploaded.

DOCUMENTS_DELETED

33

Corrupted documents were uploaded.

DOCUMENTS_DELETED

34

The chargeback failed.

CHARGEBACK_CREDIT, CHARGEBACK_NO_CREDIT

35

The chargeback failed at the card network.

CHARGEBACK_CREDIT, CHARGEBACK_NO_CREDIT

Dispute transition response
Fields Description

case_token

string
Returned

The unique identifier of the dispute case.

Allowable Values:

36 char max

token

string
Returned

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

Allowable Values:

36 char max

action

string
Returned

The action taken on the dispute case.

Allowable Values:

reason_code

string
Returned

Identifies the standardized reason for the transition.

Allowable Values:

reason_description

string
Returned

A descriptive reason for the transition.

Allowable Values:

36 char max

created_by

string
Returned

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

Allowable Values:

36 char max

from_state

string
Returned

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

Allowable Values:

OPEN, OPEN_WITH_ACTION_REQUIRED, READY, CHARGEBACK_INITIATED, CLOSED

state

string
Returned

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

Allowable Values:

OPEN, OPEN_WITH_ACTION_REQUIRED, READY, CHARGEBACK_INITIATED, CLOSED

assignee

string
Returned

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

Allowable Values:

255 char max

memo

string
Returned

Additional notes about the transition.

Allowable Values:

512 char max

failure_reason

string
Returned

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

Allowable Values:

512 char max

transition_details

object
Returned

An object containing the transition details.

Allowable Values:

Sample request body (CHARGEBACK_CREDIT)
JSON
Copied

Is this helpful?

Yes
No
Sample response body (CHARGEBACK_CREDIT)
JSON
Copied

Is this helpful?

Yes
No
Sample request body (CHARGEBACK_NO_CREDIT)
JSON
Copied

Is this helpful?

Yes
No
Sample response body (CHARGEBACK_NO_CREDIT)
JSON
Copied

Is this helpful?

Yes
No

Retrieve dispute case transition

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

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

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

URL path parameters
Fields Description

token

string
Required

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

Allowable Values:

36 char max

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

transition_token

string
Required

The token of the transition to retrieve.

Allowable Values:

36 char max

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

Retrieve dispute case transition response
Sample response body
JSON
Copied

Is this helpful?

Yes
No

List dispute case transitions

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

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

URL path parameters
Fields Description

token

string
Required

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

Allowable Values:

36 char max

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

Query parameters
Fields Description

state

string
Optional

Filter dispute case transitions that contains the specified resulting state.

Allowable Values:

OPEN, OPEN_WITH_ACTION_REQUIRED, READY, CHARGEBACK_INITIATED, CLOSED

List dispute case transition response
Sample response body
JSON
Copied

Is this helpful?

Yes
No

Create network dispute transition

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

Create a network dispute transition.

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

URL path parameters
Fields Description

token

string
Required

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

Allowable Values:

36 char max

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

Request body
Fields Description

action

string
Required

The action to take:

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

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

  • RESPOND_WITH_PREARB_RESPONSE: Respond to the prearbitration response.

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

  • CLOSE_WITH_CASE_WON: Close with case won dispute transition.

  • CLOSE_WITH_NETWORK_REJECTED: Close with network rejected.

  • REPRESENTMENT_RECEIVED: Indicates that representment was received.

Allowable Values:

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

created_by

string
Optional

The user who is creating the transition.

Allowable Values:

255 char max

memo

string
Optional

A memo regarding the transaction.

Allowable Values:

16777215 char max

network_details

object
Conditionally required

The network details.

Allowable Values:

The network_details object

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

Fields Description

prearbitration_details

object
Optional

Object defining the prearbitration details.

Allowable Values:

prearbitration_response_details

object
Optional

Object defining the prearbitration response details.

Allowable Values:

arbitration_details

object
Optional

Object defining the arbitration details.

Allowable Values:

representment_details

object
Optional

Object defining the network state details.

Allowable Values:

case_close_details

string
Optional

The new dispute state.

Allowable Values:

The prearbitration_details object

The details for prearbitration.

Fields Description

amount

number
Required

The amount in dispute.

Allowable Values:

32 bytes

attached_contents

string
Optional

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

Allowable Values:

256 char max

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

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

The details for arbitration.

Fields Description

attached_contents

string
Optional

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

Allowable Values:

256 char max

The representment_details object

The details for representment transition.

Fields Description

amount

number
Required

The amount in dispute.

Allowable Values:

Min: 0.1

attached_contents

string
Optional

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

Allowable Values:

256 char max

The case_close_details object

The details for case close transition details.

Fields Description

write_off

boolean
Optional

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

Allowable Values:

true, false

write_off_actor

string
Optional

The actor who performed the write off.

Allowable Values:

PROGRAM, ISSUER

Network dispute transition response body
Fields Description

token

string
Returned

The unique identifier of the dispute transition.

Allowable Values:

36 char max

created_time

datetime
Returned

The date and time that the transition was created.

Allowable Values:

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

last_modified_time

datetime
Returned

The date and time that the transition was last modified.

Allowable Values:

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

case_token

string
Returned

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

Allowable Values:

36 char max

action

string
Returned

The action taken.

Allowable Values:

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

created_by

string
Returned

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

Allowable Values:

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:

The network_details_response object

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

Fields Description

prearbitration_details

object
Optional

Object defining the prearbitration details.

Allowable Values:

prearbitration_response_details

object
Optional

Object defining the prearbitration response details.

Allowable Values:

arbitration_details

object
Optional

Object defining the arbitration details.

Allowable Values:

representment_details

object
Optional

Object defining the network state details.

Allowable Values:

network_state_details

string
Optional

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

Allowable Values:

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:

Sample request with prearbitration
JSON
Copied

Is this helpful?

Yes
No
Sample response with prearbitration
JSON
Copied

Is this helpful?

Yes
No
Sample request with arbitration
JSON
Copied

Is this helpful?

Yes
No
Sample response with arbitration
JSON
Copied

Is this helpful?

Yes
No
Sample accept and close dispute request
JSON
Copied

Is this helpful?

Yes
No
Sample accept and close dispute response
JSON
Copied

Is this helpful?

Yes
No
Sample close with case won dispute request
JSON
Copied

Is this helpful?

Yes
No
Sample close with case won dispute response
JSON
Copied

Is this helpful?

Yes
No

Retrieve network dispute transition

Action: GET
Endpoint: /cases/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
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
Sample response body
JSON
Copied

Is this helpful?

Yes
No

List network dispute transitions

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

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

URL path parameters
Fields Description

token

string
Required

The token of the dispute 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
Sample response body
JSON
Copied

Is this helpful?

Yes
No

Create dispute case content

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

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

The supported document formats are pdf, tiff, 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
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
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
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
JSON
Copied

Is this helpful?

Yes
No
Sample response body
JSON
Copied

Is this helpful?

Yes
No

List contents uploaded against a case

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

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

URL path parameter
Fields Description

token

string
Required

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

Allowable Values:

36 char max

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

List contents response

For response details, see Create content response body.

Sample response body
JSON
Copied

Is this helpful?

Yes
No

Get content and status

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

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

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

URL path parameters
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

For response details, see Create content response body.

Sample response body
JSON
Copied

Is this helpful?

Yes
No

Update document

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

For response details, see Create content response body.

Sample request body
JSON
Copied

Is this helpful?

Yes
No
Sample response body
JSON
Copied

Is this helpful?

Yes
No

Delete a document

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

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

Sample response body
JSON
Copied

Is this helpful?

Yes
No

Upload batch file

Action: POST
Endpoint: /cases/batch_files

Upload a batch file to initiate the bulk creation of dispute cases.

Request body
Fields Description

file_name

string
Required

The name of the file to upload.

Allowable Values:

255 char max

file_data

string
Required

The file content to be uploaded, up to 2MB in size.

Allowable Values:

1572864 char max

multi_program_code

string
Optional

If provided, the system assumes that the Excel file includes a SHARD column and uploads in the folder represented by this code.

Allowable Values:

A valid code

Response body

This endpoint returns a 201 response code with additional data that was gathered during the file upload process.

Fields Description

file_name

string
Returned

The name of the uploaded file.

Allowable Values:

255 char max

file_data

string
Returned

The uploaded file content, up to 2MB in size.

Allowable Values:

1572864 char max

multi_program_code

string
Conditionally returned

If provided, the system assumes that the Excel file includes a SHARD column and uploads in the folder represented by this code.

Allowable Values:

A valid code

Sample request
JSON
Copied

Is this helpful?

Yes
No
Sample response
JSON
Copied

Is this helpful?

Yes
No

Retrieve batch files

Action: GET
Endpoint: /cases/batch_files

Retrieve batch files filtered by the query parameters.

Query parameters
Fields Description

multi_program_code

string
Optional

Returns batch files that belong to the specified multi_program_code.

Allowable Values:

A valid code

exclude_multiprogram

string
Optional

Excludes files from the specified multi_program_code from the returned batch files.

Allowable Values:

A valid code

status

string
Optional

Returns batch files with a specific bulk file status.

Allowable Values:

PENDING, PROCESSING, FAILED, COMPLETED

Response body

This endpoint returns a 200 response code with data for all bulk files, lists of all the dispute cases that were created from the file, and any transaction that failed to be processed.

Fields Description

token

string
Conditionally returned

The unique identifier of the uploaded file, generated by the system in UUID format.

Allowable Values:

36 char max

file_name

string
Conditionally returned

The name of the uploaded file.

Allowable Values:

255 char max

status

string
Conditionally returned

The status of bulk file uploading process.

Allowable Values:

PENDING, PROCESSING, FAILED, COMPLETED

failure_reason

string
Conditionally returned

The reason why the file upload process failed.

Allowable Values:

255 char max

original_file_link

string
Conditionally returned

The original link to access the uploaded file.

Allowable Values:

A valid link

reject_report_link

string
Conditionally returned

The link to the report describing the upload rejection reason.

Allowable Values:

A valid link

processed_transactions

object
Conditionally returned

The list of successfully processed Excel file records.

Allowable Values:

rejected_transactions

object
Conditionally returned

The list of the Excel file records that failed to be processed, providing basic information about cases initiated during processing of the Excel file.

Allowable Values:

created_time

datetime
Conditionally 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
Conditionally returned

The date and time that the transition was last modified.

Allowable Values:

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

multi_program_code

string
Conditionally returned

If provided, the system assumes that the Excel file includes a SHARD column and uploads in the folder represented by this code.

Allowable Values:

A valid code

Sample response
JSON
Copied

Is this helpful?

Yes
No

Retrieve a batch file

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

Retrieve a specific batch file by token.

Path parameter
Fields Description

token

string
Required

The token that identifies the bulk file.

Allowable Values:

36 char max

Response body

This endpoint returns a 200 response code with data about the specific bulk file, a list of all the cases that were created from the file, and any transaction that failed to be processed.

Fields Description

token

string
Conditionally returned

The unique identifier of the uploaded file, generated by the system in UUID format.

Allowable Values:

36 char max

file_name

string
Conditionally returned

The name of the uploaded file.

Allowable Values:

255 char max

status

string
Conditionally returned

The status of bulk file uploading process.

Allowable Values:

PENDING, PROCESSING, FAILED, COMPLETED

failure_reason

string
Conditionally returned

The reason why the file upload process failed.

Allowable Values:

255 char max

original_file_link

string
Conditionally returned

The original link to access the uploaded file.

Allowable Values:

A valid link

reject_report_link

string
Conditionally returned

The link to the report describing the upload rejection reason.

Allowable Values:

A valid link

processed_transactions

object
Conditionally returned

The list of successfully processed Excel file records.

Allowable Values:

rejected_transactions

object
Conditionally returned

The list of the Excel file records that failed to be processed, providing basic information about cases initiated during processing of the Excel file.

Allowable Values:

created_time

datetime
Conditionally 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
Conditionally returned

The date and time that the transition was last modified.

Allowable Values:

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

multi_program_code

string
Conditionally returned

If provided, the system assumes that the Excel file includes a SHARD column and uploads in the folder represented by this code.

Allowable Values:

A valid code

Transaction_info
Fields Description

transaction_token

string
Conditionally returned

The unique identifier of the transaction for the case creation.

Allowable Values:

36 char max

case_token

string
Conditionally returned

The unique identifier of the dispute case.

Allowable Values:

36 char max

reject_reason

string
Conditionally returned

The reason why the case creation process failed during processing of the Excel file.

Allowable Values:

255 char max

Sample response
JSON
Copied

Is this helpful?

Yes
No
Join our developer newsletter