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 Code | Reason Description |
---|---|
UNKNOWN_ERROR | An unknown error occurred. |
EXCEEDED_LIMIT | Exceeded limit. |
SYSTEM_UNAVAILABLE | System unavailable. |
BAD_REQUEST | Bad request. |
UNAUTHORIZED | Unauthorized. |
FORBIDDEN | Forbidden. |
NOT_FOUND | Not found. |
TOO_MANY_REQUESTS | Too many requests. |
UNEXPECTED_ERROR | Unexpected error. |
SERVICE_UNAVAILABLE | Service unavailable. |
TRANSACTION_INTERRUPTED | Transaction interrupted due to a PSP error on the receiver's side. |
TRANSACTION_LIMIT_EXCEEDED | Daily transaction limit exceeded. |
PAYMENTS_NOT_ALLOWED | Payments to this institution are not allowed. |
RESPONSE_WAIT_TIME_EXPIRED | Time limit for waiting for a response expired. |
INSTANT_PAYMENT_API_BLOCK_MESSAGE | Message returned by the instant-payment-api-ebank - POST /gi/eb/account/block. |
INSTANT_PAYMENT_API_TRANSFER_MESSAGE | Message returned by the instant-payment-api-ebank - POST /gi/eb/account/internal_transfer. |
RECEIVER_PSP_ERROR_INTERRUPTED | Transaction interrupted due to an error at the Receiver's PSP. |
RECEIVER_PSP_ACCOUNT_NUMBER_INVALID | Receiver's PSP transactional account number does not exist or is invalid. |
ACCOUNT_BLOCKED | The specified account is blocked. |
RECEIVER_PSP_ACCOUNT_CLOSED | Receiver's PSP transactional account number closed. |
RECEIVER_PSP_ACCOUNT_TYPE_INVALID | Receiver's PSP transactional account type does not exist or is invalid. |
INSUFFICIENT_BALANCE | Insufficient balance in the PSP payer's PI account. |
INVALID_TRANSACTION_NUMBER | Invalid number of transactions. |
CPF_CNPJ_ACCOUNT_HOLDER_MISMATCH | CPF/CNPJ of the receiving user is not consistent with the account holder credited. |
CPF_CNPJ_RECEIVING_USER_INCORRECT | CPF/CNPJ of the receiving user is incorrect. |
ORDER_REJECTED_BY_RECEIVER_PSP | Order rejected by the Receiver's PSP. |
UNAUTHORIZED_PARTICIPANT_OPERATION | Participant who signed the message is not authorized to operate the debited PI account. |
PAYMENT_PROCESSING_ERROR | Error processing the payment (generic error). |
INVALID_ACCOUNT | Invalid account. |
VALIDATION_FAILED | Transaction failed due to validation failure. |
Updated 24 days ago
What’s Next