Integrate

Brite Data Solutions

This section details the integration processes for the key functionality within the Data Solutions offering which is the Account Details data retrieval.

For reading more about the old Data Solutions product, which is deprecated, you can go to this page.

Steps to integrate with Account Details from Brite Data Solutions

The integration consists of 5 steps,.

Display Brite as an option on your site
Create a request for Reports
POST /api/data_solutions.create_reports
Optional: If you use the token render the Brite client on the front-end
<script>new Brite([token])</script>
Handle callback notifications
Retrieve your Reports
POST /api/data_solutions.get_reports

1. Display Brite as an option on your site

At first, customers must recognize and choose Brite as a way to provide their account information to you. Brite provides assets which makes the presentation of the Account Information product clear and visually appealing to your customers.

Link to the assets documentation

Try out our new assets configurator here

2. Create a request for Reports

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

What is a Session? The complete user journey when the person interacts with their bank through the Brite client is called a Session. Here they can carry out actions such as authenticating with their bank or choosing their bank account.

Request to create Reports

The request includes several data points, not all of which are required. However, we 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 report generation flow on your side.

Example:

				
					POST /api/data_solutions.create_reports
Sandbox: sandbox.britepaymentgroup.com
Production: production.britepaymentgroup.com
Content-Type: application/json
Authorization: Bearer <YOUR_TOKEN>

Request
{
  "report_types": ["ACCOUNT_DETAILS"],
  "country_id": "de",
  "brand_name": "My example brand",
  "merchant_reference": "12345-ABC", // Your identifier
  "locale": "de",
  "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",
      "report_state": "SESSION_ABORTED" 
    },
    {
      "url": "https://merchant.com/callback?your_id=12345-ABC",
      "report_state": "SESSION_FAILED"
    },
    {
      "url": "https://merchant.com/callback?kyc=true&your_id=12345-ABC",
      "report_state": "SESSION_COMPLETED"
    }
  ]
}

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 redirection 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. (report_state: SESSION_COMPLETED)
The session fails for unknown reasons. (report_state: SESSION_ABORTED)
The session fails for a known reason. (report_state: SESSION_FAILED)

deeplink_redirect – recommended for mobile apps

When the customer returns from their mobile banking app, 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 that you register the session callback to know how the session is progressing. You can register the session states: SESSION_COMPLETED, SESSION_ABORTED, SESSION_FAILED. Configure your next actions after you receive these states from Brite.

Response from create a session request

				
					{
  "report_id": "ag9ofmFib25lYS0yNTU2MDlyEwsSBlJ",
  "token": "eyJob3N0IjogImh0dH5icml0ZXBheW1lbnRncm91cC"
  "url": "https://sandbox.britepaymentgroup.com/eyJob3N0IjogImh0dH5icml0ZXBheW1lbnRncm91cC"
}

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

The URL opens the Brite’s hosted bank session page. It allows your customers to authenticate themselves towards their bank which lets Brite fetch the data that is needed. We call this the redirect integration. 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 the session callbacks that are described later in this document.

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 is to initiate the Brite client in your checkout. It should be securely shared with the client. This allows your customers to complete the Account Information product session as an embedded experience. We call this the embedded integration. This should be the recommended approach.

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.
You can learn more about how to set this up in this link.

report_id is the unique identifier of the Account Information report of the user. Store the report_id you can retrieve the report once the session has been completed.

3. If you use the token render the Brite client on the front-end

				
					<script>
  var client = new Brite("token")
  [...]
<script>

The Brite client will handle all required authentication and authorisation steps the customer needs to go through with their bank. Once those are completed, you will receive an event on the front-end and the Brite client will close itself.
You can learn more about integrating with the Brite client here.

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.

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.

4.Handle callback 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 request contains information about the session’s outcome, allowing you to update your system and guide your users appropriately.

Example output:

				
					user-agent: Brite callback
content-type: Application/json

{
  "report_id": "ag9ofmFib25lYS0yNTU2MDlyEwsSBlJ",
  "merchant_id": "ag9ofmFib25lYS0xNB1Nlc3Npb2[...]4Yo4PY",
  "report_state": "SESSION_COMPLETED"
}

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

Session Failure

If the report_state is SESSION_ABORTED or SESSION_FAILED, it means that the bank verification process was unsuccessful. In such cases you can:

Return the user to the bank verification step in your front end.
Clearly inform the user that you were unable to fetch the account information and provide options to retry the bank account verification process.

Session Success

In the report_state is SESSION_COMPLETED, the bank verification was completed successfully. For these cases, you can:

Initiate the happy UX in your front end. This might involve showing a success message or moving them to the next step in your flow.
Trigger a /api/data_solutions/get_reports call towards Brite to collect the users bank account data. This is where you will retrieve the necessary information to proceed with your service.

5. Retrieve your Reports

Here’s how to retrieve the users Account Information after a successful session:

Get the account information report: Call the /api/data_solutions.get_reports endpoint using the report_id.

Example output:

				
					POST /api/data_solutions.get_reports
Sandbox: sandbox.britepaymentgroup.com
Production: production.britepaymentgroup.com
Content-Type: application/json
Authorization: Bearer <YOUR_TOKEN>

Request 
{
  "report_id": "ag9ofmFib25lYS0yNTU2MDlyEwsSBlJ"
}

Response
{
  "created_at": "2023-11-16T18:51:46.352Z",
  "account_details": {
     "type": "CURRENT" | "SAVINGS" | "JOINT_ACCOUNT" | "CREDIT_CARD" | "BUSINESS" | "OTHER",
     "holder": {
                 "name": "Anna Svensson",
                },
               
        "iban":"SE4550000000012345678912" | none,
        "bban": {
            clearing_number: "1234",
            bank_account_number: "5678912"
        } | none,
        bic: "MONZGB26" | none,
        bank_name: "SEB" | none,
        currency: "SEK" | none,
        country: "SE" | none,
    },

}

On this page