In-depth Knowledge

Error handling

When integrating Brite, it’s important to handle potential errors in a user-friendly and reliable way.

This page provides an overview of the most common error codes, including:

A short explanation of what the error means
Guidance on how you should handle it as a merchant
Classification into actionable categories

About Error Handling in the Brite Flow

When an error occurs during a payment flow:

The session or transaction is typically set to state Aborted if the reason is known
If the root cause is not identified, the state is Failed

Each error includes an error_code you receive via session.get or transaction.get and an error message that is displayed to the end user in the Brite Client. To ensure the user sees the correct error message, do not immediately redirect to another page when the Brite Client is shown. Let the Brite client handle and display the message first. Brite’s error messages and codes are updated regularly. Refer to the latest version of this documentation or inspect the error_code fields in the API response (e.g. via session.get or transaction.get).

Unexpected payments after Aborted or Failed states

In rare cases, a bank may label a payment as failed, while the transaction is actually completed.

As a result, the payment may be:

Initially set to Aborted (state 2) or Failed (state 3)
Later updated to Credited (state 5) and Settled (state 6) once funds are confirmed

To handle this correctly in your system, we recommend:

Automatically initiating a refund for duplicate or mistaken payments
Contacting the customer to clarify how to proceed

Error Code Categories

Client-Side Errors

These are errors returned during the user’s interaction with the Brite Client. They’re typically triggered by user behavior or bank-side constraints. You can group them into three categories:

Resolvable Errors

These errors indicate that the issue might be temporary or user-related, and the merchant can support recovery (e.g. by allowing retries or handling UX well).

Error Codes

general_timeout

Timeout occurred during the flow. Implement automatic retry logic (with short delay) for such cases and display a message to the user. Track these events in logs. If this error is persistent, check your own backend performance and notify Brite Support.

generic_bank_error

Temporary bank-side issue. Inform user to retry the flow. If this happens often with a specific bank, contact Brite for escalation. Display a message to the user.

psu_authentication_error

Login failed – bank error or user issue. The user has to check their Mobile Authentication app (or equivalent). Allow retry. Log repeated failures and report to Brite if a pattern emerges.

psu_insufficient_funds_selected_account

Selected account doesn’t have enough funds. Provide the option to go back and select a different account. Otherwise, ask them to retry the process.

psu_insufficient_funds_all_accounts

No account has enough balance. Let the user try again with a lower amount or after transferring funds. Consider giving them the option to select another funding method if supported.

psu_simultaneous_attempt

The user opened multiple sessions at once. Detect and prevent rapid re-clicks or parallel session starts in your frontend. Instruct the user to wait a few seconds and retry.

psu_simultaneous_attempt_cancel_login

Previous session still pending in the bank app. Provide instructions to open their banking app, cancel the previous authentication, and then return to retry the process. Show this error prominently and clearly.

Non-Resolvable Errors

These indicate intentional or expected behavior by the user. No merchant-side recovery is needed.

psu_abandoned_session

User didn´t complete the flow in time. Show a friendly timeout message (e.g. “It looks like you took a break — let’s try again”) and offer a clear way to restart the flow. Log these events, but no backend action is needed.

psu_closed_client

The user closed the Brite client manually. No further action needed. The user chose to abandon the flow. You can optionally offer a “Resume payment” CTA if the session is still active.

psu_canceled_authentication

User aborted authentication in the bank app. Clearly state that the authentication was canceled. Let the user restart or return to your checkout. No retry or backend handling required.

bank_rejected_transaction

The bank rejected the transaction post-confirmation. Check request details. Escalate to Brite if repeated.

risk_engine_rejection

Brite’s internal risk engine rejected the transaction. Contact Brite if it seems like a false positive.

Merchant Approval

These codes are returned when the merchant has implemented the approval_required=true setting. They reflect the merchant’s business logic, not a technical or user-side error.

merchant_approval_timeout

No timely response from your system for approval. Ensure your system responds to the approval_required request within the expected time window (usually 5–10 seconds). Timeouts may lead to user drop-off. Monitor and optimize your response logic.

merchant_approval_rejected

Transaction was denied by your system. This is expected behavior based on your logic. Make sure your UI communicates clearly that the transaction was not accepted and explain why (if appropriate). Log these decisions for auditability.

Server-Side Errors (HTTP 400 and above)

These errors are returned immediately by Brite’s API due to invalid or malformed requests. They should be caught and handled during integration. These errors are not visible to the end user and must be addressed by the merchant’s tech team.

Please see our API-Documentation for further details.

Best Practices for Merchants

Test unhappy flows in Sandbox
Make sure to test flows where errors can happen.

Use friendly error messages
Avoid showing technical codes to users. Use clear and helpful instructions instead.

Implement retry logic
Allow users to retry flows when facing recoverable issues like timeouts or bank unavailability.

Log errors for support
Always capture the error_code and context on your side for diagnostics and support.

Handle edge cases safely
Even rare or unknown errors should never crash the user flow — display a fallback message.