> ## Documentation Index
> Fetch the complete documentation index at: https://www.marqeta.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Disputes (Mastercard)
> Use the cases endpoint to manage transaction disputes on the Mastercard network.
export const EndpointCard = ({method = "API", title, children, href, arrow = true}) => {
const METHOD_STYLES = {
GET: {
bg: "mint-bg-green-400/20 dark:mint-bg-green-400/20",
text: "mint-text-green-700 dark:mint-text-green-400",
border: "mint-border-green-300 dark:mint-border-green-700"
},
POST: {
bg: "mint-bg-blue-400/20 dark:mint-bg-blue-400/20",
text: "mint-text-blue-700 dark:mint-text-blue-400"
},
PUT: {
bg: "mint-bg-yellow-400/20 dark:mint-bg-yellow-400/20",
text: "mint-text-yellow-700 dark:mint-text-yellow-400"
},
PATCH: {
bg: "mint-bg-orange-400/20 dark:mint-bg-orange-400/20",
text: "mint-text-orange-700 dark:mint-text-orange-400"
},
DELETE: {
bg: "mint-bg-red-400/20 dark:mint-bg-red-400/20",
text: "mint-text-red-700 dark:mint-text-red-400"
},
API: {
bg: "mint-bg-black",
text: "mint-text-white"
}
};
const MethodBadge = ({method}) => {
const style = METHOD_STYLES[method?.toUpperCase()] ?? METHOD_STYLES.GET;
return
{method?.toUpperCase()}
;
};
const content =
{}
{}
{title}
{children &&
{children}
}
Create dispute case
**Action:** `POST`\
**Endpoint:** `/cases`
Create a new dispute case by specifying the type and including the type-specific details object.
Body field details
| Fields | Description |
| ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| token
string
Optional | The unique identifier of the dispute case.
If you do not include a token, the system generates a token automatically. Because this token is necessary for use in other API calls, it is recommended that, rather than let the system generate the token, you use a simple string that is easy to remember. This value cannot be updated.
**Allowable Values:**
36 char max |
| type
string
Required | The type of case.
**Allowable Values:**
`DISPUTE` |
| memo
string
Optional | Free-form comments about the dispute.
**Allowable Values:**
512 char max |
| dispute\_details
object
Required | The reason for the dispute.
**Allowable Values:**
See The dispute\_details object table. |
The dispute\_details object
Include this object in your request if the case type is `DISPUTE`.
| Fields | Description |
| ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| original\_transaction\_token
string
Required | The token of the original transaction under dispute.
**Allowable Values:**
36 char max |
| 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 Message | Reason Code |
| ------------------------------------------------------------------------------ | -------------------------------------- |
| **Authorization-related disputes** | |
| Required authorization not obtained | `NO_AUTHORIZATION` |
| Expired authorization protection period | `NO_AUTHORIZATION` |
| Multiple authorization requests | `NO_AUTHORIZATION` |
| Late presentment | `NO_AUTHORIZATION` |
|
**Cardholder disputes** | |
| Goods or services were either not as described or defective | `CARDHOLDER_DISPUTE` |
| Goods or services not provided | `CARDHOLDER_DISPUTE` |
| Credit not processed | `CREDIT_NOT_PROCESSED` |
| Counterfeit goods | `CARDHOLDER_DISPUTE` |
| Recurring transaction | `CANCELLED_RECURRING_TRANSACTION` |
| No-show hotel charge | `CARDHOLDER_DISPUTE` |
| Credit posted as a purchase | `CARDHOLDER_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 charge | `POINT_OF_INTERACTION_ERRORS` |
| Paid by other means | `POINT_OF_INTERACTION_ERRORS` |
| Transaction amount differs | `POINT_OF_INTERACTION_ERRORS` |
| ATM disputes | `POINT_OF_INTERACTION_ERRORS` |
| Currency errors | `POINT_OF_INTERACTION_ERRORS` |
Response body
| Fields | Description |
| ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| token
string
Returned | The unique identifier of the dispute case.
**Allowable Values:**
36 char max |
| type
string
Returned | The type of case.
**Allowable Values:**
`DISPUTE` |
| memo
string
Returned | Free-form comments about the dispute.
**Allowable Values:**
512 char max |
| program\_short\_code
string
Returned | Indicates what program the case belongs to.
**Allowable Values:**
10 char max |
| user\_token
string
Returned | Token that identifiers the user that made the original transaction.
**Allowable Values:**
36 char max |
| business\_token
string
Returned | the token of the business involved in the dispute case.
**Allowable Values:**
36 char max |
| state
string
Returned | Indicates the current case state.
**Allowable Values:**
`OPEN`, `OPEN_WITH_ACTION_REQUIRED`, `READY`, `CHARGEBACK_INITIATED`, `CLOSED` |
| assignee
string
Returned | Indicates who is working on the case. This is updated by the case transition endpoint with reason\_code 22 and ASSIGN action.
**Allowable Values:**
255 char max |
| zendesk\_ticket\_id
string
Optional | ID for the Zendesk ticket.
**Allowable Values:**
255 char max |
| type\_change\_time
datetime
Optional | When the type was changed.
**Allowable Values:**
Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ |
| dispute\_details
object
Returned | The details of the dispute case.
**Allowable Values:**
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 JSON lines wrap theme={null}
{
"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 JSON expandable lines wrap theme={null}
{
"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
| Fields | Description |
| ------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| token
string
Required | The token of the dispute case to retrieve.
**Allowable Values:**
36 char max |
Query parameter
| Fields | Description |
| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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
| Fields | Description |
| ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| token
string
Returned | The unique identifier of the dispute case.
**Allowable Values:**
36 char max |
| type
string
Returned | The type of case.
**Allowable Values:**
`DISPUTE` |
| memo
string
Returned | Free-form comments about the dispute.
**Allowable Values:**
512 char max |
| 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 JSON expandable lines wrap theme={null}
{
"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](/core-api/sorting-and-pagination/).
Query parameters
| Fields | Description |
| ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 3ds
boolean
Optional | Returns dispute cases that involve 3DS.
**Allowable Values:**
`true`, `false` |
| assignee
string
Optional | Returns dispute cases associated with the specified assignee.
**Allowable Values:**
255 char max |
| chargeback\_token
string
Optional | Returns dispute cases associated with the specified chargeback.
**Allowable Values:**
36 char max |
| dispute\_state
array of strings
Optional | Returns a comma-separated list of dispute states that will be used to filter the resulting case.
**Allowable Values:**
`INITIATED`, `REPRESENTMENT`, `PRE_ARBITRATION`, `ARBITRATION`, `CASE_WON`, `CASE_LOST`, `NETWORK_REJECTED`, `CLOSED`, `WRITTEN_OFF_ISSUER`, `WRITTEN_OFF_PROGRAM` |
| network\_case\_number
string
Optional | Returns dispute cases associated with the specified network case number.
**Allowable Values:**
A valid network case number. |
| next\_actor
string
Optional | Returns the dispute cases associated with the specified next actor, such as `ISSUER`, `ACQUIRER`, `COURT`, or `DISPUTE_COMPLETED`.
**Allowable Values:**
An existing next actor. |
| original\_transaction\_token
string
Optional | Returns dispute cases associated with the specified token.
**Allowable Values:**
36 char max |
| reason
string
Optional | Returns disputes that are using the provided dispute reason.
**Allowable Values:**
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
| Fields | Description |
| ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| token
string
Returned | The unique identifier of the dispute case.
**Allowable Values:**
36 char max |
| type
string
Returned | The type of case.
**Allowable Values:**
`DISPUTE` |
| memo
string
Returned | Free-form comments about the dispute.
**Allowable Values:**
512 char max |
| 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
| Fields | Description |
| ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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
| Fields | Description |
| ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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 JSON expandable lines wrap theme={null}
{
"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
| 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 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 the uploading case documents, see Create dispute case content.
**Allowable Values:**
A list of valid UUID tokens. |
Dispute case transitions
Dispute case transitions represent the workflow during the creation, information gathering, and submission process of a dispute case. The dispute case transition actions and resulting states are described below.
| Action | 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 `provisionalCreditGranted` is set 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`, `OPEN_WITH_ACTION_REQUIRED` | Sends a `POST` request to the `\cases` endpoint with `credit_user` set to `true`. Set `reason_description` as the value of `dispute_reason` and `channel` as `ISSUER_AUTOMATED` when creating the chargeback.
Dispute case state changes to `CHARGEBACK_INITIATED` if no additional information is required. The `OPEN_WITH_ACTION_REQUIRED` state results if additional information is needed from the user before the chargeback can be submitted to the network.
Only for programs that are not enabled for Regulation E. |
| CHARGEBACK\_NO\_CREDIT | 29 | `CHARGEBACK_INITIATED`, `OPEN_WITH_ACTION_REQUIRED` | Sends a `POST` request to the `\cases` endpoint with `credit_user` set to `false`. Set `reason_description` as the value of `dispute_reason` and `channel` as `ISSUER_AUTOMATED` when creating the chargeback.
Dispute case state changes to `CHARGEBACK_INITIATED` if no additional information is required. The `OPEN_WITH_ACTION_REQUIRED` state results if additional information is needed from the user before the chargeback can be submitted to the network.
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. |
| 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. |
| WITHDRAW\_AND\_CLOSE | 40 | `CLOSED` | No further action is needed, closing the case by withdrawing. |
| WRITE\_OFF | N/A | `WRITE_OFF_PROGRAM` | 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. |
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` |
| 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 with provisional credit to the cardholder.
Only for programs that are not enabled for Regulation E. | `CHARGEBACK_CREDIT` |
| 29 | A chargeback was created with no provisional credit to the cardholder.
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 initiation 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` |
| 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 to 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. | |
| 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 | The 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` |
| 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 JSON lines wrap theme={null}
{
"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 JSON lines wrap theme={null}
{
"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 JSON lines wrap theme={null}
{
"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 JSON lines wrap theme={null}
{
"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 JSON lines wrap theme={null}
{
"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 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 been 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 provision credit has not occurred.
Solution: Wait for the provisional credit to be reversed. |
Sample response body (TRANSITION FAILURE RESPONSE)
```json JSON lines wrap theme={null}
{
"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
| Fields | Description |
| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| token
string
Required | The token of the dispute case associated with the transitions you want to retrieve.
**Allowable Values:**
36 char max
Send a `GET` request to `/cases` to retrieve dispute case tokens. |
| transition\_token
string
Required | The token of the transition to retrieve.
**Allowable Values:**
36 char max
Send a `GET` request to `/cases/{token}/transitions` to retrieve dispute case transition tokens. |
Retrieve dispute case transition response
See [Dispute transition response](#_dispute_transition_response).
Sample response body
```json JSON lines wrap theme={null}
{
"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](/core-api/sorting-and-pagination/).
URL path parameters
| Fields | Description |
| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| token
string
Required | The token of the dispute case associated with the transitions you want to list.
**Allowable Values:**
36 char max
Send a `GET` request to `/cases` to retrieve dispute case tokens. |
Query parameters
| Fields | Description |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| state
string
Optional | Filter dispute case transitions that 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](#_dispute_transition_response).
Sample response body
```json JSON expandable lines wrap theme={null}
{
"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
| Fields | Description |
| ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| token
string
Required | The token of the dispute associated with the transition you want to create.
**Allowable Values:**
36 char max
Submit a `GET` request to `/cases` to retrieve case tokens. |
Request body
| Fields | Description |
| -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| action
string
Required | The action to take:
- `RESPOND_WITH_PREARB:` Action to move a dispute to prearbitration with Visa.
- `RESPOND_WITH_ARB:` Action to move a prearbitration disputes to arbitration.
- `RESPOND_WITH_PREARB_RESPONSE`: Respond to the prearbitration response.
- `ACCEPT_AND_CLOSE:` Action to accept the dispute decision and close the dispute.
- `CLOSE_WITH_CASE_WON`: Close with case won dispute transition.
- `CLOSE_WITH_NETWORK_REJECTED`: Close with network rejected.
- `REPRESENTMENT_RECEIVED`: Indicates that representment was received.
**Allowable Values:**
`RESPOND_WITH_PREARB`, `RESPOND_WITH_ARB`, `RESPOND_WITH_PREARB_RESPONSE`, `ACCEPT_AND_CLOSE`, `CLOSE_WITH_CASE_WON`, `CLOSE_WITH_NETWORK_REJECTED`, `REPRESENTMENT_RECEIVED` |
| created\_by
string
Optional | The user who is creating the transition.
**Allowable Values:**
255 char max |
| memo
string
Optional | A memo regarding the transaction.
**Allowable Values:**
16777215 char max |
| network\_details
object
Conditionally required | The network details.
**Allowable Values:**
See The network\_details object table. |
The network\_details object
Depending on the transition, contains the `prearbitration_details` object or the `arbitration_details` object.
| Fields | Description |
| ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| prearbitration\_details
object
Optional | Object defining the prearbitration details.
**Allowable Values:**
See The prearbitration\_details object table. |
| prearbitration\_response\_details
object
Optional | Object defining the prearbitration response details.
**Allowable Values:**
See The prearbitration\_response\_details object table. |
| arbitration\_details
object
Optional | Object defining the arbitration details.
**Allowable Values:**
See The arbitration\_details object table. |
| representment\_details
object
Optional | Object defining the 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.
| Fields | Description |
| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| amount
number
Required | The amount in dispute.
**Allowable Values:**
32 bytes |
| attached\_contents
string
Optional | Content token for documents to be submitted to the network at the current dispute state.
**Allowable Values:**
256 char max |
| filed\_against\_ica
string
Required | Filing ICA of the acquirer/merchant.
**Allowable Values:**
256 char max |
| filing\_ica
string
Required | Filing ICA of the issuer.
**Allowable Values:**
256 char max |
| network\_memo
string
Optional | Memo from the network pertaining to the dispute case.
**Allowable Values:**
256 char max |
| merchant\_name
string
Optional | The merchant name.
**Allowable Values:**
22 char max |
The prearbitration\_response\_details object
The details for prearbitration response.
| Fields | Description |
| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| attached\_contents
string
Optional | Content token for documents to be submitted to the network at the current dispute state.
**Allowable Values:**
256 char max |
The arbitration\_details object
The details for arbitration.
| Fields | Description |
| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| attached\_contents
string
Optional | Content token for documents to be submitted to the network at the current dispute state.
**Allowable Values:**
256 char max |
The representment\_details object
The details for representment transition.
| Fields | Description |
| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| amount
number
Required | The amount in dispute.
**Allowable Values:**
Min: 0.1 |
| attached\_contents
string
Optional | Content token for documents to be submitted to the network at the current dispute state.
**Allowable Values:**
256 char max |
The case\_close\_details object
The details for case close transition details.
| Fields | Description |
| ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| write\_off
boolean
Optional | Indicates whether the write-off due to the case lost happened.
**Allowable Values:**
`true`, `false` |
| write\_off\_actor
string
Optional | The actor who performed the write-off.
**Allowable Values:**
`PROGRAM`, `ISSUER` |
Network dispute transition response body
| Fields | Description |
| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| token
string
Returned | The unique identifier of the dispute transition.
**Allowable Values:**
36 char max |
| created\_time
datetime
Returned | The date and time 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.
| Fields | Description |
| ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| prearbitration\_details
object
Optional | Object defining the prearbitration details.
**Allowable Values:**
See The prearbitration\_details object table. |
| prearbitration\_response\_details
object
Optional | Object defining the prearbitration response details.
**Allowable Values:**
See The prearbitration\_response\_details object table. |
| arbitration\_details
object
Optional | Object defining the arbitration details.
**Allowable Values:**
See The arbitration\_details object table. |
| representment\_details
object
Optional | Object defining the 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 JSON expandable lines wrap theme={null}
{
"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 JSON expandable lines wrap theme={null}
{
"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 JSON expandable lines wrap theme={null}
{
"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 JSON expandable lines wrap theme={null}
{
"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 JSON expandable lines wrap theme={null}
{
"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 JSON expandable lines wrap theme={null}
{
"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 JSON expandable lines wrap theme={null}
{
"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 JSON expandable lines wrap theme={null}
{
"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
| Fields | Description |
| ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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](#_network_dispute_transition_response_body) table.
Error codes
| Error Code | Error Message | Description |
| ---------- | -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| 400301 | Case is RegE and can only be accepted and closed with write off after it expires | Triggered 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 JSON lines wrap theme={null}
{
"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 JSON lines wrap theme={null}
{
"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 JSON lines wrap theme={null}
{
"action": "CLOSE_WITH_CASE_WON",
"created_by": "string",
"memo": "string"
}
```
Sample CLOSE\_WITH\_CASE\_WON transition response
```json JSON lines wrap theme={null}
{
"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
| Fields | Description |
| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| transition\_token
string
Required | The token of the transition to retrieve.
**Allowable Values:**
36 char max
Send a `GET` request to `/cases/{token}/transitions` to retrieve dispute case transition tokens. |
Response fields
See the [Network dispute transition response](#_network_dispute_transition_response_body) table.
Sample response body
```json JSON expandable lines wrap theme={null}
{
"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](/core-api/sorting-and-pagination/).
URL path parameters
| Fields | Description |
| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| token
string
Required | The token of the dispute case associated with the transitions you want to list.
**Allowable Values:**
36 char max
Send a `GET` request to `/cases` to retrieve dispute case tokens. |
List network dispute transitions response fields
See the [Network dispute transition response](#_network_dispute_transition_response_body) table.
Sample response body
```json JSON expandable lines wrap theme={null}
{
"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
| Fields | Description |
| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| token
string
Required | The token that identifies the dispute case.
**Allowable Values:**
36 char max
Send a `GET` request to `/cases` to retrieve dispute case tokens. |
Request body
| Fields | Description |
| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| document\_category
string
Required | The category of the document.
**Allowable Values:**
`AFFIDAVIT_FRAUD`, `AUTHORIZATION_RECORD`, `BANK_STATEMENT`, `CANCELLED_CHECK`, `CARDHOLDER_LETTER`, `CREDIT_VOUCHER`, `FULFILLMENT`, `ISSUER_CERTIFICATION`, `MERCHANT_LETTER`, `NETWORK_DOCUMENT`, `NETWORK_EXHIBIT`, `OTHERS`, `RECEIPT`, `SALES_DRAFT`, `SECOND_OPTION`, `UPDATED_CARDHOLDER_LETTER`, `UPDATED_MERCHANT_LETTER` |
| document\_name
string
Required | The name for the document. Must include the 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
| Fields | Description |
| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| token
string
Returned | The token identifying the document.
**Allowable Values:**
36 char max |
| case\_token
string
Returned | The token identifying the dispute case you want to upload documents against.
**Allowable Values:**
36 char max |
| document\_name
string
Returned | The name of the document.
**Allowable Values:**
255 char max |
| document\_category
string
Returned | The type of document.
**Allowable Values:**
`AFFIDAVIT_FRAUD`, `AUTHORIZATION_RECORD`, `BANK_STATEMENT`, `CANCELLED_CHECK`, `CARDHOLDER_LETTER`, `CREDIT_VOUCHER`, `FULFILLMENT`, `ISSUER_CERTIFICATION`, `MERCHANT_LETTER`, `NETWORK_DOCUMENT`, `NETWORK_EXHIBIT`, `OTHERS`, `RECEIPT`, `SALES_DRAFT`, `SECOND_OPTION`, `UPDATED_CARDHOLDER_LETTER`, `UPDATED_MERCHANT_LETTER` |
| document\_content\_type
string
Returned | The content type of the document.
**Allowable Values:**
`application/pdf`, `image/tiff`, `image/jpeg` |
| network\_processing\_type
string
Returned | Indicates the current status of the document at the network:
`SUBMITTED` – Indicates it has been submitted to the network using the Dispute Case Transition or Network Dispute Transition endpoint.
`RECEIVED` – Indicates that the document has been downloaded from the network, which occurs when the acquirer uploaded a document to support their claim.
**Allowable Values:**
`SUBMITTED`, `RECEIVED` |
| network\_processing\_phase
string
Returned | Indicates the status of the document in the dispute lifecycle.
**Allowable Values:**
`INITIATED`, `REPRESENTMENT`, `PRE_ARBITRATION` |
| network\_processing\_time
datetime
Returned | The date and time when the document has either been submitted by the user or received from the network.
**Allowable Values:**
Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ |
| created\_time
datetime
Returned | The date and time when 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 JSON lines wrap theme={null}
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 JSON lines wrap theme={null}
{
"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
| Fields | Description |
| ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| token
string
Required | The token that identifies the dispute case for which to return the contents list.
**Allowable Values:**
36 char max
Send a `GET` request to `/cases` to retrieve dispute case tokens. |
List contents response
For response details, see [Create content response body](#_create_content_response_body).
Sample response body
```json JSON expandable lines wrap theme={null}
{
"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
| Fields | Description |
| ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| case\_token
string
Required | The token that identifies the dispute case for which to return the contents list.
**Allowable Values:**
36 char max
Send a `GET` request to `/cases` to retrieve dispute case tokens. |
| token
string
Required | The token that identifies the document.
**Allowable Values:**
36 char max |
| download\_link
string
Optional | If set to `true`, this parameter causes a download link for the document to be included in the response.
**Allowable Values:**
`true`, `false` |
Response body
For response details, see [Create content response body](#_create_content_response_body).
Sample response body
```json JSON lines wrap theme={null}
{
"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
| Fields | Description |
| ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| token
string
Required | The token that identifies the dispute case for which to return the contents list.
**Allowable Values:**
36 char max
Send a `GET` request to `/cases` to retrieve dispute case tokens. |
| content\_token
string
Required | The content token that identifies the document.
**Allowable Values:**
36 char max |
Body field details
| Fields | Description |
| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| document\_name
string
Required | The name for the document.
**Allowable Values:**
255 char max |
| document\_category
string
Required | The category of the document.
**Allowable Values:**
`AFFIDAVIT_FRAUD`, `AUTHORIZATION_RECORD`, `BANK_STATEMENT`, `CANCELLED_CHECK`, `CARDHOLDER_LETTER`, `CREDIT_VOUCHER`, `FULFILLMENT`, `ISSUER_CERTIFICATION`, `MERCHANT_LETTER`, `NETWORK_DOCUMENT`, `NETWORK_EXHIBIT`, `OTHERS`, `RECEIPT`, `SALES_DRAFT`, `SECOND_OPTION`, `UPDATED_CARDHOLDER_LETTER`, `UPDATED_MERCHANT_LETTER` |
Update document response body
For response details, see [Create content response body](#_create_content_response_body).
Sample request body
```json JSON lines wrap theme={null}
{
"document_name": "receipt.pdf",
"document_category": "RECEIPT"
}
```
Sample response body
```json JSON lines wrap theme={null}
{
"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
| Fields | Description |
| ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| token
string
Required | The token that identifies the dispute case.
**Allowable Values:**
36 char max |
| content\_token
string
Required | The token that identifies the content to delete. This token is generated for the document when it is created.
**Allowable Values:**
36 char max |
Delete content response
This endpoint returns a `200` response code and `success` in the response body.
Sample response body
```json JSON lines wrap theme={null}
{
"status": "success"
}
```
Create dispute case action
**Action:** `POST`\
**Endpoint:** `/cases/{token}/actions`
Create a dispute case action.
Path parameter
| Fields | Description |
| ------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| token
string
Required | The token that identifies the dispute case.
**Allowable Values:**
36 char max |
Body field details
| Fields | Description |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| 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
| Fields | Description |
| -------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| 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 JSON lines wrap theme={null}
{
"action_type": "GRANT_PROVISIONAL_CREDIT",
"created_by": "string"
}
```
Sample response
```json JSON lines wrap theme={null}
{
"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](/core-api/disputes-evidence-collection/).
Path parameter
| Fields | Description |
| ------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| token
string
Required | The token that identifies the dispute case.
**Allowable Values:**
36 char max |
Body field details
| Fields | Description |
| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| 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
| Fields | Description |
| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| 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 JSON lines wrap theme={null}
{
"name": "string",
"created_by": "string",
"event_date": "timestamp",
}
}
```
Sample response
```json JSON lines wrap theme={null}
{
"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
| Fields | Description |
| ------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| token
string
Required | The token that identifies the dispute case.
**Allowable Values:**
36 char max |
Body field details
| Fields | Description |
| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| 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
| Fields | Description |
| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| 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 JSON lines wrap theme={null}
{
"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
| Fields | Description |
| ------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| token
string
Required | The token that identifies the dispute case.
**Allowable Values:**
36 char max |
Body field details
| Fields | Description |
| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| 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
| Fields | Description |
| ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
| 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 JSON lines wrap theme={null}
{
"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 Disputes](/docs/developer-guides/managing-mastercard-disputes.md)
- [Disputes Overview](/docs/developer-guides/disputes-landing-page.md)
- [About Disputes](/docs/developer-guides/about-disputes.md)
- [2021 Release Notes](/docs/developer-guides/release-notes-2021.md)
- [Release Notes](/docs/developer-guides/release-notes.md)