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. Prior to this, two state machines -MASTERCARD_CARD and TOK_PAG- were built for specific customers. In the future, the PRIMITIVE state machine is going to be the only one supported for new clients.

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 accepted the dispute loss.
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.
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.
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 endpoint.

During the dispute status process, you are notified of dispute status updates via the dispute status change event. 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
PENDINGOPENOPENED
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.
PENDINGCANCELCANCELED
The dispute was opened, but then cancelled
OPENED ISSUER_WORKEDCHARGEBACK_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.
OPENEDFAILED_ON_CREATIONFAILED
The network failed to create the dispute for some reason.
FAILEDRESENDOPENED
The dispute failed to be created, but has been reopened with possible changes or additional information.
FAILEDISSUER_LOSSISSUER_LOSS
The dispute failed to be created, and the issuer accepts the loss.
CANCELEDREOPENPENDING
The dispute was cancelled, but has been reopened and is now in a PENDING state.
CHARGEBACK_REJECTEDISSUER_LOSSISSUER_LOSS
The network has rejected the chargeback - issuer loss.
CHARGEBACK_REJECTEDRESENDOPENED
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_CREATEDREJECTSCHARGEBACK_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_CREATEDFAILED_ON_CLOSEFAILED_ON_CLOSE
The chargeback failed to close.
CHARGEBACK_CREATEDCLOSED_PROCESSEDCHARGEBACK_CLOSED
Chargeback processing closed, issuer loss.
CHARGEBACK_CREATEDCLOSEDCHARGEBACK_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_CREATEDREJECTS_5000_5001CHARGEBACK_ACCEPTED
Mastercard sends this event in a specific case. The issuer is refunded the dispute loss.
CHARGEBACK_CREATEDISSUER_REPRESENTMENT_UNWORKEDSECOND_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_CLOSECLOSED_PROCESSEDCHARGEBACK_CLOSED
Dispute closed.
SECOND_PRESENTMENTCLOSED_PROCESSEDCHARGEBACK_CLOSED
Network has closed the dispute for some reason.
SECOND_PRESENTMENTFAILED_ON_CLOSEFAILED_ON_CLOSE
Second presentment failed.
SECOND_PRESENTMENTEXPIREEXPIRED
Issuer missed deadline.
SECOND_PRESENTMENTSEND_PRE_ARBITRATIONPRE_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_PRESENTMENTCLOSEDCHARGEBACK_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_OPENEDFAILED_ON_CREATIONFAILED_PRE_ARBITRATION
Network failed to create the pre-arbitration
PRE_ARBITRATION_OPENEDACCEPTED_PRE_ARBITRATIONPRE_ARBITRATION_ACCEPTED
Network has accepted the pre-arbitration
PRE_ARBITRATION_OPENEDREJECT_PRE_ARBITRATIONPRE_ARBITRATION_DECLINED
Network rejected pre-arbitration
PRE_ARBITRATION_OPENEDREJECTSPRE_ARBITRATION_REJECTED
Network rejects pre-arbitration
PRE_ARBITRATION_OPENEDRECALL_PRE_ARBITRATIONPRE_ARBITRATION_RECALL
Arbitration recalled
FAILED_PRE_ARBITRATIONSEND_PRE_ARBITRATIONPRE_ARBITRATION_OPENED
Pre-arbitration reopened after failure.
FAILED_PRE_ARBITRATIONCLOSED_PROCESSEDCHARGEBACK_CLOSED
Network pre-arbitration failure, issuer loss.
FAILED_PRE_ARBITRATIONFAILED_ON_CLOSEFAILED_ON_CLOSE
Network failure. Issuer loss

VISA Allocation Workflow

CHARGEBACK_CREATEDSEND_PRE_ARBITRATIONPRE_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_OPENEDFAILED_ON_CREATIONFAILED_PRE_ARBITRATION
Network failure.
PRE_ARB_ALLOCATION_OPENEDACCEPT_PRE_ARBITRATIONPRE_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_OPENEDDECLINE_PRE_ARBITRATIONPRE_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_OPENEDRECALL_PRE_ARBITRATIONPRE_ARB_ALLOCATION_RECALLED
Network failure. VISA allocation workflow
FAILED_PRE_ARBITRATIONACCEPT_PRE_ARBITRATIONPRE_ARB_ALLOCATION_ACCEPTED
After initial failure, network has accepted the pre-arbitration. VISA allocation workflow
FAILED_PRE_ARBITRATIONCLOSED_PROCESSEDCHARGEBACK_CLOSED
Arbitration failed. VISA allocation workflow
FAILED_PRE_ARBITRATIONFAILED_ON_CLOSEFAILED_ON_CLOSE
Aribitration faied, VISA allocation workflow
PRE_ARB_ALLOCATION_DECLINEDFAILED_ON_CREATIONFAILED_DECLINE_PRE_ARB
Network failure. VISA allocation workflow
PRE_ARB_ALLOCATION_ACCEPTEDFAILED_ON_CREATIONFAILED_ACCEPT_PRE_ARB
Network failure. VISA allocation workflow
FAILED_DECLINE_PRE_ARBDECLINE_PRE_ARBITRATIONPRE_ARB_ALLOCATION_DECLINED
Network declines pre-arbitration. VISA allocation workflow
FAILED_ACCEPT_PRE_ARBACCEPT_PRE_ARBITRATIONPRE_ARB_ALLOCATION_ACCEPTED
Issuer didn't accept dispute loss. VISA allocation workflow.

State machine API endpoints

PRIMITIVE state machine diagram