/
30 minute read
March 22, 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

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:

Existing transaction token.

dispute_amount

decimal
Required

The amount of funds under dispute.

Allowable Values:

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

dispute_amount_change_reason

string
Conditionally required

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

Allowable Values:

MERCHANT_ISSUED_PARTIAL_REFUND, PARTIAL_DISPUTE, NOT_AS_DESCRIBED_PARTIAL, PARTIAL_SERVICE PRORATED_REFUND, NOT_AUTHORIZED_FOR_FULL_AMOUNT

Required if dispute_amount is not equal to transaction amount.

dispute_reason

string
Required

The code describing the reason for the dispute.

Allowable Values:

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

FRAUD_TRANSACTION

Fraudulent Processing of Transactions 4840

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_SHOW_ADDENDUM_OR_ATM_DISPUTE

No-show, Addendum, or ATM Dispute 4859

NOT_AUTHORIZED_CARD_PRESENT, NOT_AUTHORIZED_CARD_ABSENT

No Cardholder Authorization 4837

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

TRANSACTION_NOT_RECOGNIZED

Cardholder Does Not Recognize. Potential Fraud 4863

WARNING_BULLETIN_FILE

Warning Bulletin File 4807

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:

Existing dispute case token.

Response body
Fields Description

original_transaction_token

string
Returned

The token of the original transaction under dispute.

Allowable Values:

Existing transaction token.

original_transaction_type

string
Returned

The type of the original transaction under dispute.

Allowable Values:

Existing transaction token.

dispute_amount

decimal
Returned

The amount of funds under dispute.

Allowable Values:

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

dispute_amount_change_reason

string
Returned

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

Allowable Values:

MERCHANT_ISSUED_PARTIAL_REFUND, PARTIAL_DISPUTE, NOT_AS_DESCRIBED_PARTIAL, PARTIAL_SERVICE PRORATED_REFUND, NOT_AUTHORIZED_FOR_FULL_AMOUNT

currency_code

string
Returned

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

Allowable Values:

A valid currency code

dispute_reason

string
Returned

The code describing the reason for the dispute.

Allowable Values:

See the Dispute Reason table.

dispute_state

string
Returned

The current dispute state.

Allowable Values:

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

chargeback_token

string
Returned

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

Allowable Values:

A valid uuid.

network

string
Returned

The network where the transaction took place.

Allowable Values:

MASTERCARD

network_case_number

string
Returned

the network identifier for the dispute case.

Allowable Values:

A valid network case number.

acquirer_fee

number
Returned

The acquirer fee for the transaction.

Allowable Values:

A valid number.

card_token

string
Returned

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

Allowable Values:

A valid uuid.

network_failure_response

string
Returned

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

Allowable Values:

An error message returned from the network.

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:

An existing assignee.

chargeback_token

string
Optional

Returns dispute cases associated with the specified chargeback.

Allowable Values:

Existing chargeback token.

dispute_state

string
Optional

Returns dispute cases that are in the specified dispute state.

Allowable Values:

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

network_case_number

string
Optional

Returns dispute cases associated with the specified network case number.

Allowable Values:

A valid network case number.

next_actor

string
Optional

Returns dispute cases in the CHARGEBACK_INITIATED case state and who are associated with the provided next actor.

Allowable Values:

An existing next actor.

original_transaction_token

string
Optional

Returns dispute cases associated with the specified token.

Allowable Values:

Existing transaction token.

reason

string
Optional

Returns disputes that are using the provided dispute reason.

Allowable Values:

state

string
Optional

Returns disputes that are currently in the provided case state.

Allowable Values:

OPEN, OPEN_WITH_ACTION_REQUIRED, READY, CHARGEBACK_INITIATED, CLOSED

type

string
Optional

Returns cases of the specified type.

Allowable Values:

DISPUTE

user_token

string
Optional

Returns dispute cases associated with the specified user.

Allowable Values:

Existing user token.

Response body
Fields Description

token

string
Returned

The unique identifier of the dispute case.

Allowable Values:

Existing transaction token.

type

string
Returned

The type of case.

Allowable Values:

DISPUTE

memo

string
Returned

Free-form comments about the dispute.

Allowable Values:

512 char max

program_short_code

string
Returned

Indicates what program the case belongs to.

Allowable Values:

A valid short code.

user_token

string
Returned

Token that identifiers the user that made the original transaction.

Allowable Values:

A valid user uuid.

business_token

string
Returned

the token of the business involved in the dispute case.

Allowable Values:

A valid business token.

state

string
Returned

Indicates the current case state.

Allowable Values:

OPEN, OPEN_WITH_ACTION_REQUIRED, READY, CHARGEBACK_INITIATED, CLOSED

assignee

string
Returned

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

Allowable Values:

A valid user.

dispute_details

object
Returned

The details of the dispute case.

Allowable Values:

created_time

date
Returned

The time that the dispute case was created.

Allowable Values:

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

updated_time

date
Returned

The time that the dispute case was last updated.

Allowable Values:

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

The dispute_details_response object
Fields Description

original_transaction_token

string
Returned

The token of the original transaction under dispute.

Allowable Values:

Existing transaction token.

original_transaction_type

string
Returned

The type of the original transaction under dispute.

Allowable Values:

A valid transaction type.

dispute_amount

Decimal
Returned

The amount of funds under dispute.

Allowable Values:

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

dispute_amount_change_reason

string
Returned

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

Allowable Values:

MERCHANT_ISSUED_PARTIAL_REFUND, PARTIAL_DISPUTE, NOT_AS_DESCRIBED_PARTIAL, PARTIAL_SERVICE PRORATED_REFUND, NOT_AUTHORIZED_FOR_FULL_AMOUNT

currency_code

string
Returned

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

Allowable Values:

A valid currency code

dispute_reason

string
Returned

The code describing the reason for the dispute.

Allowable Values:

See the Dispute Reason table.

dispute_state

string
Returned

The current dispute state.

Allowable Values:

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

chargeback_token

string
Returned

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

Allowable Values:

A valid uuid.

network

string
Returned

The network where the transaction took place.

Allowable Values:

MASTERCARD

network_case_number

string
Returned

The network identifier for the dispute case.

Allowable Values:

A valid network case number.

acquirer_fee

number
Returned

The acquirer fee for the transaction.

Allowable Values:

A valid number.

card_token

string
Returned

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

Allowable Values:

A valid uuid.

network_failure_response

string
Returned

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

Allowable Values:

An error message returned from the network.

Sample response body
JSON
Copied

Is this helpful?

Yes
No

Create dispute case transition

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

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

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

URL path parameters
Fields Description

token

string
Required

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

Allowable Values:

Existing dispute case token.

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

Body field details
Fields Description

attached_contents

string
Optional

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

Allowable Values:

256 char max

token

string
Optional

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

Allowable Values:

36 char max

action

string
Required

The action taken on the dispute case.

Allowable Values:

reason_code

string
Required

Identifies the standardized reason for the transition.

Allowable Values:

created_by

string
Required

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

Allowable Values:

36 char max

memo

string
Optional

Additional notes about the transition.

Allowable Values:

512 char max

assignee

string
Optional

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

Allowable Values:

36 char max

Dispute case transitions

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

Action Resulting State Description

CREATE

OPEN, 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.

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.

REVIEW

READY

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

ASSIGN

No change

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

CLOSE

CLOSED

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

The reason_code field
Reason Code Description Related Actions

00

The dispute case was created.

CREATE

05

The dispute case is under review.

REVIEW

14

The Marqeta platform updated the dispute case.

CLOSE

22

The dispute case was assigned to a user.

ASSIGN

23

The dispute case was reopened.

RE_OPEN

24

The dispute case was reopened to gather more information.

RE_OPEN

26

The customer closed the dispute case.

CLOSE

28

A chargeback was created and the card holder was credited.

CHARGEBACK_CREDIT

29

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

CHARGEBACK_NO_CREDIT

30

The dispute case was closed automatically due to inactivity.

CLOSE

31

Invalid documents were uploaded.

DOCUMENTS_DELETED

32

Unreadable documents were uploaded.

DOCUMENTS_DELETED

33

Corrupted documents were uploaded.

DOCUMENTS_DELETED

34

The chargeback failed.

CHARGEBACK_CREDIT, CHARGEBACK_NO_CREDIT

35

The chargeback failed at the card network.

CHARGEBACK_CREDIT, CHARGEBACK_NO_CREDIT

Sample request body (CHARGEBACK_CREDIT)
JSON
Copied

Is this helpful?

Yes
No
Sample response body (CHARGEBACK_CREDIT)
JSON
Copied

Is this helpful?

Yes
No
Sample request body (CHARGEBACK_NO_CREDIT)
JSON
Copied

Is this helpful?

Yes
No
Sample response body (CHARGEBACK_NO_CREDIT)
JSON
Copied

Is this helpful?

Yes
No

Retrieve dispute case transition

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

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

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

URL path parameters
Fields Description

token

string
Required

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

Allowable Values:

Existing dispute case token.

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

transition_token

string
Required

The token of the transition to retrieve.

Allowable Values:

Existing dispute case transition token.

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

The action field (response only)

See Dispute Case Transitions for possible actions returned in the response.

Sample response body
JSON
Copied

Is this helpful?

Yes
No

List dispute case transitions

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

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

URL path parameters
Fields Description

token

string
Required

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

Allowable Values:

Existing dispute case token.

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

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 state of a dispute and triggers other related events. The new state of the dispute and which related events are triggered is determined by the action defined in the transition. Use this endpoint to respond and transition a dispute during the resolution process. Using this endpoint, you can respond with prearb, escalate to arbitration, or elect the final outcome of a dispute based on the evidence provided by the merchant/acquirer.

This endpoint allows you to include documents during backend resolution responses.

URL path parameters
Fields Description

token

string
Required

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

Allowable Values:

Existing dispute case token.

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

Request body
Fields Description

action

string
Required

The action to take:

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

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

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

  • CLOSE_WITH_CASE_WON: Close with case won dispute transition.

Allowable Values:

RESPOND_WITH_PREARB, RESPOND_WITH_ARB, ACCEPT_AND_CLOSE, CLOSE_WITH_CASE_WON, WAIT

created_by

string
Required

The user transitioning the dispute.

Allowable Values:

256 char max

memo

string
Optional

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

Allowable Values:

256 char max

network_details

object
Required

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

Allowable Values:

Response body
Fields Description

token

string
Returned

The network dispute transition token.

Allowable Values:

256 char max

created_time

date
Returned

The time that the transition was created.

Allowable Values:

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

last_modified_time

date
Returned

The time that the transition was last modified.

Allowable Values:

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

case_token

string
Returned

The dispute case token.

Allowable Values:

256 char max

action

string
Returned

The action taken.

Allowable Values:

created_by

string
Returned

The user transitioning the dispute.

Allowable Values:

256 char max

memo

string
Conditionally returned

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

Allowable Values:

256 char max

from_network_status

string
Returned

The dispute status from the network.

Allowable Values:

256 char max

to_network_status

string
Returned

The dispute status sent to the network.

Allowable Values:

256 char max

network_dispute_id

string
Returned

The network dispute ID.

Allowable Values:

256 char max

network_details

object
Returned

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

Allowable Values:

system_error_message

string
Conditionally returned

System error message.

Allowable Values:

network_error_message

string
Conditionally returned

Error message from the network.

Allowable Values:

The network_details object

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

Fields Description

prearbitration_details

object
Optional

Object defining the prearbitration details.

Allowable Values:

arbitration_details

object
Optional

Object defining the arbitration details.

Allowable Values:

network_state_details

object
Optional

Object defining the network state details.

Allowable Values:

dispute_state

string
Optional

The new dispute state.

Allowable Values:

A valid dispute state.

The prearbitration_details object
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

amount

float
Required

The amount in dispute.

Allowable Values:

A valid number.

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

To be added.

The network_state_details object

The network_state_details object provides details from the network for dispute case filing and second presentment.

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

amount

float
Required

The amount in dispute.

Allowable Values:

A valid number.

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
Required

The merchant name.

Allowable Values:

22 char max

The action field

See the Network Dispute Transitions table for possible actions returned in the response.

Network dispute transitions

The following table shows Mastercard transitions:

Status Description Allowable Dispute Transition Actions

Delivered/100.00% Acq Liability

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

WAIT

Delivered

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

WAIT

Accepted by Acq

The dispute has been accepted by acquirer.

ACCEPT_AND_CLOSE

Declined by Acq

The dispute has been declined by acquirer.

RESPOND_WITH_PREARB, ACCEPT_AND_CLOSE

Pre-Arb Timeframe Expired

The prearbitration timeframe has expired.

ACCEPT_AND_CLOSE

Pre-Arb Received

The prearbitration proposal has been received.

RESPOND_WITH_PREARB_RESPONSE, ACCEPT_AND_CLOSE

Pre-Arb Declined

The prearbitration proposal is declined.

WAIT

Accepted Full by Acq

Prearbitration has been accepted in full by the acquirer.

ACCEPT_AND_CLOSE

Pre-Arb Delivered

Prearbitration has been delivered.

WAIT

Pre-Arb Accepted Full

Prearbitration has been accepted in full.

ACCEPT_AND_CLOSE

Pre-Arb Declined

Prearbitration has been declined.

RESPOND_WITH_ARB

Response Timeframe Expired - 100% Acq Liability

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

ACCEPT_AND_CLOSE

Sample request 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
Sample dispute case filing response
JSON
Copied

Is this helpful?

Yes
No

Retrieve network dispute transition

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

Retrieve a specific network dispute transition for a specific dispute 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

token

string
Required

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

Allowable Values:

Existing dispute case token.

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

transition_token

string
Required

The token of the transition to retrieve.

Allowable Values:

Existing dispute case transition token.

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

Response fields
Fields Description

case_token

string
Returned

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

Allowable Values:

256 char max

action

string
Returned

The current action:

  • SUBMIT

  • ACCEPT_AND_CLOSE

  • RESPOND_WITH_PREARB

  • RESPOND_WITH_PREARB_RESPONSE

  • RESPOND_WITH_ARB

  • WAIT

  • ALLOCATION_ACKNOWLEDGED

  • REPRESENTMENT_RECEIVED

  • PREARB_RECEIVED

  • PREARB_DECLINED

  • PREARB_RESPONSE_DECLINED

  • ADJUSTMENT

Allowable Values:

256 char max

created_by

string
Returned

The user who created the action.

Allowable Values:

256 char max

memo

string
Conditionally returned

Free-form comments about the dispute.

Allowable Values:

256 char max

from_network_status

string
Returned

The dispute status from the network.

Allowable Values:

256 char max

to_network_status

string
Returned

The dispute status sent to the network.

Allowable Values:

256 char max

network_dispute_id

string
Returned

The network dispute ID.

Allowable Values:

256 char max

network_details

object
Returned

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

Allowable Values:

dispute_transition_token

number
Returned

The identifier for the dispute transition.

Allowable Values:

256 char max

prearbitration_details

object
Conditionally returned

Depends on the current state.

Allowable Values:

arbitration_details

object
Conditionally returned

Depends on the current state.

Allowable Values:

network_state_details

object
Conditionally returned

Depends on the current state.

Allowable Values:

dispute_state

string
Conditionally returned

The current dispute state.

Allowable Values:

A valid dispute state.

created_time

string
Conditionally returned

The time that the dispute was created.

Allowable Values:

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

Sample response body
JSON
Copied

Is this helpful?

Yes
No
Sample second presentment 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:

Existing dispute case token.

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

Response fields
Fields Description

case_token

string
Returned

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

Allowable Values:

256 char max

action

string
Returned

The current action:

  • SUBMIT

  • ACCEPT_AND_CLOSE

  • RESPOND_WITH_PREARB

  • RESPOND_WITH_PREARB_RESPONSE

  • RESPOND_WITH_ARB

  • WAIT

  • ALLOCATION_ACKNOWLEDGED

  • REPRESENTMENT_RECEIVED

  • PREARB_RECEIVED

  • PREARB_DECLINED

  • PREARB_RESPONSE_DECLINED

  • ADJUSTMENT

Allowable Values:

256 char max

created_by

string
Returned

The user who created the action.

Allowable Values:

256 char max

memo

string
Conditionally returned

Free-form comments about the dispute.

Allowable Values:

256 char max

from_network_status

string
Returned

The dispute status from the network.

Allowable Values:

256 char max

to_network_status

string
Returned

The dispute status sent to the network.

Allowable Values:

256 char max

network_dispute_id

string
Returned

The network dispute ID.

Allowable Values:

256 char max

network_details

object
Returned

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

Allowable Values:

dispute_transition_token

number
Returned

The identifier for the dispute transition.

Allowable Values:

256 char max

prearbitration_details

object
Conditionally returned

Depends on the current state.

Allowable Values:

arbitration_details

object
Conditionally returned

Depends on the current state.

Allowable Values:

network_state_details

object
Conditionally returned

Depends on the current state.

Allowable Values:

dispute_state

string
Conditionally returned

The current dispute state.

Allowable Values:

A valid dispute state.

created_time

string
Conditionally returned

The time that the dispute was created.

Allowable Values:

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

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:

Existing dispute case token.

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

Request body
Fields Description

document_category

string
Required

The category of the document.

Allowable Values:

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

document_name

string
Required

The name for the document.

Allowable Values:

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

document_data

bye
Required

Base64-encoded file.

Allowable Values:

2 MB max size

Create content response body
Fields Description

token

string
Returned

The token identifying the document.

Allowable Values:

Existing dispute case token.

case_token

string
Returned

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

Allowable Values:

Existing dispute case token.

document_name

string
Returned

The name of the document.

Allowable Values:

A valid document name.

document_category

string
Returned

The type of document.

Allowable Values:

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

document_content_type

string
Returned

The content type of the document.

Allowable Values:

application/pdf, image/tiff, image/jpeg

network_processing_type

string
Returned

Indicates the current status of the document at the network:

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

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

Allowable Values:

SUBMITTED, RECEIVED

network_processing_phase

string
Returned

Indicates the status of the document in the dispute lifecycle.

Allowable Values:

INITIATED, REPRESENTMENT, PRE_ARBITRATION

network_processing_time

string
Returned

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

Allowable Values:

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

created_time

string
Returned

The date and time when dispute was created.

Allowable Values:

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

updated_time

string
Returned

The date and time when dispute was last modified.

Allowable Values:

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

download_link

string
Returned

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

Allowable Values:

A valid URI.

Sample request body
JSON
Copied

Is this helpful?

Yes
No
Sample response body
JSON
Copied

Is this helpful?

Yes
No

List contents uploaded against a case

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

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

URL path parameter
Fields Description

token

string
Required

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

Allowable Values:

Existing dispute case token.

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

List contents response

For response details, see Create content response body.

Sample response body
JSON
Copied

Is this helpful?

Yes
No

Get content and status

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

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

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

URL path parameters
Fields Description

case_token

string
Required

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

Allowable Values:

Existing dispute case token.

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

token

string
Required

The token that identifies the document.

Allowable Values:

Existing content token.

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:

Existing dispute case token.

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

content_token

string
Required

The content token that identifies the document.

Allowable Values:

Existing content token.

Body field details
Fields Description

document_name

string
Required

The name for the document.

Allowable Values:

A valid document name.

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:

Existing dispute case token.

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:

Existing document token.

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
Join our developer newsletter