POST///
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 dispute 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 theprearbitration_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 |
| why_are_you_initiating_prearbitration string Required | The reason you are initiating prearbitration. Allowable Values: |
| are_you_providing_new_information boolean Required | Indicates whether this state change includes new information useful for the dispute. Allowable Values: true, false |
| summary_of_new_information string Conditionally required. | A summary of the new information provided. Allowable Values: |
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 |
| prearbitration_response_decision string Required | The prearbitration response decision. Allowable Values: ACCEPT_PARTIAL, DECLINE |
| amount string Required | The partial acceptance amount. Allowable Values: 32 bytes |
| why_are_you_not_accepting_liability string Required | The reason you are not accepting liability. Allowable Values: |
| certify_that_you_have_contacted_cardholder_and_reviewed_the_compelling_evidence_with_them_and_cardholder_continues_dispute boolean Required | Indicates whether you have contacted the cardholder and reviewed the evidence and that the cardholder is continuing the dispute. Allowable Values: true, false |
| explanation_of_why_cardholder_continues_dispute string Required | A description of why the cardholder is continuing the dispute. Allowable Values: |
| certify_that_cardholder_name_and_address_provided_by_acquirer_does_not_match_issuer_records boolean Required | Indicates whether the cardholder’s name and address from the acquirer does not match issuer records. Allowable Values: true, false |
| explanation_of_why_you_are_continuing_the_dispute string Required | An explanation of why you are continuing the dispute. Allowable Values: |
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: 256 char max |
| memo string Conditionally returned | A memo regarding the transaction. Allowable Values: 16777215 char max |
| from_network_status string Conditionally returned | The network status before the transition. Allowable Values: 255 char max |
| to_network_status string Conditionally 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 Conditionally 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 theprearbitration_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: |
| dispute_state string Optional | Once the case’s state has been moved to CHARGEBACK_INITIATED, this field will be updated as it progresses in the backend lifecycle.Allowable Values: INITIATED, REPRESENTMENT, PRE_ARBITRATION, ARBITRATION, CASE_WON, CLOSED, NETWORK_REJECTED, CASE_LOST, WRITTEN_OFF_ISSUER, WRITTEN_OFF_PROGRAM |
| case_close_details string Optional | The new dispute state. Allowable Values: See The case_close_details object table. |
Sample request with prearbitration
JSON
{
"action": "RESPOND_WITH_PREARB",
"created_by": "user_name",
"memo": "pre-arb transition for Mc testing",
"network_details": {
"prearbitration_details": {
"amount": 112.0,
"attached_contents": [
"content_token"
],
"why_are_you_initiating_prearbitration": "string",
"are_you_providing_new_information": true,
"summary_of_new_information": "string"
},
"prearbitration_response_details": {
"attached_contents": [
"string"
],
"prearb_response_decision": "ACCEPT_PARTIAL",
"amount": "string",
"whyAreYouNotAcceptingLiability": "string",
"certifyThatYouHaveContactedCardholderAndReviewedTheCompellingEvidenceWithThemAndCardholderContinuesDispute": true,
"explanationOfWhyCardholderContinuesDispute": "string",
"certifyThatCardholderNameAndAddressProvidedByAcquirerDoesNotMatchIssuerRecords": true,
"explanationOfWhyYouAreContinuingTheDispute": "string"
},
"arbitration_details": {
"attached_contents": [
"string"
]
},
"representment_details": {
"amount": 0.1,
"attached_contents": [
"string"
]
},
"case_close_details": {
"write_off": true,
"write_off_actor": "PROGRAM"
}
}
}
Sample response with prearbitration
JSON
{
"token": "my_dispute_transition_token",
"created_time": "2022-07-20T22:10:57.423Z",
"last_modified_time": "2022-07-20T22:10:57.423Z",
"case_token": "my_case_token",
"action": "RESPOND_WITH_PREARB",
"created_by": "user_name",
"memo": "pre-arb transition for Mc testing",
"from_network_status": "string",
"to_network_status": "string",
"network_dispute_id": "network_dispute_id",
"system_error_message": "string",
"network_error_message": "string",
"network_details": {
"prearbitration_details": {
"amount": 112.5,
"attached_contents": [
"content_token"
],
"why_are_you_initiating_prearbitration": "string",
"are_you_providing_new_information": true,
"summary_of_new_information": "string"
},
"prearbitration_response_details": {
"attached_contents": [
"content_token"
],
"prearb_response_decision": "ACCEPT_PARTIAL",
"amount": "string",
"whyAreYouNotAcceptingLiability": "string",
"certifyThatYouHaveContactedCardholderAndReviewedTheCompellingEvidenceWithThemAndCardholderContinuesDispute": true,
"explanationOfWhyCardholderContinuesDispute": "string",
"certifyThatCardholderNameAndAddressProvidedByAcquirerDoesNotMatchIssuerRecords": true,
"explanationOfWhyYouAreContinuingTheDispute": "string"
},
"arbitration_details": {
"attached_contents": [
"content_token"
]
},
"representment_details": {
"amount": 112.5,
"attached_contents": [
"content_token"
]
},
"network_state_details": "string",
"dispute_state": "INITIATED",
"case_close_details": {
"write_off": true,
"write_off_actor": "PROGRAM"
}
}
}
Sample request with arbitration
JSON
{
"action": "RESPOND_WITH_ARB",
"created_by": "user_name",
"memo": "arbitration response transition response for Mc testing",
"network_details": {
"prearbitration_details": {
"amount": 112.0,
"attached_contents": [
"content_token"
],
"why_are_you_initiating_prearbitration": "string",
"are_you_providing_new_information": true,
"summary_of_new_information": "string"
},
"prearbitration_response_details": {
"attached_contents": [
"string"
],
"prearb_response_decision": "ACCEPT_PARTIAL",
"amount": "string",
"whyAreYouNotAcceptingLiability": "string",
"certifyThatYouHaveContactedCardholderAndReviewedTheCompellingEvidenceWithThemAndCardholderContinuesDispute": true,
"explanationOfWhyCardholderContinuesDispute": "string",
"certifyThatCardholderNameAndAddressProvidedByAcquirerDoesNotMatchIssuerRecords": true,
"explanationOfWhyYouAreContinuingTheDispute": "string"
},
"arbitration_details": {
"attached_contents": [
"string"
]
},
"representment_details": {
"amount": 0.1,
"attached_contents": [
"string"
]
},
"case_close_details": {
"write_off": true,
"write_off_actor": "PROGRAM"
}
}
}
Sample response with arbitration
JSON
{
"token": "my_dispute_transition_token",
"created_time": "2022-07-20T22:10:57.423Z",
"last_modified_time": "2022-07-20T22:10:57.423Z",
"case_token": "my_case_token",
"action": "RESPOND_WITH_ARB",
"created_by": "user_name",
"memo": "Arbitration response transition response for Mc testing",
"from_network_status": "string",
"to_network_status": "string",
"network_dispute_id": "network_dispute_id",
"system_error_message": "string",
"network_error_message": "string",
"network_details": {
"prearbitration_details": {
"amount": 112.5,
"attached_contents": [
"content_token"
],
"why_are_you_initiating_prearbitration": "string",
"are_you_providing_new_information": true,
"summary_of_new_information": "string"
},
"prearbitration_response_details": {
"attached_contents": [
"content_token"
],
"prearb_response_decision": "ACCEPT_PARTIAL",
"amount": "string",
"whyAreYouNotAcceptingLiability": "string",
"certifyThatYouHaveContactedCardholderAndReviewedTheCompellingEvidenceWithThemAndCardholderContinuesDispute": true,
"explanationOfWhyCardholderContinuesDispute": "string",
"certifyThatCardholderNameAndAddressProvidedByAcquirerDoesNotMatchIssuerRecords": true,
"explanationOfWhyYouAreContinuingTheDispute": "string"
},
"arbitration_details": {
"attached_contents": [
"content_token"
]
},
"representment_details": {
"amount": 112.5,
"attached_contents": [
"content_token"
]
},
"network_state_details": "string",
"dispute_state": "INITIATED",
"case_close_details": {
"write_off": true,
"write_off_actor": "PROGRAM"
}
}
}
Sample accept and close dispute request
JSON
{
"action": "ACCEPT_AND_CLOSE",
"created_by": "user_name",
"memo": "accept and close",
"network_details": {
"prearbitration_details": {
"amount": 112.0,
"attached_contents": [
"content_token"
],
"why_are_you_initiating_prearbitration": "string",
"are_you_providing_new_information": true,
"summary_of_new_information": "string"
},
"prearbitration_response_details": {
"attached_contents": [
"string"
],
"prearb_response_decision": "ACCEPT_PARTIAL",
"amount": "string",
"whyAreYouNotAcceptingLiability": "string",
"certifyThatYouHaveContactedCardholderAndReviewedTheCompellingEvidenceWithThemAndCardholderContinuesDispute": true,
"explanationOfWhyCardholderContinuesDispute": "string",
"certifyThatCardholderNameAndAddressProvidedByAcquirerDoesNotMatchIssuerRecords": true,
"explanationOfWhyYouAreContinuingTheDispute": "string"
},
"arbitration_details": {
"attached_contents": [
"string"
]
},
"representment_details": {
"amount": 0.1,
"attached_contents": [
"string"
]
},
"case_close_details": {
"write_off": true,
"write_off_actor": "PROGRAM"
}
}
}
Sample accept and close dispute response
JSON
{
"token": "my_dispute_transition_token",
"created_time": "2022-07-20T22:10:57.423Z",
"last_modified_time": "2022-07-20T22:10:57.423Z",
"case_token": "my_case_token",
"action": "ACCEPT_AND_CLOSE",
"created_by": "user_name",
"memo": "accept and close",
"from_network_status": "string",
"to_network_status": "string",
"network_dispute_id": "network_dispute_id",
"system_error_message": "string",
"network_error_message": "string",
"network_details": {
"prearbitration_details": {
"amount": 112.5,
"attached_contents": [
"content_token"
],
"why_are_you_initiating_prearbitration": "string",
"are_you_providing_new_information": true,
"summary_of_new_information": "string"
},
"prearbitration_response_details": {
"attached_contents": [
"content_token"
],
"prearb_response_decision": "ACCEPT_PARTIAL",
"amount": "string",
"whyAreYouNotAcceptingLiability": "string",
"certifyThatYouHaveContactedCardholderAndReviewedTheCompellingEvidenceWithThemAndCardholderContinuesDispute": true,
"explanationOfWhyCardholderContinuesDispute": "string",
"certifyThatCardholderNameAndAddressProvidedByAcquirerDoesNotMatchIssuerRecords": true,
"explanationOfWhyYouAreContinuingTheDispute": "string"
},
"arbitration_details": {
"attached_contents": [
"content_token"
]
},
"representment_details": {
"amount": 112.5,
"attached_contents": [
"content_token"
]
},
"network_state_details": "string",
"dispute_state": "INITIATED",
"case_close_details": {
"write_off": true,
"write_off_actor": "PROGRAM"
}
}
}
Sample close with case won dispute request
JSON
{
"action": "CLOSE_WITH_CASE_WON",
"created_by": "user_name",
"memo": "close with case won",
"network_details": {
"prearbitration_details": {
"amount": 112.0,
"attached_contents": [
"content_token"
],
"why_are_you_initiating_prearbitration": "string",
"are_you_providing_new_information": true,
"summary_of_new_information": "string"
},
"prearbitration_response_details": {
"attached_contents": [
"string"
],
"prearb_response_decision": "ACCEPT_PARTIAL",
"amount": "string",
"whyAreYouNotAcceptingLiability": "string",
"certifyThatYouHaveContactedCardholderAndReviewedTheCompellingEvidenceWithThemAndCardholderContinuesDispute": true,
"explanationOfWhyCardholderContinuesDispute": "string",
"certifyThatCardholderNameAndAddressProvidedByAcquirerDoesNotMatchIssuerRecords": true,
"explanationOfWhyYouAreContinuingTheDispute": "string"
},
"arbitration_details": {
"attached_contents": [
"string"
]
},
"representment_details": {
"amount": 0.1,
"attached_contents": [
"string"
]
},
"case_close_details": {
"write_off": true,
"write_off_actor": "PROGRAM"
}
}
}
Sample close with case won dispute response
JSON
{
"token": "my_dispute_transition_token",
"created_time": "2022-07-20T22:10:57.423Z",
"last_modified_time": "2022-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 toCASE_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 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
{
"action": "ACCEPT_AND_CLOSE",
"created_by": "string",
"memo": "string",
"network_details": {
"case_close_details": {
"write_off": true,
"write_off_actor": "PROGRAM"
}
}
}
Sample ACCEPT_AND_CLOSE transition response
JSON
{
"token": "string",
"case_token": "string",
"action": "ACCEPT_AND_CLOSE",
"created_by": "string",
"memo": "string",
"from_network_status": "string",
"to_network_status": "string",
"network_dispute_id": "string",
"system_error_message": "string",
"network_error_message": "string",
"created_time": "timestamp",
"last_modified_time": "timestamp",
"network_details": {
"case_close_details": {
"write_off": true,
"write_off_actor": "PROGRAM"
}
}
}
Create CLOSE_WITH_CASE_WON transition
For Regulation E and non-Regulation E network dispute cases, the dispute state is set toCASE_WON and a CLOSE case transition with reason code 41 (Case Won) is created.
Sample CLOSE_WITH_CASE_WON transition request
JSON
{
"action": "CLOSE_WITH_CASE_WON",
"created_by": "string",
"memo": "string"
}
Sample CLOSE_WITH_CASE_WON transition response
JSON
{
"token": "string",
"case_token": "string",
"action": "ACCEPT_AND_CLOSE",
"created_by": "string",
"memo": "string",
"from_network_status": "string",
"to_network_status": "string",
"network_dispute_id": "string",
"system_error_message": "string",
"network_error_message": "string",
"created_time": "timestamp",
"last_modified_time": "timestamp",
"network_details": {
"case_close_details": {
"write_off": true,
"write_off_actor": "PROGRAM"
}
}
}