Transaction Failure and State Transition

When a transaction fails, its state will transition to FAILED. This state transition indicates that the transaction could not be completed successfully due to an error or another issue.

State Structure

The State class is used to represent the current status of the transaction. When a transaction moves to the FAILED state, the State object will have the following attributes:

• status: This will be set to FAILED to indicate that the transaction did not succeed.
• reason: This attribute provides additional context about why the transaction failed. It contains detailed information in the form of a Reason object.
• createdAt: his timestamp records when the state was created, reflecting the exact moment when the transaction transitioned to the FAILED state.

Reason Attribute

The Reason object within the State class provides further details about the failure. It includes:

• code: A string that represents a specific error code, which can be used to identify the type of failure.
• message: A descriptive message that explains the nature of the failure, providing more context for debugging or user communication.
• details: A map containing any additional information related to the failure, which can include specific parameters, validation errors, or other relevant data.

Example

When a transaction fails due to insufficient balance, the State object might look like this:

{
  "status": "FAILED",
  "reason": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Insufficient balance in the PSP payer's PI account.",
    "details": {}
  },
  "createdAt": "2024-08-20T12:31:46.1400Z"
}

State(  
    status = "FAILED",  
    reason = Reason(  
        code = "INSUFFICIENT_BALANCE",  
        message = "Insufficient balance in the PSP payer's PI account.",  
        details = emptyMap() 
    ),  
    createdAt = ZonedDateTime.now()  
)

In this example:

• The status is FAILED.
• The reason contains an error code INSUFFICIENT_BALANCE, and a message explaining the failure.

This structure allows for clear and informative error handling, making it easier to diagnose and respond to transaction failures.

Reason Codes