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 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 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 |
|---|---|---|
| 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 - Get possible dispute statuses for a dispute.
- Get possible states - Get possible dispute statuses given a current status and event
PRIMITIVE state machine diagram
Updated 5 months ago