POST///
Transition a dispute case to another state or initiate a chargeback against the dispute case.
A dispute case transition is an event that changes the state of a dispute case and triggers other related events. The new state of the dispute case and which related events are triggered is determined by the action defined in the dispute case transition.
URL path parameters
| Fields | Description |
|---|---|
| token string Required | The token of the dispute case associated with the transition you want to create. Allowable Values: 36 char max Send a GET request to /cases to retrieve dispute case tokens. |
Body field details
| Fields | Description |
|---|---|
| token string Optional | The unique identifier of the dispute case transition. If you do not include a token, the system generates a token automatically. Allowable Values: 36 char max |
| action string Required | The action taken on the dispute case. Allowable Values: 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 dispute 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
| Fields | Description |
|---|---|
| chargeback_details object Required | An object containing the chargeback details. Allowable Values: See The chargeback_details object. |
The chargeback_details object
| Fields | Description |
|---|---|
| attached_contents string Required | List of content tokens that should be submitted to the network when initiating a chargeback. The content tokens should be associated to the case. For more information about 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 processes of a dispute case. The dispute case transition actions and resulting states are described below.| Action | Reason Code | Resulting State | Description |
|---|---|---|---|
| CREATE | N/A | 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.For programs that are enabled for Regulation E, this action and reason code returns an error for a Regulation E dispute and sets provisionalCreditGranted to true. |
| RE_OPEN | N/A | OPEN | Reopens a dispute case to get additional information or documents. Dispute case state changes to OPEN. |
| CHARGEBACK_CREDIT | 28 | CHARGEBACK_INITIATED | 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.Only for programs that are not enabled for Regulation E. |
| CHARGEBACK_NO_CREDIT | 29 | CHARGEBACK_INITIATED | 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.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_SUBMIT | 51 | CHARGEBACK_INITIATED | Submitting 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. |
| REVIEW | N/A | READY | Dispute case is ready to review. Dispute case state changes to READY. |
| ASSIGN | N/A | No change | Assigns a dispute case to a user. An assignee value is required. Does not change dispute case state. |
| KYC_OVERRIDE | N/A | CLOSED | Documents are verified and the case is being closed. |
| CLOSE | 41 | CLOSED | Closes 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. |
| CLOSE | 42 | CLOSED/PENDING_CLOSED | Closes 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. |
| CLOSE | 45 | CLOSED | Closes 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_DELETED | N/A | No change | Invalid documents were uploaded, documents are not in a readable format or quality, or documents are corrupted and not human readable. |
| REINSTATE_USER | N/A | CLOSED | Failed to reinstate the user. |
| REINSTATE_BUSINESS | N/A | CLOSED | Failed to reinstate the business. |
| WITHDRAW_AND_CLOSE | 40 | CLOSED | No further action is needed, closing the case by withdrawing. This action can only be taken from the OPEN or OPEN_WITH_ACTION_REQUIRED state and when provisional credit has not been granted. |
| WRITE_OFF | N/A | No change | Written off either by user or program. |
| GRANT_CREDIT | N/A | No change | Granting provisional credit. |
| REVERT_CREDIT | N/A | No change | Reverting provisional credit. |
| CHANGE_CASE_TYPE | N/A | No change | Change case from DISPUTE type to the LEGACY_DISPUTE type. |
The transition reason_code field
The transition reason code identifies the standardized reason for the transition.| Reason Code | Description | Related Actions |
|---|---|---|
| 00 | The dispute case was created. | CREATE |
| 01 | The dispute case was created, but needs additional verification actions. | CREATE |
| 05 | The dispute case is under review. | REVIEW |
| 14 | The Marqeta platform updated the dispute case. | CLOSE, NON_CHARGEBACK_CREDIT |
| 15 | An update was initiated by the issuer. | REINSTATE_USER, REINSTATE_BUSINESS |
| 18 | The user or business status was changed to ACTIVE because information was properly validated and confirmed. | REINSTATE_USER, REINSTATE_BUSINESS |
| 19 | The user or business status was changed to ACTIVE because account activity was properly validated and confirmed. | REINSTATE_USER, REINSTATE_BUSINESS |
| 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, DOCUMENTS_DELETED |
| 25 | The documents were verified and the dispute case is being closed. | CLOSE, KYC_OVERRIDE, REINSTATE_USER, REINSTATE_BUSINESS |
| 26 | The customer closed the dispute case. | CLOSE |
| 27 | The dispute is for a smaller amount and no chargeback is needed. | NON_CHARGEBACK_CREDIT |
| 28 | A chargeback was created and the cardholder was credited. Only for programs that are not enabled for Regulation E. | CHARGEBACK_CREDIT |
| 29 | A chargeback was created and the cardholder was not credited. Only for programs that are not enabled for Regulation E. | CHARGEBACK_NO_CREDIT |
| 30 | The dispute case was closed automatically due to inactivity. | CLOSE, WITHDRAW_AND_CLOSE |
| 31 | Invalid documents were uploaded. | DOCUMENTS_DELETED |
| 32 | Documents were uploaded that are unreadable because of incorrect format or poor quality. | DOCUMENTS_DELETED |
| 33 | Corrupted documents were uploaded. | DOCUMENTS_DELETED |
| 34 | The chargeback failed. Only for programs that are not enabled for Regulation E. | CHARGEBACK_CREDIT, CHARGEBACK_NO_CREDIT |
| 35 | The chargeback failed at the card network. Only for programs that are not enabled for Regulation E. | CHARGEBACK_CREDIT, CHARGEBACK_NO_CREDIT, CLOSE |
| 36 | KYC override failed. | KYC_OVERRIDE |
| 37 | User reinstatement failed. | REINSTATE_USER |
| 38 | Business reinstatement failed. | REINSTATE_BUSINESS |
| 39 | Associated transaction selection is required to ready this dispute case. | |
| 40 | No 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 |
| 41 | The dispute case was won, accepted with favorable results, for all types of dispute cases. This action cannot trigger until the dispute_state is CASE_WON. | CLOSE |
| 42 | The 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 |
| 43 | The dispute case was rejected by the network. | CLOSE |
| 44 | The dispute case was written off by the issuer. | WRITE_OFF, CLOSE |
| 45 | The dispute case was closed and written off by the program using funds from the program account. | WRITE_OFF, CLOSE |
| 46 | Provisional credit has been granted. | GRANT_CREDIT |
| 47 | Provisional credit has been reverted. | REVERT_CREDIT |
| 48 | A failure occurred when attempting to transition to the READY state. | No change |
| 49 | The dispute case was reported to the network as FRAUD. | WITHDRAW_AND_CLOSE |
| 50 | The dispute case was changed from DISPUTE type to LEGACY_DISPUTE type. | CHANGE_CASE_TYPE |
| 51 | Submitting 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. | CHARGEBACK_SUBMIT |
| 52 | Provisional credit is required for a Regulation E dispute case. | |
| 53 | Awaiting milestone. |
Dispute transition response
| Fields | Description |
|---|---|
| case_token string Returned | The unique identifier of the dispute case. Allowable Values: 36 char max |
| token string Returned | The unique identifier of the dispute case transition. If you did not include a token, the system generates a token automatically. Allowable Values: 36 char max |
| action string Returned | The action taken on the dispute case. Allowable Values: 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",
"assignee": "assignee_name",
"memo": "Initiating chargeback",
"transition_details": {
"chargeback_details": {
"attached_contents": [
"3fa85f64-5717-4562-b3fc-2c963f66afa6"
]
}
}
}
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.
| Action | Reason Code | Resulting State | Description |
|---|---|---|---|
CHARGEBACK_SUBMIT | 52 | OPEN_WITH_ACTION_REQUIRED | Triggered 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. |
CLOSE | 53 | PENDING_CLOSED | Triggered 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 usingCHARGEBACK_SUBMIT when the dispute has no provisional credit granted.
Error response
| Error Code | Error Message | Description |
|---|---|---|
| 400400 | Attempted 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. |
| 400400 | Cannot write off cases that haven’t granted provisional credit | Triggered 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. |
| 400401 | Case is no longer applicable as case lost under RegE | Triggered 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. |
| 400400 | Invalid Action for Current State | Triggered 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. |
| 400400 | Unable to withdraw and close because provisional credit has been granted | Triggered during an attempt to transition a case with WITHDRAW_AND_CLOSE when the provisional credit has been granted. |
| 400400 | Waiting for provisional credit to be reversed before the case can be closed | Triggered 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 provisional 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"]
}
}
}