Disputes (Mastercard) (Beta)
Note
This feature is currently in beta and subject to change. It also requires additional activation steps. To learn more about the Beta program for this feature and about activating it for your program, contact your Marqeta representative.Use the /cases endpoint to manage transaction disputes on the Mastercard network.
For specific details on how to integrate with the Mastercard network, see Managing Mastercard Disputes. For general information on disputes, chargebacks, and best practices, see About Disputes.
Create dispute case
Copy section link
Action: POST
Endpoint: /cases
Create a new dispute case by specifying the type and including the type-specific details object.
Body field details
Copy section link
| Fields | Description |
|---|---|
token
string
|
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
|
The type of case. Allowable Values:
|
memo
string
|
Free-form comments about the dispute. Allowable Values: 512 char max |
zendesk_ticket_id
string
|
ID for the Zendesk ticket. Allowable Values: 255 char max |
dispute_details
object
|
The reason for the dispute. Allowable Values: See The dispute_details object table. |
The dispute_details object
Copy section link
Include this object in your request if the case type is DISPUTE.
| Fields | Description |
|---|---|
original_transaction_token
string
|
The token of the original transaction under dispute. Allowable Values: 36 char max |
original_transaction_id
integer
|
The ID of the original transaction under dispute. Allowable Values: 36 char max |
dispute_amount
number
|
The amount of funds under dispute. Allowable Values: Must be less than or equal to the original transaction amount. |
dispute_amount_change_reason
string
|
The reason the dispute amount has been changed from the transaction amount. Allowable Values:
Required if |
currency_code
string
|
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
|
The code describing the reason for the dispute. Allowable Values: See Dispute case reasons. |
cardholder_contact_date
datetime
|
The contact date of the cardholder. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ |
Dispute case reasons
Copy section link
The following are the possible dispute reasons for a case and the equivalent Mastercard reasons and reason codes.
| Dispute Reason | Mastercard Reason and Code |
|---|---|
ACCOUNT_NUMBER_NOT_ON_FILE |
Account Number No on File |
AUTHORIZATION_RELATED_FOR_DUAL_MESSAGE_ SYSTEM |
Authorization-related Chargeback |
CANCELLED_RECURRING_TRANSACTION |
Cancelled Recurring and Digital Goods Transactions |
CARDHOLDER_DISPUTE |
Cardholder Dispute |
CARDHOLDER_DISPUTE_US_ONLY |
Cardholder Dispute. Not Elsewhere Classified (U.S. Region Only) |
CHIP_LIABILITY_SHIFT |
Chip Liability Shift |
CHIP_PIN_LIABILITY_SHIFT_LOST_STOLEN |
Chip Liability Shift – Lost/Stolen/Never Received Issue (NRI) Fraud |
CHIP_READ_POS_LATE_PRESENTMENT |
Chip Read POS Late Presentment |
CREDIT_NOT_PROCESSED |
Credit Not Processed |
DOMESTIC_CHARGEBACK_INTRA_EUROPEAN_USE |
Domestic Chargeback Dispute Reserved for intra-European Use |
INCORRECT_CURRENCY, INCORRECT_TRANSACTION_CODE, INCORRECT_CURRENCY_OR_TRANSACTION_CODE |
Correct Transaction Currency Code Not Provided |
INCORRECT_TRANSACTION_AMOUNT_OR_ACCOUNT_NUMBER |
Transaction Amount Differs |
INSTALLMENT_BILLING_DISPUTE |
Installment Billing Dispute |
LATE_PRESENTMENT |
Late Presentment |
NO_AUTHORIZATION |
Cardholder claims that they did not authorize or participate in the transaction |
NO_SHOW_ADDENDUM_OR_ATM_DISPUTE |
No-show, Addendum, or ATM Dispute |
NON_RECEIPT_OF_CASH_OR_LOAD_TRANSACTION_VALUE_AT_ATM |
The cardholder disputes a charge that they are not responsible for the transaction in question |
NOT_AUTHORIZED_CARD_PRESENT, NOT_AUTHORIZED_CARD_ABSENT |
No Cardholder Authorization |
NOT_AS_DESCRIBED_OR_DEFECTIVE_MERCHANDISE |
Goods or services damaged or defective, Counterfeit goods |
POINT_OF_INTERACTION_ERRORS |
Point of Interaction Error |
QUESTIONABLE_MERCHANT_ACTIVITY |
Questionable Merchant Activity |
SERVICE_NOT_PROVIDED_MERCHANDISE_NOT_ RECEIVED |
Goods or Services Not Provided |
WARNING_BULLETIN_FILE |
Warning Bulletin File |
Response body
Copy section link
| Fields | Description |
|---|---|
token
string
|
The unique identifier of the dispute case. Allowable Values: 36 char max |
type
string
|
The type of case. Allowable Values:
|
memo
string
|
Free-form comments about the dispute. Allowable Values: 512 char max |
program_short_code
string
|
Indicates what program the case belongs to. Allowable Values: 10 char max |
user_token
string
|
Token that identifiers the user that made the original transaction. Allowable Values: 36 char max |
business_token
string
|
the token of the business involved in the dispute case. Allowable Values: 36 char max |
state
string
|
Indicates the current case state. Allowable Values:
|
assignee
string
|
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
|
ID for the Zendesk ticket. Allowable Values: 255 char max |
type_change_time
datetime
|
When the type was changed. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ |
dispute_details
object
|
The details of the dispute case. Allowable Values: See The dispute_details_response object table. |
created_time
datetime
|
The time that the dispute case was created. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ |
updated_time
datetime
|
The time that the dispute case was last updated. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ |
Retrieve dispute case
Copy section link
Action: GET
Endpoint: /cases/{token}
Retrieve a specific dispute case.
URL path parameters
Copy section link
| Fields | Description |
|---|---|
token
string
|
The token of the dispute case to retrieve. Allowable Values: 36 char max |
Response body
Copy section link
| Fields | Description |
|---|---|
token
string
|
The unique identifier of the dispute case. Allowable Values: 36 char max |
type
string
|
The type of case. Allowable Values:
|
memo
string
|
Free-form comments about the dispute. Allowable Values: 512 char max |
program_short_code
string
|
Indicates what program the case belongs to. Allowable Values: 10 char max |
user_token
string
|
Token that identifiers the user that made the original transaction. Allowable Values: 36 char max |
business_token
string
|
the token of the business involved in the dispute case. Allowable Values: 36 char max |
state
string
|
Indicates the current case state. Allowable Values:
|
assignee
string
|
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
|
ID for the Zendesk ticket. Allowable Values: 255 char max |
type_change_time
datetime
|
When the type was changed. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ |
dispute_details
object
|
The details of the dispute case. Allowable Values: See The dispute_details_response object table. |
created_time
datetime
|
The time that the dispute case was created. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ |
updated_time
datetime
|
The time that the dispute case was last updated. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ |
List dispute cases
Copy section link
Action: GET
Endpoint: /cases
List existing dispute cases. This endpoint supports sorting and pagination.
Query parameters
Copy section link
| Fields | Description |
|---|---|
3ds
boolean
|
Returns dispute cases that involve 3DS. Allowable Values:
|
assignee
string
|
Returns dispute cases associated with the specified assignee. Allowable Values: 255 char max |
chargeback_token
string
|
Returns dispute cases associated with the specified chargeback. Allowable Values: 36 char max |
dispute_state
array of strings
|
Returns a comma-separated list of dispute states that will be used to filter the resulting case. Allowable Values:
|
network_case_number
string
|
Returns dispute cases associated with the specified network case number. Allowable Values: A valid network case number. |
next_actor
string
|
Returns the dispute cases associated with the specified next actor, such as Allowable Values: An existing next actor. |
original_transaction_token
string
|
Returns dispute cases associated with the specified token. Allowable Values: 36 char max |
reason
string
|
Returns disputes that are using the provided dispute reason. Allowable Values: See Dispute case reasons. |
state
string
|
Returns a comma-separated list of case states that will be used to filter the resulting case. Allowable Values:
|
type
string
|
Returns cases of the specified type. Allowable Values:
|
user_token
string
|
Returns dispute cases associated with the specified user. Allowable Values: 36 char max |
Response body
Copy section link
| Fields | Description |
|---|---|
token
string
|
The unique identifier of the dispute case. Allowable Values: 36 char max |
type
string
|
The type of case. Allowable Values:
|
memo
string
|
Free-form comments about the dispute. Allowable Values: 512 char max |
program_short_code
string
|
Indicates what program the case belongs to. Allowable Values: 10 char max |
user_token
string
|
Token that identifiers the user that made the original transaction. Allowable Values: 36 char max |
business_token
string
|
the token of the business involved in the dispute case. Allowable Values: 36 char max |
state
string
|
Indicates the current case state. Allowable Values:
|
assignee
string
|
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
|
ID for the Zendesk ticket. Allowable Values: 255 char max |
type_change_time
datetime
|
When the type was changed. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ |
dispute_details
object
|
The details of the dispute case. Allowable Values: See The dispute_details_response object table. |
created_time
datetime
|
The time that the dispute case was created. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ |
updated_time
datetime
|
The time that the dispute case was last updated. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ |
The dispute_details_response object
Copy section link
| Fields | Description |
|---|---|
original_transaction_token
string
|
The token of the original transaction under dispute. Allowable Values: 36 char max |
original_transaction_id
integer
|
The ID of the original transaction under dispute. Allowable Values: Existing transaction ID. |
original_transaction_type
string
|
The type of the original transaction under dispute. Allowable Values: 255 char max |
dispute_amount
number
|
The amount of funds under dispute. Allowable Values: Must be less than or equal to the original transaction amount. |
dispute_amount_change_reason
string
|
The reason the dispute amount has been changed from the transaction amount. Allowable Values:
|
currency_code
string
|
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
|
The code describing the reason for the dispute. Allowable Values: See the Dispute case reasons table. |
dispute_state
string
|
The current dispute state. Allowable Values:
|
chargeback_token
string
|
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 Allowable Values: 36 char max |
network
string
|
The network where the transaction took place. Allowable Values:
|
acquirer_fee
number
|
The acquirer fee for the transaction. Allowable Values: A valid number. |
associated_transaction_selection_
required
boolean
|
Indicates whether there are any transactions related to the original transaction. Allowable Values:
|
card_token
string
|
Unique identifier that maps back to the card that made the original transaction. Allowable Values: 36 char max |
network_failure_response
string
|
Indicates the latest error that has occurred while the case is processed. Allowable Values: 255 char max |
cardholder_contact_date
datetime
|
The contact date of the cardholder. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ |
provisional_credit_granted
boolean
|
Indicates whether the provisilal credit was granted. Allowable Values:
|
regulation_type
string
|
The regulation type of the disputer case. Allowable Values: 255 char max |
Create dispute case transition
Copy section link
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
Copy section link
| Fields | Description |
|---|---|
token
string
|
The token of the dispute case associated with the transition you want to create. Allowable Values: 36 char max Send a |
Body field details
Copy section link
| Fields | Description |
|---|---|
token
string
|
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
|
The action taken on the dispute case. Allowable Values: |
reason_code
string
|
Identifies the standardized reason for the transition. Allowable Values: See The reason_code field table. |
created_by
string
|
The user ID or name of the user who created the transition. Allowable Values: 255 char max |
assignee
string
|
The user ID or name of the user assigned to the case. Allowable Values: 255 char max |
memo
string
|
Additional notes about the transition. Allowable Values: 16777215 char max |
transition_details
object
|
An object containing the transition details. Allowable Values: |
The transition_details object
Copy section link
| Fields | Description |
|---|---|
chargeback_details
object
|
An object containing the chargeback details. Allowable Values: |
The chargeback_details object
Copy section link
| Fields | Description |
|---|---|
attached_contents
string
|
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
Copy section link
Dispute case transitions represent the workflow during the creation, information gathering, and submission process of a dispute case. The dispute case transition actions and resulting states are described below.
| Action | Resulting State | Description |
|---|---|---|
CREATE |
|
Creates a new dispute case.
A default action when a |
RE_OPEN |
|
Reopens a dispute case to get additional information or documents.
Dispute case state changes to |
NON_CHARGEBACK_CREDIT |
|
Smaller amount, no chargeback needed. |
CHARGEBACK_CREDIT |
|
Sends a Dispute case state changes to |
CHARGEBACK_NO_CREDIT |
|
Sends a Dispute case state changes to |
CHARGEBACK_SUBMIT |
|
Submitting dispute to the network. |
REVIEW |
|
Dispute case is ready to review.
Dispute case state changes to |
ASSIGN |
No change |
Assigns a dispute case to a user.
An |
KYC_OVERRIDE |
|
Documents are verified and the case is being closed. |
CLOSE |
|
Closes the dispute case.
Dispute case state changes to |
DOCUMENTS_DELETED |
No change |
Invalid documents were uploaded, documents are not in readable format or quality, or documents are corrupted and not human readable. |
REINSTATE_USER |
|
Failed to reinstate the user. |
REINSTATE_BUSINESS |
|
Failed to reinstate the business. |
WITHDRAW_AND_CLOSE |
|
No further action is needed, closing the case by withdrawing. |
WRITE_OFF |
No change |
Written off either by user or program. |
GRANT_CREDIT |
No change |
Granting provisional credit. |
REVERT_CREDIT |
No change |
Reverting provisional credit. |
CHANGE_CASE_TYPE |
No change |
Change case from |
The reason_code field
Copy section link
| Reason Code | Description | Related Actions |
|---|---|---|
00 |
The dispute case was created. |
|
01 |
The dispute case was created, but needs additional verification actions. |
|
05 |
The dispute case is under review. |
|
14 |
The Marqeta platform updated the dispute case. |
|
15 |
An update was initiated by the issuer. |
|
18 |
The user or business status was changed to |
|
19 |
The user or business status was changed to |
|
22 |
The dispute case was assigned to a user. |
|
23 |
The dispute case was reopened. |
|
24 |
The dispute case was reopened to gather more information. |
|
25 |
The documents were verified and the dispute case is being closed. |
|
26 |
The customer closed the dispute case. |
|
27 |
The dispute is for a smaller amount and no chargeback is needed. |
|
28 |
A chargeback was created with provisional credit to the cardholder. |
|
29 |
A chargeback was created with no provisional credit to the cardholder. |
|
30 |
The dispute case was closed automatically due to inactivity. |
|
31 |
Invalid documents were uploaded. |
|
32 |
Documents were uploaded that are unreadable because of incorrect format or poor quality. |
|
33 |
Corrupted documents were uploaded. |
|
34 |
The chargeback initiation failed. |
|
35 |
The chargeback failed at the card network. |
|
36 |
KYC override failed. |
|
37 |
User reinstatement failed. |
|
38 |
Business reinstatement failed. |
|
39 |
Associated transaction selection is required to ready this dispute case. |
|
40 |
No further action is needed. Closing the dispute case by withdrawing. |
|
41 |
The dispute case was won, accepted with favorable results. |
|
42 |
The dispute case was lost, accepted with unfavorable results. |
|
43 |
The dispute case was rejected by the network. |
|
44 |
The dispute case was written off by the issuer. |
|
45 |
The dispute cse was written off by the program. |
|
46 |
Provisional credit has been granted. |
|
47 |
Provisional credit has been reverted. |
|
48 |
A failure occurred when attempting to transition to the |
No change |
49 |
The dispute case was reported to the network as |
|
50 |
The dispute case was changed from |
|
51 |
The dispute case is being submitted to the network. |
|
52 |
Provisional credit is required for a Regulation E dispute case. |
|
53 |
Awaiting milestone. |
Dispute transition response
Copy section link
| Fields | Description |
|---|---|
case_token
string
|
The unique identifier of the dispute case. Allowable Values: 36 char max |
token
string
|
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
|
The action taken on the dispute case. Allowable Values: |
reason_code
string
|
Identifies the standardized reason for the transition. Allowable Values: See The reason_code field table. |
reason_description
string
|
A descriptive reason for the transition. Allowable Values: 36 char max |
created_by
string
|
The user ID or name of the user who created the transition. Allowable Values: 36 char max |
from_state
string
|
The state of the dispute case before the case transition was created. Allowable Values:
|
state
string
|
The resulting state of the dispute case after the transition was created. Allowable Values:
|
assignee
string
|
The user ID or name of the user assigned to the dispute case. Allowable Values: 255 char max |
memo
string
|
Additional notes about the transition. Allowable Values: 512 char max |
failure_reason
string
|
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
|
An object containing the transition details. Allowable Values: |
Retrieve dispute case transition
Copy section link
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
Copy section link
| Fields | Description |
|---|---|
token
string
|
The token of the dispute case associated with the transitions you want to retrieve. Allowable Values: 36 char max Send a |
transition_token
string
|
The token of the transition to retrieve. Allowable Values: 36 char max Send a |
Retrieve dispute case transition response
Copy section link
List dispute case transitions
Copy section link
Action: GET
Endpoint: /cases/{token}/transitions
List existing dispute case transitions for the specified dispute case. This endpoint supports sorting and pagination.
URL path parameters
Copy section link
| Fields | Description |
|---|---|
token
string
|
The token of the dispute case associated with the transitions you want to list. Allowable Values: 36 char max Send a |
Query parameters
Copy section link
| Fields | Description |
|---|---|
state
string
|
Filter dispute case transitions that contain the specified resulting state. Allowable Values:
|
List dispute case transition response
Copy section link
Create network dispute transition
Copy section link
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
Copy section link
| Fields | Description |
|---|---|
token
string
|
The token of the dispute associated with the transition you want to create. Allowable Values: 36 char max |
Request body
Copy section link
| Fields | Description |
|---|---|
action
string
|
The action to take:
Allowable Values:
|
created_by
string
|
The user who is creating the transition. Allowable Values: 255 char max |
memo
string
|
A memo regarding the transaction. Allowable Values: 16777215 char max |
network_details
object
|
The network details. Allowable Values: See The network_details object table. |
The network_details object
Copy section link
Depending on the transition, contains the prearbitration_details object or arbitration_details object.
| Fields | Description |
|---|---|
prearbitration_details
object
|
Object defining the prearbitration details. Allowable Values: See The prearbitration_details object table. |
prearbitration_response_details
object
|
Object defining the prearbitration response details. Allowable Values: See The prearbitration_response_details object table. |
arbitration_details
object
|
Object defining the arbitration details. Allowable Values: See The arbitration_details object table. |
representment_details
object
|
Object defining the network state details. Allowable Values: See The network_state_details object table. |
case_close_details
string
|
The new dispute state. Allowable Values: See The case_close_details object table. |
The prearbitration_details object
Copy section link
The details for prearbitration.
| Fields | Description |
|---|---|
amount
number
|
The amount in dispute. Allowable Values: 32 bytes |
attached_contents
string
|
Content token for documents to be submitted to the network at the current dispute state. Allowable Values: 256 char max |
filed_against_ica
string
|
Filing ICA of the acquirer/merchant. Allowable Values: 256 char max |
filing_ica
string
|
Filing ICA of the issuer. Allowable Values: 256 char max |
network_memo
string
|
Memo from the network pertaining to the dispute case. Allowable Values: 256 char max |
merchant_name
string
|
The merchant name. Allowable Values: 22 char max |
The prearbitration_response_details object
Copy section link
The details for prearbitration response.
| Fields | Description |
|---|---|
attached_contents
string
|
Content token for documents to be submitted to the network at the current dispute state. Allowable Values: 256 char max |
The arbitration_details object
Copy section link
The details for arbitration.
| Fields | Description |
|---|---|
attached_contents
string
|
Content token for documents to be submitted to the network at the current dispute state. Allowable Values: 256 char max |
The representment_details object
Copy section link
The details for representment transition.
| Fields | Description |
|---|---|
amount
number
|
The amount in dispute. Allowable Values: Min: 0.1 |
attached_contents
string
|
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
Copy section link
The details for case close transition details.
| Fields | Description |
|---|---|
write_off
boolean
|
Indicates whether the write-off due to the case lost happened. Allowable Values:
|
write_off_actor
string
|
The actor who performed the write-off. Allowable Values:
|
Network dispute transition response body
Copy section link
| Fields | Description |
|---|---|
token
string
|
The unique identifier of the dispute transition. Allowable Values: 36 char max |
created_time
datetime
|
The date and time that the transition was created. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ |
last_modified_time
datetime
|
The date and time that the transition was last modified. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ |
case_token
string
|
The token identifying the dispute case for the created the dispute transition. Allowable Values: 36 char max |
action
string
|
The action taken. Allowable Values:
|
created_by
string
|
The user ID or name of the user who created the transition. Allowable Values: 255 char max |
memo
string
|
A memo regarding the transaction. Allowable Values: 16777215 char max |
from_network_status
string
|
The network status before the transition. Allowable Values: 255 char max |
to_network_status
string
|
The new network status after the transition. Allowable Values: 255 char max |
network_dispute_id
string
|
The ID assigned to the dispute by the network. Allowable Values: 36 char max |
system_error_message
string
|
The error message for the system error. Allowable Values: 16777215 char max |
network_error_message
string
|
The error message for the network error. Allowable Values: 16777215 char max |
network_details
object
|
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
Copy section link
Depending on the transition, contains the prearbitration_details object or arbitration_details object.
| Fields | Description |
|---|---|
prearbitration_details
object
|
Object defining the prearbitration details. Allowable Values: See The prearbitration_details object table. |
prearbitration_response_details
object
|
Object defining the prearbitration response details. Allowable Values: See The prearbitration_response_details object table. |
arbitration_details
object
|
Object defining the arbitration details. Allowable Values: See The arbitration_details object table. |
representment_details
object
|
Object defining the network state details. Allowable Values: See The network_state_details object table. |
network_state_details
string
|
A JSON object, containing the details, received from the network. Allowable Values: 16777215 char max |
dispute_state
string
|
Once the case’s state has been moved to Allowable Values:
|
case_close_details
string
|
The new dispute state. Allowable Values: See The case_close_details object table. |
Retrieve network dispute transition
Copy section link
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
Copy section link
| Fields | Description |
|---|---|
transition_token
string
|
The token of the transition to retrieve. Allowable Values: 36 char max Send a |
Response fields
Copy section link
See the Network dispute transition response table.
List network dispute transitions
Copy section link
Action: GET
Endpoint: /cases/{token}/disputetransitions
List existing network dispute transitions for the specified dispute, including details of the merchant/acquirer responses during the backend resolution process. This endpoint supports sorting and pagination.
URL path parameters
Copy section link
| Fields | Description |
|---|---|
token
string
|
The token of the dispute case associated with the transitions you want to list. Allowable Values: 36 char max Send a |
List network dispute transitions response fields
Copy section link
See the Network dispute transition response table.
Create dispute case content
Copy section link
Action: POST
Endpoint: /cases/{token}/contents
Upload and store documents related to a dispute, such as evidence for dispute or KYC verification documents.
The supported document formats are pdf, tiff, jpeg, and zip. A zip file must contain a pdf, tiff, or jpeg file. Each uploaded file is restricted to 2 MB.
URL path parameter
Copy section link
| Fields | Description |
|---|---|
token
string
|
The token that identifies the dispute case. Allowable Values: 36 char max Send a |
Request body
Copy section link
| Fields | Description |
|---|---|
document_category
string
|
The category of the document. Allowable Values:
|
document_name
string
|
The name for the document. Must include the document extension as appropriate for a supported file format: pdf, tiff, or jpeg. Allowable Values: 255 char max |
document_data
binary
|
Base64-encoded file. Allowable Values: 2 MB max size |
Create content response body
Copy section link
| Fields | Description |
|---|---|
token
string
|
The token identifying the document. Allowable Values: 36 char max |
case_token
string
|
The token identifying the dispute case you want to upload documents against. Allowable Values: 36 char max |
document_name
string
|
The name of the document. Allowable Values: 255 char max |
document_category
string
|
The type of document. Allowable Values:
|
document_content_type
string
|
The content type of the document. Allowable Values:
|
network_processing_type
string
|
Indicates the current status of the document at the network:
Allowable Values:
|
network_processing_phase
string
|
Indicates the status of the document in the dispute lifecycle. Allowable Values:
|
network_processing_time
datetime
|
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
|
The date and time when dispute was created. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ |
updated_time
datetime
|
The date and time when dispute was last modified. Allowable Values: Format: yyyy-MM-dd’T’HH:mm:ss.SSSZ |
download_link
string
|
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. |
List contents uploaded against a case
Copy section link
Action: GET
Endpoint: /cases/{token}/contents
Get a list of uploaded contents for the specified dispute case.
URL path parameter
Copy section link
| Fields | Description |
|---|---|
token
string
|
The token that identifies the dispute case for which to return the contents list. Allowable Values: 36 char max Send a |
List contents response
Copy section link
For response details, see Create content response body.
Get content and status
Copy section link
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
Copy section link
| Fields | Description |
|---|---|
case_token
string
|
The token that identifies the dispute case for which to return the contents list. Allowable Values: 36 char max Send a |
token
string
|
The token that identifies the document. Allowable Values: 36 char max |
download_link
string
|
If set to Allowable Values:
|
Response body
Copy section link
For response details, see Create content response body.
Update document
Copy section link
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
Copy section link
| Fields | Description |
|---|---|
token
string
|
The token that identifies the dispute case for which to return the contents list. Allowable Values: 36 char max Send a |
content_token
string
|
The content token that identifies the document. Allowable Values: 36 char max |
Body field details
Copy section link
| Fields | Description |
|---|---|
document_name
string
|
The name for the document. Allowable Values: 255 char max |
document_category
string
|
The category of the document. Allowable Values:
|
Update document response body
Copy section link
For response details, see Create content response body.
Delete a document
Copy section link
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
Copy section link
| Fields | Description |
|---|---|
token
string
|
The token that identifies the dispute case. Allowable Values: 36 char max |
content_token
string
|
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
Copy section link
This endpoint returns a 200 response code and success in the response body.