Skip to main content
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

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

See The dispute_details object table.

​
The dispute_details object

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

string

Required		The token 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

Conditionally required		The date that the cardholder made initial contact regarding the dispute. Required for Regulation E reason codes if the program has been enrolled for Regulation E provisional credit; otherwise, optional.

Allowable Values:

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

​
Dispute case reasons

The following are the possible Mastercard dispute messages along with the equivalent reason codes.
Mastercard Dual MessageReason Code
Authorization-related disputes
Required authorization not obtainedNO_AUTHORIZATION
Expired authorization protection periodNO_AUTHORIZATION
Multiple authorization requestsNO_AUTHORIZATION
Late presentmentNO_AUTHORIZATION

Cardholder disputes
Goods or services were either not as described or defectiveCARDHOLDER_DISPUTE
Goods or services not providedCARDHOLDER_DISPUTE
Credit not processedCREDIT_NOT_PROCESSED
Counterfeit goodsCARDHOLDER_DISPUTE
Recurring transactionCANCELLED_RECURRING_TRANSACTION
No-show hotel chargeCARDHOLDER_DISPUTE
Credit posted as a purchaseCARDHOLDER_DISPUTE

Fraud-related disputes
No cardholder authorization (card-absent or manual/key-entered card-present)NOT_AUTHORIZED_CARD_ABSENT
Chip liability shift (non-fallback transaction)CHIP_LIABILITY_SHIFT
Chip/PIN liability shift (card must be PIN-preferring to use this reason code)CHIP_PIN_LIABILITY_SHIFT_LOST_STOLEN

Point of interaction error disputes
Duplicate chargePOINT_OF_INTERACTION_ERRORS
Paid by other meansPOINT_OF_INTERACTION_ERRORS
Transaction amount differsPOINT_OF_INTERACTION_ERRORS
ATM disputesPOINT_OF_INTERACTION_ERRORS
Currency errorsPOINT_OF_INTERACTION_ERRORS

​
Response body

FieldsDescription
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 when the dispute case was created.

Allowable Values:

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

datetime

Returned		The time when the dispute case was last updated.

Allowable Values:

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

​
Sample request body

JSON
{
  "token": "string",
  "type": "DISPUTE",
  "memo": "Memo text",
  "dispute_details": {
    "original_transaction_token": "string",
    "dispute_amount": 0,
    "dispute_amount_change_reason": "MERCHANT_ISSUED_PARTIAL_REFUND",
    "currency_code": "USD",
    "dispute_reason": "CARDHOLDER_DISPUTE",
    "cardholder_contact_date": "2023-07-18T22:24:46.251Z"
  }
}

​
Sample response body

JSON
{
  "token": "string",
  "type": "DISPUTE",
  "memo": "string",
  "program_short_code": "string",
  "user_token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "business_token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "state": "OPEN",
  "assignee": "string",
  "zendesk_ticket_id": "string",
  "type_change_time": "string",
  "dispute_details": {
    "original_transaction_token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "original_transaction_type": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "dispute_amount": 0,
    "dispute_amount_change_reason": "MERCHANT_ISSUED_PARTIAL_REFUND",
    "currency_code": "string",
    "dispute_reason": "CARDHOLDER_DISPUTE",
    "dispute_state": "INITIATED",
    "chargeback_token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "network": "MASTERCARD",
    "acquirer_fee": 0,
    "associated_transaction_selection_required": true,
    "card_token": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "network_failure_response": "string",
    "cardholder_contact_date": "2023-07-18T22:24:46.251Z",
    "provisional_credit_granted": true,
    "regulation_type": "string"
  },
  "created_time": "2023-07-20T15:36:41.909Z",
  "updated_time": "2023-07-20T15:36:41.909Z"
}

​
Retrieve dispute case

Action: GET
Endpoint: /cases/{token} Retrieve a specific dispute case.

​
URL path parameters

FieldsDescription
token

string

Required		The token of the dispute case to retrieve.

Allowable Values:

36 char max

​
Query parameter

FieldsDescription
expand

string

Optional		If the regulation_type field is set to REG_E, adds the regulation_details fields inside dispute_details in the response. For more information, see The regulation_details object.

Allowable Values:

regulation_details

​
Response body

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

string

Returned		Token that identifiers the user that made the original transaction.

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
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 when the dispute case was created.

Allowable Values:

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

datetime

Returned		The time when the dispute case was last updated.

Allowable Values:

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

​
Sample response body

JSON
{
  "created_time": "2024-10-15T09:35:16Z",
  "last_modified_time": "2025-01-03T19:02:17Z",
  "token": "my_case_token",
  "type": "DISPUTE",
  "memo": "",
  "user_token": "my_user_token",
  "state": "CLOSED",
  "assignee": "Ross Geller",
  "zendesk_ticket_id": "1234",
  "dispute_details": {
    "original_transaction_token": "my_txn_token",
    "original_transaction_type": "authorization.clearing 3DS",
    "dispute_amount": 33.99,
    "currency_code": "GBP",
    "dispute_reason": "CARDHOLDER_DISPUTE",
    "dispute_state": "CASE_WON",
    "chargeback_token": "my_cb_token",
    "network": "MASTERCARD",
    "network_case_number": "my_networkCase_number",
    "card_token": "my_card_token",
    "cardholder_contact_date": "2024-08-19T07:16:00Z",
    "provisional_credit_granted": false,
    "acquirer_fee": 0.0000,
    "associated_transaction_selection_required": false,
    "network_case_status_details": {
      "created_time": "2024-10-15T10:45:03Z",
      "last_modified_time": "2025-01-03T19:02:16Z",
      "case_status": "Closed",
      "current_case_amount": 33.99,
      "next_actor": "DISPUTE_COMPLETED",
      "days_to_act": -194,
      "last_action_date": "2024-10-15T00:00:00Z",
      "case_opened_date": "2024-10-15T00:00:00Z",
      "last_refresh_date": "2025-01-03T19:02:17Z",
      "allowable_actions": []
    },
    "network_failure_response": ""
  },
  "case_tags": []
}

​
List dispute cases

Action: GET
Endpoint: /cases List existing dispute cases. This endpoint supports sorting and pagination.

​
Query parameters

FieldsDescription
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

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

string

Returned		Token that identifiers the user that made the original transaction.

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
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 when the dispute case was created.

Allowable Values:

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

datetime

Returned		The time when the dispute case was last updated.

Allowable Values:

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

​
The dispute_details_response object

FieldsDescription
original_transaction_token

string

Returned		The token of the original transaction under dispute.

Allowable Values:

36 char max
original_transaction_type

string

Returned		The type of the original transaction under dispute.

Allowable Values:

255 char max
dispute_amount

number

Returned		The amount of funds under dispute.

Allowable Values:

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

string

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

Allowable Values:

MERCHANT_ISSUED_PARTIAL_REFUND, PARTIAL_DISPUTE, NOT_AS_DESCRIBED_PARTIAL, PARTIAL_SERVICE, PRORATED_REFUND, NOT_AUTHORIZED_FOR_FULL_AMOUNT
currency_code

string

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

Allowable Values:

30 char max
dispute_reason

string

Returned		The code describing the reason for the dispute.

Allowable Values:

See the Dispute case reasons table.
dispute_state

string

Returned		The current dispute state. 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, 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. For Regulation E dispute cases, this value is returned after dispute case creation.

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 date that the cardholder made initial contact regarding the dispute.

Allowable Values:

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

boolean

Returned		Indicates whether the provisional credit was granted.

Allowable Values:

true, false
regulation_type

string

Returned		The regulation type of the disputer case. For Regulation E cases, this value is REG_E.

Allowable Values:

255 char max
regulation_details

object

Conditionally returned		Contains the Regulation E configuration that governs the dispute case throughout the lifecycle. Available only if the expanded query parameter was set to regulation_details in the query.

Allowable Values:

See The regulation details object.

​
The regulation_details object

FieldsDescription
pc_grant_days_to_act

string

Conditionally returned		The maximum number of days to grant provisional credit before the dispute case becomes out of compliance.

Allowable Values:

255 char max
pc_perm_days_to_act

string

Conditionally returned		The maximum number of days to reverse a cardholder’s provisional credit. If a dispute case is still open with no outcome, the provisional credit cannot be reversed from the cardholder.

Allowable Values:

255 char max
pc_reversed_coms_days_to_act

string

Conditionally returned		The maximum number of days to inform a cardholder that the provisional credit will be reversed from the day the case was attempted to be closed.

Allowable Values:

255 char max
pc_reversed_days_to_act

string

Conditionally returned		The number of business days that must elapse before the reversal of the provisional credit.

Allowable Values:

255 char max

​
Sample response body

JSON
{
  "count": 2,
  "start_index": 0,
  "end_index": 1,
  "is_more": true,
  "data": [
    {
      "created_time": "2024-10-15T09:35:16Z",
      "last_modified_time": "2025-01-03T19:02:17Z",
      "token": "my_case_token",
      "type": "DISPUTE",
      "memo": "",
      "user_token": "my_user_token",
      "state": "CLOSED",
      "assignee": "Ross Geller",
      "zendesk_ticket_id": "1234",
      "dispute_details": {
        "original_transaction_token": "my_txn_token",
        "original_transaction_type": "authorization.clearing 3DS",
        "dispute_amount": 33.99,
        "currency_code": "GBP",
        "dispute_reason": "CARDHOLDER_DISPUTE",
        "dispute_state": "CASE_WON",
        "chargeback_token": "my_cb_token",
        "network": "MASTERCARD",
        "network_case_number": "my_network_case_number",
        "card_token": "my_card_token",
        "cardholder_contact_date": "2024-08-19T07:16:00Z",
        "provisional_credit_granted": false,
        "acquirer_fee": 0.0000,
        "associated_transaction_selection_required": false,
        "network_case_status_details": {
          "created_time": "2024-10-15T10:45:03Z",
          "last_modified_time": "2025-01-03T19:02:16Z",
          "case_status": "Closed",
          "current_case_amount": 33.99,
          "next_actor": "DISPUTE_COMPLETED",
          "days_to_act": -194,
          "last_action_date": "2024-10-15T00:00:00Z",
          "case_opened_date": "2024-10-15T00:00:00Z",
          "last_refresh_date": "2025-01-03T19:02:17Z",
          "allowable_actions": []
        },
        "network_failure_response": ""
      },
      "case_tags": []
    },
    {
      "created_time": "2024-10-15T13:23:34Z",
      "last_modified_time": "2024-11-11T16:28:59Z",
      "token": "my_case_token",
      "type": "DISPUTE",
      "memo": "",
      "user_token": "my_user_token",
      "state": "CLOSED",
      "assignee": "Ross Geller",
      "zendesk_ticket_id": "1234",
      "dispute_details": {
        "original_transaction_token": "my_txn_token",
        "original_transaction_type": "authorization.clearing 3DS",
        "dispute_amount": 667.73,
        "currency_code": "GBP",
        "dispute_reason": "CARDHOLDER_DISPUTE",
        "dispute_state": "CASE_LOST",
        "network": "MASTERCARD",
        "network_case_number": "my_network_case_number",
        "card_token": "my_card_token",
        "cardholder_contact_date": "2024-09-18T17:17:00Z",
        "provisional_credit_granted": false,
        "acquirer_fee": 0.0000,
        "associated_transaction_selection_required": false,
        "network_case_status_details": {
          "created_time": "2024-10-15T18:47:03Z",
          "last_modified_time": "2024-11-14T10:32:03Z",
          "case_status": "Closed",
          "current_case_amount": 667.73,
          "next_actor": "DISPUTE_COMPLETED",
          "days_to_act": -194,
          "last_action_date": "2024-10-15T00:00:00Z",
          "case_opened_date": "2024-10-15T00:00:00Z",
          "last_refresh_date": "2024-11-14T10:32:03Z",
          "allowable_actions": []
        }
      },
      "case_tags": []
    }
  ]
}

​
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

FieldsDescription
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

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

FieldsDescription
chargeback_details

object

Required		An object containing the chargeback details.

Allowable Values:

See The chargeback_details object.

​
The chargeback_details object

FieldsDescription
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.
ActionReason CodeResulting StateDescription
CREATEN/AOPEN, OPEN_WITH_ACTION_REQUIREDCreates 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.

For programs that are enabled for Regulation E, this action and reason code returns an error for a Regulation E dispute and provisionalCreditGranted is set to true.
RE_OPENN/AOPENReopens a dispute case to get additional information or documents. Dispute case state changes to OPEN.
CHARGEBACK_CREDIT28CHARGEBACK_INITIATED, OPEN_WITH_ACTION_REQUIREDSends 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.

Only for programs that are not enabled for Regulation E.
CHARGEBACK_NO_CREDIT29CHARGEBACK_INITIATED, OPEN_WITH_ACTION_REQUIREDSends 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.

Only for programs that are not enabled for Regulation E. For programs that are enabled for Regulation E, this action and reason code return an error for a Regulation E dispute.
CHARGEBACK_SUBMIT51CHARGEBACK_INITIATEDSubmitting dispute to the network. This applies only to programs that are enabled for Regulation E and for a Regulation E dispute. If provisional credit has not been granted, this returns an error. For programs that are not enabled for Regulation E, this returns an error.
REVIEWN/AREADYDispute case is ready to review. Dispute case state changes to READY.
ASSIGNN/ANo changeAssigns a dispute case to a user. An assignee value is required. Does not change dispute case state.
CLOSE41CLOSEDCloses the dispute case.

The case was won. Dispute case state changes to CLOSED. For all types of dispute cases, this action cannot be triggered until dispute_state is in a CASE_WON state.
CLOSE42CLOSED/PENDING_CLOSEDCloses the dispute case. The case was lost. For non-Regulation E cases, this results in the CLOSED state. For Regulation E cases, this results in the PENDING_CLOSED state.
CLOSE45CLOSEDCloses the dispute case. Dispute case state changes to CLOSED. This reason code indicates that the case will be closed and written off using funds from the program account.
DOCUMENTS_DELETEDN/ANo changeInvalid documents were uploaded, documents are not in a readable format or quality, or documents are corrupted and not human readable.
WITHDRAW_AND_CLOSE40CLOSEDNo further action is needed, closing the case by withdrawing.
WRITE_OFFN/AWRITE_OFF_PROGRAMWritten off either by user or program.
GRANT_CREDITN/ANo changeGranting provisional credit.
REVERT_CREDITN/ANo changeReverting provisional credit.

​
The transition reason_code field

The transition reason code identifies the standardized reason for the transition.
Reason CodeDescriptionRelated Actions
00The dispute case was created.CREATE
01The dispute case was created, but needs additional verification actions.CREATE
05The dispute case is under review.REVIEW
14The Marqeta platform updated the dispute case.CLOSE, NON_CHARGEBACK_CREDIT
15An update was initiated by the issuer.REINSTATE_USER, REINSTATE_BUSINESS
18The user or business status was changed to ACTIVE because information was properly validated and confirmed.REINSTATE_USER, REINSTATE_BUSINESS
19The user or business status was changed to ACTIVE because account activity was properly validated and confirmed.REINSTATE_USER, REINSTATE_BUSINESS
22The dispute case was assigned to a user.ASSIGN
23The dispute case was reopened.RE_OPEN
24The dispute case was reopened to gather more information.RE_OPEN, DOCUMENTS_DELETED
25The documents were verified and the dispute case is being closed.CLOSE
26The customer closed the dispute case.CLOSE
27The dispute is for a smaller amount and no chargeback is needed.NON_CHARGEBACK_CREDIT
28A chargeback was created with provisional credit to the cardholder.

Only for programs that are not enabled for Regulation E.		CHARGEBACK_CREDIT
29A chargeback was created with no provisional credit to the cardholder.

Only for programs that are not enabled for Regulation E.		CHARGEBACK_NO_CREDIT
30The dispute case was closed automatically due to inactivity.CLOSE, WITHDRAW_AND_CLOSE
31Invalid documents were uploaded.DOCUMENTS_DELETED
32Documents were uploaded that are unreadable because of incorrect format or poor quality.DOCUMENTS_DELETED
33Corrupted documents were uploaded.DOCUMENTS_DELETED
34The chargeback initiation failed.

Only for programs that are not enabled for Regulation E.		CHARGEBACK_CREDIT, CHARGEBACK_NO_CREDIT
35The chargeback failed at the card network.

Only for programs that are not enabled for Regulation E.		CHARGEBACK_CREDIT, CHARGEBACK_NO_CREDIT, CLOSE
37User reinstatement failed.REINSTATE_USER
38Business reinstatement failed.REINSTATE_BUSINESS
39Associated transaction selection is required to ready this dispute case.
40No further action is needed. Closing the dispute case by withdrawing.

Only used when the provisional credit has not been granted in the OPEN and OPEN_WITH_ACTION_REQUIRED states. For Regulation E and non-Regulation E cases, this results in the CLOSED state and the chargeback is WITHDRAWN.		WITHDRAW_AND_CLOSE
41The dispute case was won, accepted with favorable results, for to all types of dispute cases.

This action cannot trigger until the dispute_state is CASE_WON.		CLOSE
42The dispute case was lost, accepted with unfavorable results.

For non-Regulation E dispute cases, this results in the CLOSED state. For Regulation E dispute cases, this results in PENDING_CLOSED.		CLOSE
43The dispute case was rejected by the network.CLOSE
44The dispute case was written off by the issuer.WRITE_OFF, CLOSE
45The dispute case was closed and written off by the program using funds from the program account.WRITE_OFF, CLOSE
46Provisional credit has been granted.GRANT_CREDIT
47Provisional credit has been reverted.REVERT_CREDIT
48A failure occurred when attempting to transition to the READY state.
49The dispute case was reported to the network as FRAUD.WITHDRAW_AND_CLOSE
50The dispute case was changed from DISPUTE type to LEGACY_DISPUTE type.CHANGE_CASE_TYPE
51The dispute case is being submitted to the network.

This applies only to programs that are enabled for Regulation E and for a Regulation E dispute. If provisional credit has not been granted, this returns an error. For programs that are not enabled for Regulation E, this returns an error.		CHARGEBACK_SUBMIT
52Provisional credit is required for a Regulation E dispute case.
53Awaiting milestone.

​
Dispute transition response

FieldsDescription
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 transition 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)

This sample is only for programs that are not enabled for Regulation E.
JSON
{
  "token": "dispute_case_token",
  "action": "CHARGEBACK_CREDIT",
  "reason_code": "28",
  "created_by": "user_name",
  "assignee": "assignee_name",
  "memo": "Text about this dispute",
  "transition_details": {
    "chargeback_details": {
      "attached_contents": [
        "3fa85f64-5717-4562-b3fc-2c963f66afa6"
      ]
    }
  }
}

​
Sample response body (CHARGEBACK_CREDIT)

This sample is only for programs that are not enabled for Regulation E.
JSON
{
  "case_token": "my_case_id",
  "token": "my_casetransition_id",
  "action": "CHARGEBACK_CREDIT",
  "reason_code": "28",
  "reason_description": "Smaller Amount",
  "created_by": "user_name",
  "from_state": "OPEN",
  "state": "CHARGEBACK_INITIATED",
  "assignee": "assignee_name",
  "memo": "Text about this dispute",
  "failure_reason": "string",
  "transition_details": {
    "chargeback_details": {
      "attached_contents": [
        "3fa85f64-5717-4562-b3fc-2c963f66afa6"
      ]
    }
  }
}

​
Sample request body (CHARGEBACK_NO_CREDIT)

JSON
{
  "token": "dispute_case_token",
  "action": "CHARGEBACK_NO_CREDIT",
  "reason_code": "29",
  "created_by": "user_name",
  "transition_details": {
    "chargeback_details": {
      "attached_contents": [
        "content_token"
      ]
    }
  }
}

​
Sample response body (CHARGEBACK_NO_CREDIT)

JSON
{
  "case_token": "my_case_id",
  "token": "my_casetransition_id",
  "action": "CHARGEBACK_N0_CREDIT",
  "reason_code": "29",
  "reason_description": "Smaller Amount",
  "created_by": "user_name",
  "from_state": "OPEN",
  "state": "CHARGEBACK_INITIATED",
  "assignee": "assignee_name",
  "memo": "Initiating chargeback",
  "failure_reason": "string",
  "transition_details": {
    "chargeback_details": {
      "attached_contents": [
        "3fa85f64-5717-4562-b3fc-2c963f66afa6"
      ]
    }
  }
}

​
Response action/reason code changes

There are some cases where the reason code is changed by the system for either of two reasons:
  • An error occurred while processing a transition.
  • The dispute case transition moved the case to a state different from the desired state.
ActionReason CodeResulting StateDescription
CHARGEBACK_SUBMIT52OPEN_WITH_ACTION_REQUIREDTriggered during an attempt to transition a dispute case with action CHARGEBACK_SUBMIT and reason code 51. Occurs when attempting to transition a Regulation E dispute case that has not granted provisional credit.
CLOSE53PENDING_CLOSEDTriggered during an attempt to transition a dispute case with action CLOSED and reason code 42. Occurs for Regulation E cases to indicate that the customer must first notify the cardholder before reverting the credit, as required by Regulation E, and must wait a specified number of days before reverting credit.

​
Sample response body (ACTION/REASON CODE CHANGES)

JSON
{
  "token": "string",
  "case_token": "string"
  "reason_code": "51",
  "reason_description": "Submit case to the card network"
  "created_by": "string",
  "from_state": "READY",
  "state": "CHARGEBACK_INITIATED",
  "action": "CHARGEBACK_SUBMIT",
  "memo": "string",
  "transition_details": {
    "chargeback_details": {
      "attached_contents": ["uuid"]
    }
  }
}

​
Transition failure response

An error occurs when attempting to transition a dispute case using CHARGEBACK_SUBMIT when the dispute has no provisional credit granted.

​
Error response

Error CodeError MessageDescription
400400Attempted to close case as case won when the dispute state is not set to CASE_WON.Triggered when an attempt to close a case as CASE_WON without having it be won in the backend lifecycle.
400400Cannot write off cases that haven’t been granted provisional creditTriggered during an attempt to transition a case with action CLOSE and reason code 45. Occurs for Regulation E cases if provisional credit has not been granted. Solution: Close the case using WITHDRAW_AND_CLOSE.
400401Case is no longer applicable as case lost under RegETriggered during an attempt to transition a dispute case with action CLOSE and reason code 42. Occurs for Regulation E cases that are past the Regulation E 45-day time limit.

Solution: Close the case with reason code 45.
400400Invalid Action for Current StateTriggered during CHARGEBACK_SUBMIT if the program is not Regulation E enabled. Triggered during CHARGEBACK_CREDIT or CHARGEBACK_NO_CREDIT when attempting to use this action to transition a REG_E case.
400400Unable to withdraw and close because provisional credit has been grantedTriggered during an attempt to transition a case with WITHDRAW_AND_CLOSE when the provisional credit has been granted.
400400Waiting for provisional credit to be reversed before the case can be closedTriggered during an attempt to transition a case with action CLOSE and reason code 42. Occurs if the case is in PENDING_CLOSED state and the reversal of provision credit has not occurred.

Solution: Wait for the provisional credit to be reversed.

​
Sample response body (TRANSITION FAILURE RESPONSE)

JSON
{
  "token": "string",
  "case_token": "string"
  "reason_code": "52",
  "reason_description": "Provisional credit required"
  "created_by": "string",
  "from_state": "READY",
  "state": "OPEN_WITH_ACTION_REQUIRED",
  "action": "CHARGEBACK_SUBMIT",
  "memo": "string",
  "transition_details": {
    "chargeback_details": {
      "attached_contents": ["uuid"]
    }
  }
}

​
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

FieldsDescription
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

See Dispute transition response.

​
Sample response body

JSON
{
  "case_token": "string",
  "token": "string",
  "action": "CREATE",
  "reason_code": "44",
  "reason_description": "string",
  "created_by": "string",
  "from_state": "OPEN",
  "state": "OPEN",
  "assignee": "string",
  "memo": "string",
  "failure_reason": "string",
  "transition_details": {
    "chargeback_details": {
      "attached_contents": [
        "3fa85f64-5717-4562-b3fc-2c963f66afa6"
      ]
    }
  }
}

​
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

FieldsDescription
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

FieldsDescription
state

string

Optional		Filter dispute case transitions that contain the specified resulting state.

Allowable Values:

OPEN, OPEN_WITH_ACTION_REQUIRED, READY, CHARGEBACK_INITIATED, CLOSED

​
List dispute case transition response

See Dispute transition response.

​
Sample response body

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

​
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

FieldsDescription
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

FieldsDescription
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

Depending on the transition, contains the prearbitration_details object or the arbitration_details object.
FieldsDescription
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 representment details.

Allowable Values:

See The representment_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

The details for prearbitration.
FieldsDescription
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.
FieldsDescription
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.
FieldsDescription
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.
FieldsDescription
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.
FieldsDescription
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

FieldsDescription
token

string

Returned		The unique identifier of the dispute transition.

Allowable Values:

36 char max
created_time

datetime

Returned		The date and time when the transition was created.

Allowable Values:

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

datetime

Returned		The date and time when 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 transition.

Allowable Values:

255 char max
network_dispute_id

string

Returned		The ID assigned to the dispute by the network.

Allowable Values:

36 char max
system_error_message

string

Conditionally returned		The error message for the system error.

Allowable Values:

16777215 char max
network_error_message

string

Conditionally returned		The error message for the network error.

Allowable Values:

16777215 char max
network_details

object

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

Allowable Values:

See The network_details_response object table.

​
The network_details_response object

Depending on the transition, contains the prearbitration_details object or the arbitration_details object.
FieldsDescription
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 representment details.

Allowable Values:

See The representment_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

JSON
{
  "action": "RESPOND_WITH_PREARB",
  "created_by": "user_name",
  "memo": "pre-arb transition for Mc testing",
  "network_details": {
    "prearbitration_details": {
      "amount": 112.0,
      "attached_contents": [
        "content_token"
      ],
      "why_are_you_initiating_prearbitration": "string",
      "are_you_providing_new_information": true,
      "summary_of_new_information": "string"
    },
    "prearbitration_response_details": {
      "attached_contents": [
        "string"
      ],
      "prearb_response_decision": "ACCEPT_PARTIAL",
      "amount": "string",
      "whyAreYouNotAcceptingLiability": "string",
      "certifyThatYouHaveContactedCardholderAndReviewedTheCompellingEvidenceWithThemAndCardholderContinuesDispute": true,
      "explanationOfWhyCardholderContinuesDispute": "string",
      "certifyThatCardholderNameAndAddressProvidedByAcquirerDoesNotMatchIssuerRecords": true,
      "explanationOfWhyYouAreContinuingTheDispute": "string"
    },
    "arbitration_details": {
      "attached_contents": [
        "string"
      ]
    },
    "representment_details": {
      "amount": 0.1,
      "attached_contents": [
        "string"
      ]
    },
    "case_close_details": {
      "write_off": true,
      "write_off_actor": "PROGRAM"
    }
  }
}

​
Sample response with prearbitration

JSON
{
  "token": "my_dispute_transition_token",
  "created_time": "2023-07-20T22:10:57.423Z",
  "last_modified_time": "2023-07-20T22:10:57.423Z",
  "case_token": "my_case_token",
  "action": "RESPOND_WITH_PREARB",
  "created_by": "user_name",
  "memo": "pre-arb transition for Mc testing",
  "from_network_status": "string",
  "to_network_status": "string",
  "network_dispute_id": "network_dispute_id",
  "system_error_message": "string",
  "network_error_message": "string",
  "network_details": {
    "prearbitration_details": {
      "amount": 112.5,
      "attached_contents": [
        "content_token"
      ],
      "why_are_you_initiating_prearbitration": "string",
      "are_you_providing_new_information": true,
      "summary_of_new_information": "string"
    },
    "prearbitration_response_details": {
      "attached_contents": [
        "content_token"
      ],
      "prearb_response_decision": "ACCEPT_PARTIAL",
      "amount": "string",
      "whyAreYouNotAcceptingLiability": "string",
      "certifyThatYouHaveContactedCardholderAndReviewedTheCompellingEvidenceWithThemAndCardholderContinuesDispute": true,
      "explanationOfWhyCardholderContinuesDispute": "string",
      "certifyThatCardholderNameAndAddressProvidedByAcquirerDoesNotMatchIssuerRecords": true,
      "explanationOfWhyYouAreContinuingTheDispute": "string"
    },
    "arbitration_details": {
      "attached_contents": [
        "content_token"
      ]
    },
    "representment_details": {
      "amount": 112.5,
      "attached_contents": [
        "content_token"
      ]
    },
    "network_state_details": "string",
    "dispute_state": "INITIATED",
    "case_close_details": {
      "write_off": true,
      "write_off_actor": "PROGRAM"
    }
  }
}

​
Sample request with arbitration

JSON
{
  "action": "RESPOND_WITH_ARB",
  "created_by": "user_name",
  "memo": "arbitration response transition response for Mc testing",
  "network_details": {
    "prearbitration_details": {
      "amount": 112.0,
      "attached_contents": [
        "content_token"
      ],
      "why_are_you_initiating_prearbitration": "string",
      "are_you_providing_new_information": true,
      "summary_of_new_information": "string"
    },
    "prearbitration_response_details": {
      "attached_contents": [
        "string"
      ],
      "prearb_response_decision": "ACCEPT_PARTIAL",
      "amount": "string",
      "whyAreYouNotAcceptingLiability": "string",
      "certifyThatYouHaveContactedCardholderAndReviewedTheCompellingEvidenceWithThemAndCardholderContinuesDispute": true,
      "explanationOfWhyCardholderContinuesDispute": "string",
      "certifyThatCardholderNameAndAddressProvidedByAcquirerDoesNotMatchIssuerRecords": true,
      "explanationOfWhyYouAreContinuingTheDispute": "string"
    },
    "arbitration_details": {
      "attached_contents": [
        "string"
      ]
    },
    "representment_details": {
      "amount": 0.1,
      "attached_contents": [
        "string"
      ]
    },
    "case_close_details": {
      "write_off": true,
      "write_off_actor": "PROGRAM"
    }
  }
}

​
Sample response with arbitration

JSON
{
  "token": "my_dispute_transition_token",
  "created_time": "2023-07-20T22:10:57.423Z",
  "last_modified_time": "2023-07-20T22:10:57.423Z",
  "case_token": "my_case_token",
  "action": "RESPOND_WITH_ARB",
  "created_by": "user_name",
  "memo": "Arbitration response transition response for Mc testing",
  "from_network_status": "string",
  "to_network_status": "string",
  "network_dispute_id": "network_dispute_id",
  "system_error_message": "string",
  "network_error_message": "string",
  "network_details": {
    "prearbitration_details": {
      "amount": 112.5,
      "attached_contents": [
        "content_token"
      ],
      "why_are_you_initiating_prearbitration": "string",
      "are_you_providing_new_information": true,
      "summary_of_new_information": "string"
    },
    "prearbitration_response_details": {
      "attached_contents": [
        "content_token"
      ],
      "prearb_response_decision": "ACCEPT_PARTIAL",
      "amount": "string",
      "whyAreYouNotAcceptingLiability": "string",
      "certifyThatYouHaveContactedCardholderAndReviewedTheCompellingEvidenceWithThemAndCardholderContinuesDispute": true,
      "explanationOfWhyCardholderContinuesDispute": "string",
      "certifyThatCardholderNameAndAddressProvidedByAcquirerDoesNotMatchIssuerRecords": true,
      "explanationOfWhyYouAreContinuingTheDispute": "string"
    },
    "arbitration_details": {
      "attached_contents": [
        "content_token"
      ]
    },
    "representment_details": {
      "amount": 112.5,
      "attached_contents": [
        "content_token"
      ]
    },
    "network_state_details": "string",
    "dispute_state": "INITIATED",
    "case_close_details": {
      "write_off": true,
      "write_off_actor": "PROGRAM"
    }
  }
}

​
Sample accept and close dispute request

JSON
{
  "action": "ACCEPT_AND_CLOSE",
  "created_by": "user_name",
  "memo": "accept and close",
  "network_details": {
    "prearbitration_details": {
      "amount": 112.0,
      "attached_contents": [
        "content_token"
      ],
      "why_are_you_initiating_prearbitration": "string",
      "are_you_providing_new_information": true,
      "summary_of_new_information": "string"
    },
    "prearbitration_response_details": {
      "attached_contents": [
        "string"
      ],
      "prearb_response_decision": "ACCEPT_PARTIAL",
      "amount": "string",
      "whyAreYouNotAcceptingLiability": "string",
      "certifyThatYouHaveContactedCardholderAndReviewedTheCompellingEvidenceWithThemAndCardholderContinuesDispute": true,
      "explanationOfWhyCardholderContinuesDispute": "string",
      "certifyThatCardholderNameAndAddressProvidedByAcquirerDoesNotMatchIssuerRecords": true,
      "explanationOfWhyYouAreContinuingTheDispute": "string"
    },
    "arbitration_details": {
      "attached_contents": [
        "string"
      ]
    },
    "representment_details": {
      "amount": 0.1,
      "attached_contents": [
        "string"
      ]
    },
    "case_close_details": {
      "write_off": true,
      "write_off_actor": "PROGRAM"
    }
  }
}

​
Sample accept and close dispute response

JSON
{
  "token": "my_dispute_transition_token",
  "created_time": "2023-07-20T22:10:57.423Z",
  "last_modified_time": "2023-07-20T22:10:57.423Z",
  "case_token": "my_case_token",
  "action": "ACCEPT_AND_CLOSE",
  "created_by": "user_name",
  "memo": "accept and close",
  "from_network_status": "string",
  "to_network_status": "string",
  "network_dispute_id": "network_dispute_id",
  "system_error_message": "string",
  "network_error_message": "string",
  "network_details": {
    "prearbitration_details": {
      "amount": 112.5,
      "attached_contents": [
        "content_token"
      ],
      "why_are_you_initiating_prearbitration": "string",
      "are_you_providing_new_information": true,
      "summary_of_new_information": "string"
    },
    "prearbitration_response_details": {
      "attached_contents": [
        "content_token"
      ],
      "prearb_response_decision": "ACCEPT_PARTIAL",
      "amount": "string",
      "whyAreYouNotAcceptingLiability": "string",
      "certifyThatYouHaveContactedCardholderAndReviewedTheCompellingEvidenceWithThemAndCardholderContinuesDispute": true,
      "explanationOfWhyCardholderContinuesDispute": "string",
      "certifyThatCardholderNameAndAddressProvidedByAcquirerDoesNotMatchIssuerRecords": true,
      "explanationOfWhyYouAreContinuingTheDispute": "string"
    },
    "arbitration_details": {
      "attached_contents": [
        "content_token"
      ]
    },
    "representment_details": {
      "amount": 112.5,
      "attached_contents": [
        "content_token"
      ]
    },
    "network_state_details": "string",
    "dispute_state": "INITIATED",
    "case_close_details": {
      "write_off": true,
      "write_off_actor": "PROGRAM"
    }
  }
}

​
Sample close with case won dispute request

JSON
{
  "action": "CLOSE_WITH_CASE_WON",
  "created_by": "user_name",
  "memo": "close with case won",
  "network_details": {
    "prearbitration_details": {
      "amount": 112.0,
      "attached_contents": [
        "content_token"
      ],
      "why_are_you_initiating_prearbitration": "string",
      "are_you_providing_new_information": true,
      "summary_of_new_information": "string"
    },
    "prearbitration_response_details": {
      "attached_contents": [
        "string"
      ],
      "prearb_response_decision": "ACCEPT_PARTIAL",
      "amount": "string",
      "whyAreYouNotAcceptingLiability": "string",
      "certifyThatYouHaveContactedCardholderAndReviewedTheCompellingEvidenceWithThemAndCardholderContinuesDispute": true,
      "explanationOfWhyCardholderContinuesDispute": "string",
      "certifyThatCardholderNameAndAddressProvidedByAcquirerDoesNotMatchIssuerRecords": true,
      "explanationOfWhyYouAreContinuingTheDispute": "string"
    },
    "arbitration_details": {
      "attached_contents": [
        "string"
      ]
    },
    "representment_details": {
      "amount": 0.1,
      "attached_contents": [
        "string"
      ]
    },
    "case_close_details": {
      "write_off": true,
      "write_off_actor": "PROGRAM"
    }
  }
}

​
Sample close with case won dispute response

JSON
{
  "token": "my_dispute_transition_token",
  "created_time": "2023-07-20T22:10:57.423Z",
  "last_modified_time": "2023-07-20T22:10:57.423Z",
  "case_token": "my_case_token",
  "action": "CLOSE_WITH_CASE_WON",
  "created_by": "user_name",
  "memo": "close with case won",
  "from_network_status": "string",
  "to_network_status": "string",
  "network_dispute_id": "network_dispute_id",
  "system_error_message": "string",
  "network_error_message": "string",
  "network_details": {
    "prearbitration_details": {
      "amount": 112.5,
      "attached_contents": [
        "content_token"
      ],
      "why_are_you_initiating_prearbitration": "string",
      "are_you_providing_new_information": true,
      "summary_of_new_information": "string"
    },
    "prearbitration_response_details": {
      "attached_contents": [
        "content_token"
      ],
      "prearb_response_decision": "ACCEPT_PARTIAL",
      "amount": "string",
      "whyAreYouNotAcceptingLiability": "string",
      "certifyThatYouHaveContactedCardholderAndReviewedTheCompellingEvidenceWithThemAndCardholderContinuesDispute": true,
      "explanationOfWhyCardholderContinuesDispute": "string",
      "certifyThatCardholderNameAndAddressProvidedByAcquirerDoesNotMatchIssuerRecords": true,
      "explanationOfWhyYouAreContinuingTheDispute": "string"
    },
    "arbitration_details": {
      "attached_contents": [
        "content_token"
      ]
    },
    "representment_details": {
      "amount": 112.5,
      "attached_contents": [
        "content_token"
      ]
    },
    "network_state_details": "string",
    "dispute_state": "INITIATED",
    "case_close_details": {
      "write_off": true,
      "write_off_actor": "PROGRAM"
    }
  }
}

​
Create ACCEPT_AND_CLOSE transition

This transition moves the network dispute state to CASE_LOST and sets the case transition to CLOSE with reason code 42 (Case Lost). For Regulation E dispute cases, if the case is past 45 days, the callee must specify both write_off and write_off_actor. When this occurs, the dispute state is set to WRITE_OFF_PROGRAM and sets the case transition to CLOSE with reason code 45 (Write off Program).

​
Query parameters

FieldsDescription
action

string

Required		The action taken.

Allowable Values:

ACCEPT_AND_CLOSE
created_by

string

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

Allowable Values:

256 char max
memo

string

Required		A memo regarding the transaction.

Allowable Values:

16777215 char max
close_case_details.write_off

boolean

Conditionally required		Required if the 45-day Regulation E time limit has expired.

Allowable Values:

true, false
close_case_details.write_off_actor

string

Conditionally required		Triggers a CLOSE case transition with reason code 45. Required if the 45-day Regulation E time limit has expired.

Allowable Values:

PROGRAM

​
Response fields

See the Network dispute transition response table.

​
Error codes

Error CodeError MessageDescription
400301Case is RegE and can only be accepted and closed with write off after it expiresTriggered when attempting to do an ACCEPT_AND_CLOSE action without write-off information for a case that has exceeded the 45-day milestone.

​
Sample ACCEPT_AND_CLOSE transition request

JSON
{
  "action": "ACCEPT_AND_CLOSE",
  "created_by": "string",
  "memo": "string",
  "network_details": {
    "case_close_details": {
      "write_off": true,
      "write_off_actor": "PROGRAM"
    }
  }
}

​
Sample ACCEPT_AND_CLOSE transition response

JSON
{
  "token": "string",
  "case_token": "string",
  "action": "ACCEPT_AND_CLOSE",
  "created_by": "string",
  "memo": "string",
  "from_network_status": "string",
  "to_network_status": "string",
  "network_dispute_id": "string",
  "system_error_message": "string",
  "network_error_message": "string",
  "created_time": "timestamp",
  "last_modified_time": "timestamp",
  "network_details": {
    "case_close_details": {
      "write_off": true,
      "write_off_actor": "PROGRAM"
    }
  }
}

​
Create CLOSE_WITH_CASE_WON transition

For Regulation E and non-Regulation E network dispute cases, the dispute state is set to CASE_WON and a CLOSE case transition with reason code 41 (Case Won) is created.

​
Sample CLOSE_WITH_CASE_WON transition request

JSON
{
  "action": "CLOSE_WITH_CASE_WON",
  "created_by": "string",
  "memo": "string"
}

​
Sample CLOSE_WITH_CASE_WON transition response

JSON
{
  "token": "string",
  "case_token": "string",
  "action": "ACCEPT_AND_CLOSE",
  "created_by": "string",
  "memo": "string",
  "from_network_status": "string",
  "to_network_status": "string",
  "network_dispute_id": "string",
  "system_error_message": "string",
  "network_error_message": "string",
  "created_time": "timestamp",
  "last_modified_time": "timestamp",
  "network_details": {
    "case_close_details": {
      "write_off": true,
      "write_off_actor": "PROGRAM"
    }
  }
}

​
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

FieldsDescription
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

See the Network dispute transition response table.

​
Sample response body

JSON
{
  "token": "my_network_transition_id1",
  "created_time": "2023-07-21T19:32:01.326Z",
  "last_modified_time": "2023-07-21T19:32:01.326Z",
  "case_token": "my_case_token",
  "action": "CHARGEBACK_CREDIT",
  "created_by": "user_name",
  "memo": "Initiating chargeback",
  "from_network_status": "string",
  "to_network_status": "string",
  "network_dispute_id": "string",
  "system_error_message": "string",
  "network_error_message": "string",
  "network_details": {
    "prearbitration_details": {
      "amount": 120.0,
      "attached_contents": [
        "string"
      ],
      "why_are_you_initiating_prearbitration": "string",
      "are_you_providing_new_information": true,
      "summary_of_new_information": "string"
    },
    "prearbitration_response_details": {
      "attached_contents": [
        "string"
      ],
      "prearb_response_decision": "ACCEPT_PARTIAL",
      "amount": "string",
      "whyAreYouNotAcceptingLiability": "string",
      "certifyThatYouHaveContactedCardholderAndReviewedTheCompellingEvidenceWithThemAndCardholderContinuesDispute": true,
      "explanationOfWhyCardholderContinuesDispute": "string",
      "certifyThatCardholderNameAndAddressProvidedByAcquirerDoesNotMatchIssuerRecords": true,
      "explanationOfWhyYouAreContinuingTheDispute": "string"
    },
    "arbitration_details": {
      "attached_contents": [
        "string"
      ]
    },
    "representment_details": {
      "amount": 120.0,
      "attached_contents": [
        "string"
      ]
    },
    "network_state_details": "string",
    "dispute_state": "CHARGEBACK_INITIATED",
    "case_close_details": {
      "write_off": true,
      "write_off_actor": "PROGRAM"
    }
  }
}

​
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

FieldsDescription
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

See the Network dispute transition response table.

​
Sample response body

JSON
{
  "count": 0,
  "start_index": 0,
  "end_index": 0,
  "is_more": true,
  "data": [
    {
      "token": "string",
      "created_time": "2023-07-21T17:37:37.792Z",
      "last_modified_time": "2023-07-21T17:37:37.792Z",
      "case_token": "string",
      "action": "SUBMIT",
      "created_by": "string",
      "memo": "string",
      "from_network_status": "string",
      "to_network_status": "string",
      "network_dispute_id": "string",
      "system_error_message": "string",
      "network_error_message": "string",
      "network_details": {
        "prearbitration_details": {
          "amount": 0,
          "attached_contents": [
            "string"
          ],
          "why_are_you_initiating_prearbitration": "string",
          "are_you_providing_new_information": true,
          "summary_of_new_information": "string"
        },
        "prearbitration_response_details": {
          "attached_contents": [
            "string"
          ],
          "prearb_response_decision": "ACCEPT_PARTIAL",
          "amount": "string",
          "whyAreYouNotAcceptingLiability": "string",
          "certifyThatYouHaveContactedCardholderAndReviewedTheCompellingEvidenceWithThemAndCardholderContinuesDispute": true,
          "explanationOfWhyCardholderContinuesDispute": "string",
          "certifyThatCardholderNameAndAddressProvidedByAcquirerDoesNotMatchIssuerRecords": true,
          "explanationOfWhyYouAreContinuingTheDispute": "string"
        },
        "arbitration_details": {
          "attached_contents": [
            "string"
          ]
        },
        "representment_details": {
          "amount": 0.1,
          "attached_contents": [
            "string"
          ]
        },
        "network_state_details": "string",
        "dispute_state": "INITIATED",
        "case_close_details": {
          "write_off": true,
          "write_off_actor": "PROGRAM"
        }
      }
    }
  ]
}

​
Create dispute case content

Action: POST
Endpoint: /cases/{token}/contents Upload and store evidentiary documents related to a dispute. 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

FieldsDescription
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

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

FieldsDescription
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 the dispute was created.

Allowable Values:

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

datetime

Returned		The date and time when the 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
Content-Type: multipart/form-data; boundary=marqeta_file_separator
Cache-Control: no-cache

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

{
  "document_category": "RECEIPT",
  "document_name": "receipt.pdf",
  "document_data": "string"
}

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

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

--marqeta_file_separator--

​
Sample response body

JSON
{
  "token": "my_content_token",
  "case_token": "my_case_token",
  "document_name": "string",
  "document_category": "RECEIPT",
  "document_content_type": "application/pdf",
  "network_processing_type": "SUBMITTED",
  "network_processing_phase": "INITIATED",
  "network_processing_time": "2024-02-01T20:22:34.913Z",
  "created_time": "2024-02-01T20:22:34.913Z",
  "updated_time": "2024-02-01T20:22:34.913Z",
  "download_link": "download_link"
}

​
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

FieldsDescription
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
{
  "count": 2,
  "start_index": 0,
  "end_index": 1,
  "is_more": false,
  "data": [
    {
      "token": "my_content_token",
      "case_token": "my_case_token",
      "document_name": "receipt.pdf",
      "document_category": "RECEIPT",
      "document_content_type": "image/jpeg",
      "network_processing_type": "RECEIVED",
      "network_processing_phase": "INITIATED",
      "network_processing_time": "2021-03-19T13:22:07Z",
      "created_time": "2021-03-19T13:22:07Z",
      "updated_time": "2021-03-19T13:22:07Z",
      "download_link": "uri"
    },
    {
      "token": "my_content_token",
      "case_token": "my_case_token",
      "document_name": "receipt.pdf",
      "document_category": "RECEIPT",
      "document_content_type": "image/jpeg",
      "network_processing_type": "RECEIVED",
      "network_processing_phase": "INITIATED",
      "network_processing_time": "timestamp",
      "created_time": "2021-03-19T13:22:07Z",
      "updated_time": "2021-03-19T13:22:07Z",
      "download_link": "uri"
    }
  ]
}

​
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

FieldsDescription
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
{
  "token": "my_content_token",
  "case_token": "my_case_token",
  "document_name": "letter.pdf",
  "document_category": "CARDHOLDER_LETTER",
  "document_content_type": "string",
  "network_processing_type": "SUBMITTED",
  "network_processing_phase": "INITIATED",
  "network_processing_time": "2024-02-02T23:06:18.429Z",
  "created_time": "2024-02-02T23:06:18.429Z",
  "updated_time": "2024-02-02T23:06:18.429Z",
  "download_link": "uri"
}

​
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

FieldsDescription
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

FieldsDescription
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
{
  "document_name": "receipt.pdf",
  "document_category": "RECEIPT"
}

​
Sample response body

JSON
{
  "token": "my_content_token",
  "case_token": "my_case_token",
  "document_name": "letter.pdf",
  "document_category": "CARDHOLDER_LETTER",
  "document_content_type": "string",
  "network_processing_type": "SUBMITTED",
  "network_processing_phase": "INITIATED",
  "network_processing_time": "2024-02-02T23:06:18.429Z",
  "created_time": "2024-02-02T23:06:18.429Z",
  "updated_time": "2024-02-02T23:06:18.429Z",
  "download_link": "uri"
}

​
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

FieldsDescription
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
{
  "status": "success"
}

​
Create dispute case action

Action: POST
Endpoint: /cases/{token}/actions Create a dispute case action.

​
Path parameter

FieldsDescription
token

string

Required		The token that identifies the dispute case.

Allowable Values:

36 char max

​
Body field details

FieldsDescription
action_type

string

Required		The action to take: grant provisional credit and trigger the event.

Allowable Values:

GRANT_PROVISIONAL_CREDIT
created_by

string

Required		The user who created the action.

Allowable Values:

255 char

​
Response body

FieldsDescription
token

string

Returned		The unique identifier of the dispute case.

Allowable Values:

36 char max
action_type

string

Returned		The action taken.

Allowable Values:

255 char max
created_by

string

Returned		The user who created the action.

Allowable Values:

255 char

​
Sample request

JSON
{
  "action_type": "GRANT_PROVISIONAL_CREDIT",
  "created_by": "string"
}

​
Sample response

JSON
{
  "case_token": "<my_case_token>",
  "action_type": "GRANT_PROVISIONAL_CREDIT",
  "created_by": "string"
}

​
Create event

Action: POST
Endpoint: /cases/{token}/events Create a dispute case event. If you are a Managed by Marqeta (MxM) customer or a hybrid card program and you are submitting a dispute that falls under Regulation E, you must create a case event with evidence. For instructions on creating a case event with evidence, see Disputes Evidence Collection.

​
Path parameter

FieldsDescription
token

string

Required		The token that identifies the dispute case.

Allowable Values:

36 char max

​
Body field details

FieldsDescription
name

string

Required		The name of the event.

Allowable Values:

255 char max
event_date

string

Optional		When the event took place.

Allowable Values:

Format: yyyy-MM-dd’T’HH:mm:ssZ
created_by

string

Required		The user creating the event.

Allowable Values:

255 char max

​
Response body

FieldsDescription
token

string

Returned		The generated UUID of the event.

Allowable Values:

36 char max
case_token

string

Returned		The associated case that triggered this event.

Allowable Values:

36 char max
name

string

Returned		The name of the event.

Allowable Values:

255 char max
category

string

Returned		The category to which the event belongs.

Allowable Values:

REG_E
created_by

string

Required		The user creating the event.

Allowable Values:

255 char max
event_date

string

Returned		When the event took place.

Allowable Values:

Format: yyyy-MM-dd’T’HH:mm:ssZ
created_time

string

Returned		The timestamp when the event was created.

Allowable Values:

Format: yyyy-MM-dd’T’HH:mm:ssZ

​
Sample request

JSON
{
  "name": "string",
  "created_by": "string",
  "event_date": "timestamp",
  }
}

​
Sample response

JSON
{
    "token": "uuid",
    "case_token": "string",
    "name": "string",
    "category": "string",
    "created_by": "string",
    "event_date": "timestamp",
    "created_time": "timestamp"
}

​
List events

Action: GET
Endpoint: /cases/{token}/events List events.

​
Path parameter

FieldsDescription
token

string

Required		The token that identifies the dispute case.

Allowable Values:

36 char max

​
Body field details

FieldsDescription
name

string

Required		The name of the event.

Allowable Values:

255 char max
event_date

string

Optional		When the event took place.

Allowable Values:

Format: yyyy-MM-dd’T’HH:mm:ssZ
created_by

string

Required		The user creating the event.

Allowable Values:

255 char max
categories

object

Optional		The categories to which the event belongs.

Allowable Values:

REG_E

​
Response body

FieldsDescription
token

string

Returned		The generated UUID of the event.

Allowable Values:

36 char max
case_token

string

Returned		The associated case that triggered this event.

Allowable Values:

36 char max
name

string

Returned		The name of the event.

Allowable Values:

255 char max
category

string

Returned		The category to which the event belongs.

Allowable Values:

REG_E
created_by

string

Required		The user creating the event.

Allowable Values:

255 char max
event_date

string

Returned		When the event took place.

Allowable Values:

Format: yyyy-MM-dd’T’HH:mm:ssZ
created_time

string

Returned		The timestamp when the event was created.

Allowable Values:

Format: yyyy-MM-dd’T’HH:mm:ssZ

​
Sample response

JSON
{
  "count": 30,
  "start_index": 0,
  "end_index": 29,
  "is_more": true,
  "data": [
    {
        "case_token": "string",
        "category": "string",
        "sub_category": "string",
        "milestone": "string",
        "next_milestone_due_date": "timestamp",
        "created_time": "timestamp",
        "last_modified_time": "timestamp"
    }
  ]
}

​
List dispute case milestones

Action: GET
Endpoint: /cases/{token}/milestones List dispute case milestones.

​
Path parameter

FieldsDescription
token

string

Required		The token that identifies the dispute case.

Allowable Values:

36 char max

​
Body field details

FieldsDescription
name

string

Required		The name of the event.

Allowable Values:

255 char max
event_date

string

Optional		When the event took place.

Allowable Values:

Format: yyyy-MM-dd’T’HH:mm:ssZ
created_by

string

Required		The user creating the event.

Allowable Values:

255 char max
categories

object

Optional		The categories to which the event belongs.

Allowable Values:

REG_E
subcategories

object

Optional		The subcategories to which the event belongs.

Allowable Values:

PROVISIONAL_CREDIT, CARDHOLDER_COMMS

​
Response body

FieldsDescription
case_token

string

Returned		The associated case that triggered this event.

Allowable Values:

36 char max
category

string

Returned		The category to which the event belongs.

Allowable Values:

REG_E
sub_category

string

Returned		The subcategory to which the event belongs.

Allowable Values:

REG_E
milestone

string

Required		The milestone.

Allowable Values:

255 char max
next_milestone_due_date

datetime

Returned		The date that the next milestone is due.

Allowable Values:

Format: yyyy-MM-dd’T’HH:mm:ssZ
created_time

datetime

Returned		The timestamp when the event was created.

Allowable Values:

Format: yyyy-MM-dd’T’HH:mm:ssZ
last_modified_time

datetime

Returned		The timestamp when the event was last modified.

Allowable Values:

Format: yyyy-MM-dd’T’HH:mm:ssZ

​
Sample response

JSON
{
  "count": 30,
  "start_index": 0,
  "end_index": 29,
  "is_more": true,
  "data": [
    {
        "case_token": "string",
        "category": "string",
        "sub_category": "string",
        "milestone": "string",
        "next_milestone_due_date": "timestamp",
        "created_time": "timestamp",
        "last_modified_time": "timestamp"
    }
  ]
}

Related topics

Managing Mastercard DisputesDisputes (Visa)Disputes OverviewAbout DisputesAbout Credit Account Disputes