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.
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.
Transaction 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 → LINK |
- | 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 (with you find the the session details {LINK}) to further process the transaction. |
Store relevant details and continue with the transaction_id | Yes |
All session details (response to POST /session.get)
This is a response to the POST /api/session.get
with all details. Note that the details are not always available for all sessions or are added once the session reached a certain state.
{
// 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"
}