Integrate

Brite Data Solutions

This section details the integration processes for two key functionalities within the Data Solutions offering: Bank Account data retrieval and User authentication . These tools enable merchants to authenticate users and gather necessary bank account information.

Bank Account Selection

The Bank Account Selection API enables merchants to securely collect a user’s bank account data.

During a session initiated via sessions.create_bank_account_selection API, Brite authenticates the user with their bank and allows them to select one of their bank accounts.

Once the account selection is successful, Brite generates a unique identifier called the bank_account_id. This ID securely represents all the details of the user’s chosen bank account. Merchants can then fetch this bank_account_id once the session is complete.

Before you start! For you to complete the integration successfully, you should have:

API Credentials for the sandbox consisting of a public_key and a secret => Reach out to Brite if you don’t have them.
Choose your Integration Type => Brite offers embedded and redirect integrations (see below).

The integration consists of 5 steps,.

Display Brite as an option on your site
GET /v1/assets/
Create a session to initiate the bank account selection
POST /api/session.create_bank_account_selection
Render the Brite Client on the front-end
<script>new Brite([token])</script>

Handle the session webhook
POST [callbacks[…].url]
Retrieve the bank account data
POST /api/session.get

Integration Types

You can integrate Brite in two ways: embedded within your site (we highly recommend this option) or through a redirect to a Brite-hosted payment page.

We refer to each in the respective integration step and highlight relevant aspects about each. However, note that Brite is optimised for embedded integration.

Integration Steps

1. Display Brite on your site

At first, customers must recognise and choose Brite as a way to verify their bank account details.

Brite provides assets which make the presentation of Brite as a bank account verification option clear and visually beautiful for your customers!

The best way to do that is to use Brite’s assets API. Find that in more detail at: https://docs.britepayments.com/checkout-ux-guidelines/automated-asset-deliver/

2. Initiate Bank Account Selection Session:

Before you can create a session, you need to authorize your access to Brite's APIs. You'll find the necessary steps in the API Authentication section. Completing these steps will provide you with an access_token that you'll need to include in all your subsequent requests to the Brite APIs.

Request to create a session

The request includes several data points, not all of which are required. However, we highly recommend adding them as outlined in the sample request here. Providing the data can improve the overall UX for the customer and also allow you to follow the session flow on your side.

Example Request:

				
					POST /api/session.create_bank_account_selection HTTP/1.1
Host: sandbox.britepaymentgroup.com
Content-Type: application/json
Authorization: Bearer <YOUR_TOKEN>
{
  "country_id": "se",
  "brand_name": "My example brand",
  "merchant_reference": "12345-ABC", // Your identifier
  "locale": "sv",
  "redirect_uri": "https://merchant.com/bank_account_verification?your_id=12345-ABC",
  "deeplink_redirect": "myapp://open?your_id=12345-ABC",
  "callbacks": [
    {
      "url": "https://merchant.com/callback?your_id=12345-ABC",
      "session_state": 10 // STATE_ABORTED to go back to bank account linking step
    },
    {
      "url": "https://merchant.com/callback?your_id=12345-ABC",
      "session_state": 11 // STATE_FAILED to go back to bank account linking step
    },
    {
      "url": "https://merchant.com/callback?kyc=true&your_id=12345-ABC",
      "session_state": 12 // STATE_COMPLETED to fetch the bank_account_id
    }
}

Here we highlight some parameters. For a full list of all parameters, check out the API reference.

brand_name

The brand name is visible to the customer when using Brite. You should choose a recognisable and relatable brand name here for a better experience. Note that even though there is no character limitation, Brite will show 31 characters in the smallest version of the client.

redirect_uri – only for hosted integrations

When the session completes, aborts or in other ways finishes, Brite opens the link provided in redirect_uri If you use Brite via the hosted integration.

Brite opens the link once the session finishes. That is when

The customer completes the session (session_state: 12 , STATE_COMPLETED),
The session fails for unknown reasons (session_state: 10 , STATE_ABORTED) or
The session fails for a known reason (session_state: 11 , STATE_FAILED).

Example for mobile apps: myapp://open?screen=bank_account_verification&your_id=12345-AB
Example for web pages: https://merchant.com/bank_account_verification?your_id=2345-AB

deeplink_redirect – recommended for mobile apps

When the customer returns from their mobile banking app or online banking, a Brite web application is opened to handle the returning customer. Note that this is particularly the case on mobile devices. Immediately after that Brite opens the link provided in deeplink_redirect. This way, the customer is basically redirected from their bank to the deeplink_redirect. The link should point to the view in your mobile app or web page on which the customer can continue the session process using Brite.

callbacks

It is crucial to subscribe to the session callbacks to know how the session is progressing. For the standard bank account selection, you should subscribe to the session states 10, 11 and 12.

See below on how you should handle the callback notifications.

Response from create a session request

				
					{
   "url": "https://sandbox.britepaymentgroup.com/eyJo[...]2M1ODI1ZCJ9",
   "token": "eyJo[...]2M1ODI1ZCJ9",
   "id": "ag9o[...]pb24YstTA5AEM"
}

The response contains attributes for both, the embedded integration (token) and the hosted integration (url).

url

The URL opens the Brite’s hosted payment page. It allows your customers to complete the payment on the hosted payment page and then return to your checkout. We call this the redirect integration.

url is NOT for an iframe DO NOT render this url inside an iframe. It is meant to be opened in a new window/tab. If you want to display Brite inside an iframe use the token in combination with the Brite Client javascript.

token

The token to initiate the Brite client in your checkout. It should be securely shared with the client. This allows your customers to complete the bank account verification as an embedded experience. We call this the embedded integration.

Share the token with your front-end The token is meant to be shared with your client (front-end). There you should use the Brite SDK and create a new Brite instance.
Visit https://docs.britepayments.com/technical-documentation/rendering-the-brite-client/ for additional information.

The unique identifier of the session.

Store the session id It will allow you collect the bank account details once the session has been completed.

Embedded integration (Recommended)

The embedded integration allows your customers to complete the session within your site.

In some cases, they might need to complete certain steps such as authentication and authorisation in their online banking. However, they will get back to your site before completing the payment.

Continue the integration by rendering the client on the front-end.

Redirect integration

The redirect integration allows you to redirect the customer to a Brite-hosted page.

The customer completes all required steps there until the session is aborted, failed or completed. At the end of the flow, Brite redirects the customer back to the URL you provided in the redirect_uri.

Continue the integration by handling session callbacks.

3. Render the client on the front-end

				
					<script>
    var client = new Brite('session_token');
    [...]
    </script>

4. Handle session callbacks notifications

After a Brite session concludes—whether successfully, aborted, or failed—Brite sends a POST request to the Callback URL you specified in the initial session request. This webhook notification contains information about the session’s outcome, allowing you to update your system and guide your users appropriately.

Example callback POST request

				
					User-agent: Brite Callback
Content-Type: application/json

{
  "session_id": "ag9ofmFib25lYS0xNzYyMTNyEQsS[...]5QEM",
  "merchant_id": "ag9ofmFib25lYS0xNB1Nlc3Npb2[...]4Yo4PY",
  "session_state": 12
}

The most important part of this payload is the session_state field, which tells you how the session ended. Here’s how you should handle each possible state:

Session Failure (session_state: 10 or 11)

If the session_state is 10 (failed) or 11 (aborted), it means the bank verification process was unsuccessful. In these cases, you should:

Return the user to the bank verification step in your front end.
Clearly inform the user that the verification failed and provide options to retry the verification or choose an alternative method for bank account verification.

Session Success (session_state: 12)

If the session_state is 12 (completed), the bank verification was completed successfully. For these cases, you should:

Initiate the happy path UX in your front end. This might involve showing a success message or moving them to the next step in your flow.
Trigger a /session.get API call towards Brite to collect the user’s bank account data. This is where you’ll retrieve the necessary information to proceed with your service.

5. Get Bank Account Data

Here’s how to retrieve the bank account information after a successful session:

Get the bank account details:
Call the session.get endpoint using the session_id from the webhook notification.
The response will include the Brite-generated bank_account_id and a bank_account object containing the account holder and the bank account details.

The bank_account_id is a unique identifier for the user’s verified bank account and acts as a reference to the bank account data. This bank_account_id can be used to pay out funds to the user’s bank account via the /transaction.create_withdrawal endpoint. For additional information on instant payouts, refer to Brite Instant Payouts

Example session.get request

				
					POST /api/session.get HTTP/1.1
Host: sandbox.britepaymentgroup.com
Content-Type: application/json
Authorization: Bearer <YOUR_ACCESS_TOKEN>

{
  "id": "string" // session_id
}

Example session.get response

				
					{
  "created": 1722535560,
  "country_id": "se",
  "merchant_reference": "Your_ID",
  "state": 12,
  "bank_account_id": "ag1hYm9uZWEtMjQ5MDE0chELEgt[...]gBDA",
  "bank_account": {
    "holder": "John Doe"
    "bban": "********160210",
    "iban": "SE****************160210",
    "id": "ag1hYm9uZWEtMjQ5MDE0chELEgtCYW5r[...]gBDA"

  },
  "customer_id": "ag1hYm9uZWEtMjQ5MDE0cg4LE[...]gBDA"
  [...]
}

BBAN and IBAN values are masked by default! For GDPR and compliance reasons, bban and iban values are masked by default. For specific use cases, if you anticipate that you will need these data points unmasked, please check with your commercial point of contact at Brite.

User Authentication

Shared Content! To avoid redundant content, this section details only the integration steps unique to this process. For common steps (1 and 3), please refer to the preceding section.

The User authentication API provides a mechanism to identify and authenticate returning customers who have previously interacted with Brite, allowing merchants to log them in or recognise them within their systems seamlessly

Brite generates a unique customer_id for every user during any Brite session. You can save this customer_id and associate it with a user in your system. Later, you can trigger a Brite authentication session. Brite will then verify the user’s identity and return their customer_id. This enables you to confidently recognise the user and, for example, grant them access to their private account or retrieve associated data.

The integration consists of 5 steps,.

Display Brite as an option on your site
GET /v1/assets/
Create a session to initiate the authentication session
POST /api/session.create_authentication
Render the Brite Client on the front-end
<script>new Brite([token])</script>

Handle the session webhook
POST [callbacks[…].url]
Retrieve the customer_id
POST /api/session.get

Use Embedded Integration Only The User Authentication functionality is designed exclusively for embedded integrations. Therefore, redirect integrations are not supported. For a detailed explanation of both integration types, refer to Integration types section in the preceding chapter

Integration Steps

2. Initiate an Authentication Session:

Request to create a session

The request includes several data points, not all of which are required. However, we highly recommend adding them as outlined in the sample request below. Providing the data can improve the overall UX for the customer and also allow you to follow the session flow on your side.

Refer to the previous section for descriptions of parameters. For a full list of all parameters, check out the API reference.

Example Request:

				
					POST /api/session.create_authentication HTTP/1.1
Host: sandbox.britepaymentgroup.com
Content-Type: application/json
Authorization: Bearer <YOUR_ACCESS_TOKEN>
{
  "country_id": "se",
  "brand_name": "My example brand",
  "merchant_reference": "12345-ABC", // Your identifier
  "locale": "sv",
  "deeplink_redirect": "myapp://open?your_id=12345-ABC",
  "callbacks": [
    {
      "url": "https://merchant.com/callback?your_id=12345-ABC",
      "session_state": // STATE_ABORTED to go back to authentication selection
    },
    {
      "url": "https://merchant.com/callback?your_id=12345-ABC",
      "session_state": 11 // STATE_ABORTED to go back to authentication selection
    },
    {
      "url": "https://merchant.com/callback?kyc=true&your_id=12345-ABC",
      "session_state": 12 // STATE_COMPLETED to fetch the customer_id
    }
}

Response from create a session request

				
					{
   "url": "https://sandbox.britepaymentgroup.com/eyJo[...]2M1ODI1ZCJ9",
   "token": "eyJo[...]2M1ODI1ZCJ9",
   "id": "ag9o[...]pb24YstTA5AEM"
}

Store the session id It will allow you fetch the customer_id once the session is completed.

The response provides attributes for both embedded integrations (token) and hosted integrations (url). However, as noted earlier, redirect integration is not supported for this functionality, so you must not use the url parameter.

For instructions on how to embed the Brite iframe using our SDK, refer to the Embedding the Brite Javascript SDK section.

4. Handle session callbacks notifications

After the authentication session concludes—whether successfully, aborted, or failed—Brite sends a POST request to the Callback URL you specified in the initial session request. This webhook notification contains information about the session’s outcome, allowing you to update your system and guide your users appropriately.

Example callback POST request

				
					User-agent: Brite Callback
Content-Type: application/json

{
  "session_id": "ag9ofmFib25lYS0xNzYyMTNyEQsS[...]5QEM",
  "merchant_id": "ag9ofmFib25lYS0xNB1Nlc3Npb2[...]4Yo4PY",
  "session_state": 12
}

The most important part of this payload is the session_state field, which tells you how the session ended. Here’s how you should handle each possible state:

Session Failure (session_state: 10 or 11)

If the session_state is 10 (failed) or 11 (aborted), it means the user verification process was unsuccessful. In these cases, you should:

Return the user to the login step in your front end.
Clearly inform the user that the verification failed and provide options to retry the verification or choose an alternative method for user verification.

Session Success (session_state: 12)

If the session_state is 12 (completed), the user verification was completed successfully. For these cases, you should:

Trigger a /session.get API call towards Brite to collect the customer_id.

Initiate the happy path UX in your front-end. This might involve granting them access to their private account or retrieving associated data.

5. Retrieve the customer_id

Call the session.get endpoint using the session_id from the webhook notification. The response will include the Brite-generated customer_id.

Example session.get request

				
					POST /api/session.get HTTP/1.1
Host: sandbox.britepaymentgroup.com
Content-Type: application/json
Authorization: Bearer <YOUR_ACCESS_TOKEN>

{
  "id": "string" // session_id
}

Example session.get response

				
					{
  "created": 1722535560,
  "country_id": "se",
  "merchant_reference": "Your_ID",
  "state": 12,
  "customer_id": "ag1hYm9uZWEtMjQ5MDE0cg4LE[...]gBDA"
  [...]
}