--- updatedAt: 2026-06-11T19:00:30.000Z agentTools: siteIndex: https://developers.pismo.io/llms.txt projectIndex: https://developers.pismo.io/pismo-docs/llms.txt --- # Disputes state machine A state machine is a programming architecture that allows dynamic flow to states depending on values from previous states or user inputs. Pismo uses a state machine it calls the *PRIMITIVE* state machine to guide customers through the dispute process. The PRIMITIVE state machine provides a framework for opening a dispute and resolving it through the card network system. Customers can use this framework to build their own state machine on top of that, though it is not necessary. The PRIMITIVE state machine covers all aspects of chargeback, second presentment, pre-arbitration, and Visa allocation. ## PRIMITIVE state machine statuses The following table provides a brief explanation of PRIMITIVE state machine statuses. Each status also has a group status. {`

Status/Group status	Description
PENDING Group status: OPEN	Dispute created, but card network requires further information from issuer.
OPENED Group status: CARDNETWORK_CHARGEBACK	Dispute was opened with a case ID or claim ID.
CANCELED Group status: DENIED	Issuer did not proceed with creating the chargeback.
FAILED Group status: FAILED	Issuer must provide correct information
EXPIRED Group status: LOSS	Issuer did not meet the deadline and has, therefore, lost the dispute.
CHARGEBACK_CREATED Group status: CARDNETWORK_CHARGEBACK	Dispute initiated with success. Issuer can open a chargeback with forms and documents.
CHARGEBACK_ACCEPTED Group status: WON	Acquirer gives up the chargeback. Specific for Mastercard disputes.
CHARGEBACK_REJECTED Group status: LOSS	Card network rejected chargeback creation.
CHARGEBACK_CLOSED Group status: LOSS	Issuer wants to accept second presentment or give up the chargeback.
CHARGEBACK_REJECT_COLLABORATION Group status: WON	Acquirer gives up the chargeback. Specific for Disputes with Mastercard cardnetwork
CHARGEBACK_PENDING_DOCUMENTATION Group status: CARDNETWORK_CHARGEBACK	Issuer pending attach documentation.
SECOND_PRESENTMENT Group status: CARDNETWORK_SECOND_PRESENTMENT	Acquirer didn't accept the chargeback and wants to prove why. Issuer receives the document from acquirer with the amount and the new reason code.
FAILED_PRE_ARBITRATION Group status: FAILED	The pre-arbitration, for some reason, could not be created.
FAILED_DOCUMENTATION Group status: FAILED	Card network considered the documentation invalid
FILED_IN_ERROR Group status: FAILED	The pre-arbitration, for some reason, could not be created.
PRE_ARBITRATION_OPENED Group status: CARDNETWORK_PREARBITRATION	Issuer didn't accept the second presentment and wants to proceed with the dispute. Issuer can upload new documents, a new amount (partial), and new information text.
PRE_ARBITRATION_ACCEPTED Group status: WON	Acquirer accepts dispute loss.
PRE_ARBITRATION_DECLINED Group status: LOSS	Acquirer didn't accept the dispute loss. Issuer receives the documents that the acquirer uses to decline.
ISSUER_LOSS Group status: LOSS	Issuer accepts dispute loss after a failed or chargeback rejected status.
FAILED_ON_CLOSE Group status: FAILED	The chargeback could not, for some reason, be closed.
PRE_ARB_ALLOCATION_OPENED Group status: CARDNETWORK_PREARBITRATION	Acquirer initiated a pre-arbitration. Visa allocation workflow.
PRE_ARB_ALLOCATION_ACCEPTED Group status: LOSS	Issuer didn't accept dispute loss. Visa allocation workflow.
PRE_ARB_ALLOCATION_DECLINED Group status: WON	Issuer didn't accept acquirer claims. Visa allocation workflow.
PRE_ARB_ ALLOCATION_RECALLED Group status: WON	Acquirer accepts the loss after opening a pre-arbitration. Visa allocation workflow.
FAILED_ACCEPT_PRE_ARB Group status: FAILED	Network couldn’t accept pre-arbitration. Visa allocation workflow.
FAILED_DECLINE_PRE_ARB Group status: FAILED	Network couldn’t decline pre-arbitration. Visa allocation workflow.

`} ## Events and statuses The PRIMITIVE state machine works through *events* and *statuses*. An event occurs and transitions the dispute status to a new status. For example, an `ISSSUER_LOSS` event occurs, meaning the issuer accepts the loss, moves the dispute status to `ISSUER_LOSS` and the group status to `LOSS`. Events can come from the network or from the [Update dispute status](https://developers.pismo.io/pismo-docs/reference/post-v1-disputes-disputeid-event) endpoint. During the dispute status process, you are notified of dispute status updates via the [dispute status change event](https://developers.pismo.io/events/docs/disputes-dispute-installment-status-change-1). The `dispute_status` object contains fields indicating the status (`description`), the state machine (`type`) and dispute group status. The following table shows how events transition a dispute status in the PRIMITIVE state machine: {`

Dispute status	Event	New status
PENDING	OPEN	OPENED
If the dispute was created and has a PENDING status, the issuer must send the OPEN event (via Update dispute status) to move the dispute to OPENED. When that happens, Pismo sends the request to create a chargeback to the card network.
PENDING	CANCEL	CANCELED
The dispute was opened, but then cancelled
OPENED	ISSUER_WORKED	CHARGEBACK_CREATED
The card network has responded to Pismo with an ISSUER_WORKED event, meaning it has accepted and opened the chargeback dispute. Pismo then transitions the dispute status to CHARGEBACK_CREATED.
OPENED	FAILED_ON_CREATION	FAILED
The network failed to create the dispute for some reason.
FAILED	RESEND	OPENED
The dispute failed to be created, but has been reopened with possible changes or additional information.
FAILED	ISSUER_LOSS	ISSUER_LOSS
The dispute failed to be created, and the issuer accepts the loss.
CANCELED	REOPEN	PENDING
The dispute was cancelled, but has been reopened and is now in a PENDING state.
CHARGEBACK_REJECTED	ISSUER_LOSS	ISSUER_LOSS
The network has rejected the chargeback - issuer loss.
CHARGEBACK_REJECTED	RESEND	OPENED
If the chargeback is rejected, you can use the Update dispute status endpoint to send the RESEND event after, for example, uploading additional evidence files. Pismo tries again to create the chargeback with the network and transitions the status to OPENED.
CHARGEBACK_CREATED	REJECTS	CHARGEBACK_REJECTED
After a chargeback is created, the card network can reject the chargeback (check Mastercard and VISA rejection rules) and Pismo transitions the status to CHARGEBACK_REJECTED. If you still want to pursue this dispute, you will need to change the dispute status to RESEND.
CHARGEBACK_CREATED	FAILED_ON_CLOSE	FAILED_ON_CLOSE
The chargeback failed to close.
CHARGEBACK_CREATED	CLOSED_PROCESSED	CHARGEBACK_CLOSED
Chargeback processing closed, issuer loss.
CHARGEBACK_CREATED	CLOSED	CHARGEBACK_ACCEPTED
If a chargeback is created and the acquirer doesn't contest the dispute and accepts the chargeback, the network sends the CLOSED event to Pismo, who then transitions the status to CHARGEBACK_ACCEPTED.
CHARGEBACK_CREATED	REJECTS_5000_5001	CHARGEBACK_ACCEPTED
Mastercard sends this event in a specific case. The issuer is refunded the dispute loss.
CHARGEBACK_CREATED	ISSUER_REPRESENTMENT_UNWORKED	SECOND_PRESENTMENT
If the chargeback is created and the acquirer decides to contest the dispute, then the card network sends Pismo an ISSUER_REPRESENTMENT_UNWORKED event and Pismo transitions the status to SECOND_PRESENTMENT.
FAILED_ON_CLOSE	CLOSED_PROCESSED	CHARGEBACK_CLOSED
Dispute closed.
SECOND_PRESENTMENT	CLOSED_PROCESSED	CHARGEBACK_CLOSED
Network has closed the dispute for some reason.
SECOND_PRESENTMENT	FAILED_ON_CLOSE	FAILED_ON_CLOSE
Second presentment failed.
SECOND_PRESENTMENT	EXPIRE	EXPIRED
Issuer missed deadline.
SECOND_PRESENTMENT	SEND_PRE_ARBITRATION	PRE_ARBITRATION_OPENED
After a dispute status changes to SECOND_PRESENTMENT, the issuer can use the SEND_PRE_ARBITRATION event in Update dispute status to initiate a pre-arbitration. This endpoint has a number of fields specifically for pre-arbitration.
SECOND_PRESENTMENT	CLOSED	CHARGEBACK_ACCEPTED
If the acquirer doesn't contest the dispute and accepts the chargeback, the network sends the CLOSED event to Pismo, who then transitions the status to CHARGEBACK_ACCEPTED
PRE_ARBITRATION_OPENED	FAILED_ON_CREATION	FAILED_PRE_ARBITRATION
Network failed to create the pre-arbitration
PRE_ARBITRATION_OPENED	ACCEPTED_PRE_ARBITRATION	PRE_ARBITRATION_ACCEPTED
Network has accepted the pre-arbitration
PRE_ARBITRATION_OPENED	REJECT_PRE_ARBITRATION	PRE_ARBITRATION_DECLINED
Network rejected pre-arbitration
PRE_ARBITRATION_OPENED	REJECTS	PRE_ARBITRATION_REJECTED
Network rejects pre-arbitration
PRE_ARBITRATION_OPENED	RECALL_PRE_ARBITRATION	PRE_ARBITRATION_RECALL
Arbitration recalled
FAILED_PRE_ARBITRATION	SEND_PRE_ARBITRATION	PRE_ARBITRATION_OPENED
Pre-arbitration reopened after failure.
FAILED_PRE_ARBITRATION	CLOSED_PROCESSED	CHARGEBACK_CLOSED
Network pre-arbitration failure, issuer loss.
FAILED_PRE_ARBITRATION	FAILED_ON_CLOSE	FAILED_ON_CLOSE
Network failure. Issuer loss
VISA Allocation Workflow
CHARGEBACK_CREATED	SEND_PRE_ARBITRATION	PRE_ARB_ALLOCATION_OPENED
In Visa’s allocation workflow, the acquirer sends a pre-arbitration instead of a second presentment. Once the card network system receives this, the dispute status changes automatically to PRE_ARB_ALLOCATION_OPENED. When this happens, the issuer must respond, either accepting the dispute loss or reject it.
PRE_ARB_ALLOCATION_OPENED	FAILED_ON_CREATION	FAILED_PRE_ARBITRATION
Network failure.
PRE_ARB_ALLOCATION_OPENED	ACCEPT_PRE_ARBITRATION	PRE_ARB_ALLOCATION_ACCEPTED
If issuer wants to accept the pre-arbitration allocation they can send the event ACCEPT_PRE_ARBITRATION. This close the dispute permanently and they accept the loss. VISA allocation workflow
PRE_ARB_ALLOCATION_OPENED	DECLINE_PRE_ARBITRATION	PRE_ARB_ALLOCATION_DECLINED
If the acquirer wants to proceed with the dispute they can send the event DECLINE_PRE_ARBITRATION. This requires the issuer to attach more pre-arbitratipn information. The new document can be uploaded using the Create dispute endpoint but, this time, the category field must have the pre-arbitration information. VISA allocation workflow.
PRE_ARB_ALLOCATION_OPENED	RECALL_PRE_ARBITRATION	PRE_ARB_ALLOCATION_RECALLED
Network failure. VISA allocation workflow
FAILED_PRE_ARBITRATION	ACCEPT_PRE_ARBITRATION	PRE_ARB_ALLOCATION_ACCEPTED
After initial failure, network has accepted the pre-arbitration. VISA allocation workflow
FAILED_PRE_ARBITRATION	CLOSED_PROCESSED	CHARGEBACK_CLOSED
Arbitration failed. VISA allocation workflow
FAILED_PRE_ARBITRATION	FAILED_ON_CLOSE	FAILED_ON_CLOSE
Aribitration faied, VISA allocation workflow
PRE_ARB_ALLOCATION_DECLINED	FAILED_ON_CREATION	FAILED_DECLINE_PRE_ARB
Network failure. VISA allocation workflow
PRE_ARB_ALLOCATION_ACCEPTED	FAILED_ON_CREATION	FAILED_ACCEPT_PRE_ARB
Network failure. VISA allocation workflow
FAILED_DECLINE_PRE_ARB	DECLINE_PRE_ARBITRATION	PRE_ARB_ALLOCATION_DECLINED
Network declines pre-arbitration. VISA allocation workflow
FAILED_ACCEPT_PRE_ARB	ACCEPT_PRE_ARBITRATION	PRE_ARB_ALLOCATION_ACCEPTED
Issuer didn't accept dispute loss. VISA allocation workflow.

`} ## Migration statuses and events Pismo can migrate a dispute from VISA and Mastercard onto the Pismo platform where the customer can continue with the dispute. | Dispute status | Event | New status | | :------------- | :----------------------------------- | :----------------------------- | | MIGRATION | FAILED\_ON\_CREATION | FAILED\_MIGRATION | | MIGRATION | ISSUER\_REPRESENTMENT\_UNWORKED | SECOND\_PRESENTMENT | | MIGRATION | ISSUER\_WORKED | CHARGEBACK\_CREATED | | MIGRATION | SEND\_PRE\_ARBITRATION\_ALLOCATION | PRE\_ARB\_ALLOCATION\_OPENED | | MIGRATION | SEND\_PRE\_ARBITRATION | PRE\_ARBITRATION\_OPENED | | MIGRATION | UNASSIGNED | UNASSIGNED | | MIGRATION | ACCEPTED\_PRE\_ARBITRATION | PRE\_ARBITRATION\_ACCEPTED | | MIGRATION | REJECT\_PRE\_ARBITRATION | PRE\_ARBITRATION\_DECLINED | | MIGRATION | PRE\_ARBITRATION\_REJECTS | PRE\_ARBITRATION\_REJECTED | | MIGRATION | RECALL\_PRE\_ARBITRATION | PRE\_ARBITRATION\_RECALL | | MIGRATION | ACCEPT\_PRE\_ARBITRATION | PRE\_ARB\_ALLOCATION\_ACCEPTED | | MIGRATION | DECLINE\_PRE\_ARBITRATION | PRE\_ARB\_ALLOCATION\_DECLINED | | MIGRATION | RECALL\_ALLOCATION\_PRE\_ARBITRATION | PRE\_ARB\_ALLOCATION\_RECALLED | | MIGRATION | EXPIRE | EXPIRED | | MIGRATION | CLOSED | CHARGEBACK\_ACCEPTED | | MIGRATION | REJECTS | CHARGEBACK\_REJECTED | | MIGRATION | REJECTS\_5000\_5001 | CHARGEBACK\_ACCEPTED | | MIGRATION | CLOSED\_PROCESSED | CHARGEBACK\_CLOSE | ## State machine API endpoints * [Get possible dispute states](https://developers.pismo.io/pismo-docs/reference/get-v1-disputes-disputeid-possible-status) - Get possible dispute statuses for a dispute. * [Get possible states](https://developers.pismo.io/pismo-docs/reference/get-v1-disputes-possible-status) - Get possible dispute statuses given a current status and event ## PRIMITIVE state machine diagram Disputes state machine graphic

VISA Allocation Workflow