Dashboard

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

Reason CodeReason Description
UNKNOWN_ERRORAn unknown error occurred.
EXCEEDED_LIMITExceeded limit.
SYSTEM_UNAVAILABLESystem unavailable.
BAD_REQUESTBad request.
UNAUTHORIZEDUnauthorized.
FORBIDDENForbidden.
NOT_FOUNDNot found.
TOO_MANY_REQUESTSToo many requests.
UNEXPECTED_ERRORUnexpected error.
SERVICE_UNAVAILABLEService unavailable.
TRANSACTION_INTERRUPTEDTransaction interrupted due to a PSP error on the receiver's side.
TRANSACTION_LIMIT_EXCEEDEDDaily transaction limit exceeded.
PAYMENTS_NOT_ALLOWEDPayments to this institution are not allowed.
RESPONSE_WAIT_TIME_EXPIREDTime limit for waiting for a response expired.
INSTANT_PAYMENT_API_BLOCK_MESSAGEMessage returned by the instant-payment-api-ebank - POST /gi/eb/account/block.
INSTANT_PAYMENT_API_TRANSFER_MESSAGEMessage returned by the instant-payment-api-ebank - POST /gi/eb/account/internal_transfer.
RECEIVER_PSP_ERROR_INTERRUPTEDTransaction interrupted due to an error at the Receiver's PSP.
RECEIVER_PSP_ACCOUNT_NUMBER_INVALIDReceiver's PSP transactional account number does not exist or is invalid.
ACCOUNT_BLOCKEDThe specified account is blocked.
RECEIVER_PSP_ACCOUNT_CLOSEDReceiver's PSP transactional account number closed.
RECEIVER_PSP_ACCOUNT_TYPE_INVALIDReceiver's PSP transactional account type does not exist or is invalid.
INSUFFICIENT_BALANCEInsufficient balance in the PSP payer's PI account.
INVALID_TRANSACTION_NUMBERInvalid number of transactions.
CPF_CNPJ_ACCOUNT_HOLDER_MISMATCHCPF/CNPJ of the receiving user is not consistent with the account holder credited.
CPF_CNPJ_RECEIVING_USER_INCORRECTCPF/CNPJ of the receiving user is incorrect.
ORDER_REJECTED_BY_RECEIVER_PSPOrder rejected by the Receiver's PSP.
UNAUTHORIZED_PARTICIPANT_OPERATIONParticipant who signed the message is not authorized to operate the debited PI account.
PAYMENT_PROCESSING_ERRORError processing the payment (generic error).
INVALID_ACCOUNTInvalid account.
VALIDATION_FAILEDTransaction failed due to validation failure.