In-depth Knowledge

Session States

The session concept

A session handles any customer interaction. From choosing a bank, logging into their bank account and passing any required steps for that, selecting a bank account and any further details to then ultimately completing the session.

What is relevant for your integration?

Sessions are only applied where there are customer interactions, namely

Payments (deposits or payins)
Data Solutions

Sessions are not relevant if you integrate payouts (withdrawals) or refunds. The session has different states of which only 4 are really relevant for an integration. That is STATE_AUTHENTICATION_COMPLETED (2), STATE_COMPLETED (12), STATE_ABORTED (10) and STATE_FAILED (11) (highlighted in below table).

At the end of the session, the customer has either initiated a payment (deposit or payin) or granted access to their bank account details (data solutions). You can find all details about the session in the session response. That is especially the case for the transaction_id which allows you to do further processing based on the transaction rather than the session outcome.

Sessions DO NOT track flow of funds Sessions indicate if the customer completed all steps required to authenticate and, if requested, authorise the payment. But ultimately they serve the purpose of initiating a payment (deposit) and not processing it further. So if you are interested in the flow of funds, meaning you like to know if a payment (deposit) was actually received or not, we recommend subscribing to the transaction states.

Session timeout

The session is alive for 30 minutes after it was created (STATE_CREATED).

When the session expires, meaning it has not failed, aborted or completed before the 30 min, Brite aborts the session and triggers a STATE_ABORTED (10) with the error code expired_session. You also receive a notification for that if you subscribed to the state 10 notification callback.

Session can still be successful after the session expired

Some banks require the customer to complete steps for the authentication and authorisation outside of the Brite client. This means Brite can’t track those steps even when the session expires. In the highly unlikely case that a customer still completes the payment or data access after the session expired (they would need to have started the process shortly before session expiry), the transaction can still succeed. You can circumvent this by subscribing to the transaction states for processing flow of funds instead of relying on the finale state of the session.

Session State Flow

`session_state`*	Session state name	Description	What to do?	Notification?
`0`	`STATE_CREATED`	Session has been created in Brite's system.	-	-
`1`	`STATE_AUTHENTICATION_STARTED`	The customer has submitted their login credentials for their bank OR has been redirected to their bank to login.	-	-
`2`	`STATE_AUTHENTICATION_COMPLETED`	The customer completed all required steps for the login.	Approve or reject the session	Yes
`3`	`STATE_BANK_ACCOUNT_SELECTION_STARTED`	The customer sees a list of bank accounts available to them. They select one bank account and continue.	-	-
`4`	`STATE_BANK_ACCOUNT_SELECTION_COMPLETED`	The customer has selected the bank account they want to continue with.	-	-
`5`	`STATE_DEPOSIT_STARTED`	The customer is asked to authorise the payment.	-	-
`6`	`STATE_RECIPIENT_APPROVAL_STARTED`	If the bank requires the customer to add Brite as a recipient of their transactions, Brite allows to do that as part of the payment session. Banks which require recipients: SE > Swedbank.	-	-
`7`	`STATE_RECIPIENT_APPROVAL_COMPLETED`	If the customer had to add Brite as a recipient, then this marks the end of this process and the customer can continue.	-	-
`8`	`STATE_TRANSACTION_APPROVAL_STARTED`	The bank requires the customer to approve the payment. This can be different from bank to bank but usually involves specific steps to authorise the payment.	-	-
`9`	`STATE_TRANSACTION_APPROVAL_COMPLETED`	The bank confirmed that the customer successfully completed all required steps to authorise the payment.	-	-
`10`	`STATE_ABORTED`	The session aborted for a known reason. See list of errors.	-	Yes
`11`	`STATE_FAILED`	The session failed for unknown reason or was manually failed by Brite.	-	Yes
`12`	`STATE_COMPLETED`	The session has been completed successfully. In case you integrate Brite Payments or Data Solutions, you can use the `transaction_id` to further process the transaction. Find that as part of the session details.	Store relevant details and continue with the transaction_id	Yes

* only the numerical session_state is shared in the notification.

				
					{
    // Identifiers
    "id": "ag9ofmFib25lYS0xNzYyMTNyFQsSC1RyYW5zYWN0aW9uGOOznssBDA",
    "transaction_id": "ag9ofmFib25lYS0xNzYyMTNyFQsSC1RyYW5zYWN0aW9uGkLpXv3rBDA",
    "bank_account_id": "ag9ofmFib25lYS0xNzYyMTNyFQsSC1RyYW5zYWN0aW9uHjM9bYqZBDA",
    "bank_id": "ag9ofmFib25lYS0yNDkwMTRyEQsSBEJhbmsYgICAksbT5AkM",
    "customer_id": "ag9ofmFib25lYS0xNzYyMTNyFQsSC1RyYW5zYWN0aW9uKzV8hP2aBDA",
    "fee_id": "ag9ofmFib25lYS0xNzYyMTNyFQsSC1RyYW5zYWN0aW9uLwE6jK9fBDA",
    "merchant_reference": "SHOP-ORDER-001",
    "reference": "TXN-REF-20240312",

    // Status and State
    "state": "12", // 12 = STATE_COMPLETED
    "type": 1, // Deposit
    "created": 1744627000,
    "completed": 1744627500,
    "error_code": "psu_canceled_authentication",

    // Amount and Currency
    "amount": 123.45,
    "currency_id": "sek",

    // Bank Account Information
    "bank_account": {
        "balance": 9876.54,
        "bank_id": "ag9ofmFib25lYS0yNDkwMTRyEQsSBEJhbmsYgICAksbT5AkM",
        "bban": "SE12345678901234567890",
        "deposit_disabled": false,
        "holder": "John Doe",
        "iban": "SE98765432109876543210",
        "id": "ag1hYm9uZWEtMjQ5MDE0chELEgtCYW5rQWNjb3VudBgBDA",
        "name": "My Savings Account",
        "payment_account": true,
        "previous_selected": true,
        "product": "Savings Plus",
        "unchecked_balance": 10000.00
    },

    // Bank Information
    "bank": {
        "id": "ag9ofmFib25lYS0yNDkwMTRyEQsSBEJhbmsYgICAksbT5AkM",
        "name": "Swedbank"
    },

    // Other
    "country_id": "se",
    "ip": "192.168.1.100",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"
}