Find out more about the product packaging and pricing

Permanent users data

Provided data in API

In our API we provide data of end-user transactions. Transactions can be queried for some category/categories in the specified date range. The response contains a list of all end-user transactions which belong to given categories. If you request parent or root category, the response would include also all subcategories.

Our API provides information on both income and expenses. More detailed information is described here. 

PSD2 data process flow

For this flow is created user account for which are stored all consents of end-user. This account is used for getting data, which are possible to get in up to 90 days (depends on bank) and can be refreshed during this period.

Step 1.

externalUserId

hint

{
    userId: '1a2b...........9z',
    externalUserId: '12......90',
    hint: 'hint to identify user',
    createdAt: '2023-04-25T19:14:35.655Z',
}

Step 2.

As the second step, the user has to give us his consent and authenticate himself/herself against a financial institution. This can be achieved by embedding Bisnode's authentication flow as an iframe, a web link, or redirection to the provider.

The aim of this step is to retrieve the short-lived authentication code which must be exchanged for an authorization token.

For the testing purposes, select "Test Password" and use "tink" as the user authorized by "tink-1234" password.

Step 2.a. - iframe

<iframe src="https://ais.bisnode.com/psd2-ob-auth-web/v1/auth?redirect_uri=CALLBACK_URL&app_id=APPLICATION_ID&authorization_code=USER_ID&mode=iframe">

When using the iframe solution, the code is sent via the postMessage method to the parent window.

The CALLBACK_URL is used as the target origin when sending messages via postMessage.

When no CALLBACK_URL is used or CALLBACK_URL is localhost, then is user redirected to the default landing page after successful login, and postMessage is sent there.

The code can be retrieved by adding an event listener to your site, the page which is embedding the iframe.

The APPLICATION_ID is used for verification of redirect_uri and it is mandatory. For getting APPLICATION_ID, contact our team and provide us your redirect CALBACK_URL (it also can be more than one). We will generate a unique APPLICATION_ID for you.

The USER_ID for authorization code parameter is part of response from /user endpoint

When the user is successfully logged in postMessage contains success: true and in the payload is code:

{"success":true,"payload":{"code":"1234567890asdfghjkl", "username": "test", "bank_id_timestamp": "2022-05-14 22:33"}, "state": "customer state"}

Username is provided when is filled as URL parameter for customer validation that wasn't changed in URL during consent process.

Bank_id_timestamp is timestamp of end-user consent.
State is provided when is filled as URL parameter.

If there occurs an error, then in postMessage is "success": false, and in the payload is error and message:

{"success":false,"payload":{"error":{"status":"USER_CANCELLED","message":"The user cancelled the authentication"}}}

A list of all error statuses can be found here.

window.addEventListener('message', (event) => {
  if (event.origin !== 'https://ais.bisnode.com') {
    return;
  }

  const data = JSON.parse(event.data);

  const { success } = data;

  if (success) {
    const { payload: { code, username, bank_id_timestamp }, state} = data;

// Use the code to exchange for authentication
console.log('Auth code is', code);
} else {
const { payload: { error }} = data;

console.error(
`Error occurred: ${error.status} with message: ${error.message}.`
);
}

console.log(event);
}, false);

Step 2.b. - web link

The link can be used as a simple HREF link as well:

<a href="https://ais.bisnode.com/psd2-ob-auth-web/v1/auth?redirect_uri=CALLBACK_URL&app_id=APPLICATION_ID&authorization_code=USER_ID">

The difference is that we are omitting the mode=iframeparameter and that the end-user will be redirected back to your CALLBACK_URL instead of sending window.postMessage.

Once the user is authenticated against the bank account, he/she is brought back to your site with the code as part of the CALLBACK_URL GET parameter (CALLBACK_URL?code=<your code will be here>).

For testing purposes we can set the CALLBACK_URL to http://localhost:3000/callback, the callback will result in the "Page was not found" error if there is no web server running on the localhost, but everything you need is the code from the URL. Try it out!

The resulting code is used for exchanging an access token in the next step.

When an error occurred during login, the CALLBACK_URL will contain the error parameter for the error code and the message parameter for the error message.

For example:

http://localhost:3000/callback?error=USER_CANCELLED&message=The%20user%20cancelled%20the%20authentication

A list of all error statuses can be found here.

The APPLICATION_IDis used for verification of redirect_uri and it is mandatory. For getting APPLICATION_ID, contact our team and provide us your redirect CALBACK_URI (it also can be more than one). We will generate a unique APPLICATION_ID for you.

The USER_ID for authorization code parameter is part of response from /user endpoint

When no CALLBACK_URL is used or CALLBACK_URL is localhost, then is user redirected to the default landing page after successful login.

Step 2.c. - redirection to provider

The link can be used as a simple HREF link which provides redirection to the provider as well:

<a href="https://ais.bisnode.com/psd2-ob-auth-web/v1/auth?redirect_uri=CALLBACK_URL&app_id=APPLICATION_ID&authorization_code=USER_ID&mode=redirect_to_provider">

Implementation is similar to the HREF link (see 1.b) with the difference that mode is set to redirect_to_provider, which indicates that ais.bisnode.com will provide redirection to provider and back to CALLBACK_URL.

Once the user is authenticated against the bank account, he/she is brought back to your site with the code as part of the CALLBACK_URL GET parameter (CALLBACK_URL?code=<your code will be here>).

When no CALLBACK_URL is used or CALLBACK_URL is localhost, then is user redirected to the default landing page after successful login.

The disadvantage of using this approach is that there are two redirects and the end-user lands directly on the account information provider web page.

For testing purposes we can set the CALLBACK_URL to http://localhost:3000/callback, the callback will result in the "Page was not found" error if there is no web server running on the localhost, but everything you need is the code from the URL. Try it out!

The resulting code is used for exchanging an access token in the next step.

When an error occurred during login, the CALLBACK_URL will contain the error parameter for the error code and the message parameter for the error message.

For example:

http://localhost:3000/callback?error=USER_CANCELLED&message=The%20user%20cancelled%20the%20authentication

A list of all error statuses can be found here.

The APPLICATION_IDis used for verification of redirect_uri and it is mandatory. For getting APPLICATION_ID, contact our team and provide us your redirect CALBACK_URI (it also can be more than one). We will generate a unique APPLICATION_ID for you.

The USER_ID for authorization code parameter is part of response from /user endpoint

Optional parameters:

These parameters can be used for the customization of the authentication views. If the parameter is not filled or has the wrong value, the default value is used. 

Scope 

Grant access to different provider API endpoints which controls the permitted data access.

It is possible to use multiple values separated by a comma. Or by multiple scope parameters.

It is highly recommended to use the default value to get all information needed. 

Sample usage:

<a href="https://ais.bisnode.com/psd2-auth-link-web/v1/auth?redirect_uri=CALLBACK_URL&app_id=APPLICATION_ID&scope=accounts,transaction,identity">


<a href="https://ais.bisnode.com/psd2-auth-link-web/v1/auth?redirect_uri=CALLBACK_URL&app_id=APPLICATION_ID&scope=accounts&scope=transaction&scope=identity">

Market

Lists all providers on a specified market.

Only one value can be specified in the parameter.

Sample usage:

<a href="https://ais.bisnode.com/psd2-auth-link-web/v1/auth?redirect_uri=CALLBACK_URL&app_id=APPLICATION_ID&market=AT">

Locale

Specify the language of the login form.

Sample usage:

<a href="https://ais.bisnode.com/psd2-auth-link-web/v1/auth?redirect_uri=CALLBACK_URL&app_id=APPLICATION_ID&locale=de_DE">

Username

If this parameter is provided, the username field will be pre-filled in the login form. If not, the end-user can type it in. 

Sample usage:

<a href="https://ais.bisnode.com/psd2-auth-link-web/v1/auth?redirect_uri=CALLBACK_URL&app_id=APPLICATION_ID&username=tink">

Test

Specify if the test environment is used.

Sample usage:

<a href="https://ais.bisnode.com/psd2-auth-link-web/v1/auth?redirect_uri=CALLBACK_URL&app_id=APPLICATION_ID&test=true">

 It is possible to use all optional parameters together.

Optional parameters can be used in an iframe like this:

<iframe src="https://ais.bisnode.com/psd2-auth-link-web/v1/auth?redirect_uri=CALLBACK_URL&app_id=APPLICATION_ID&mode=iframe&scope=SCOPE&market=MARKET&locale=LOCALE&test=TEST&username=tink">

The same usage is for simple HREF:

<a href="https://ais.bisnode.com/psd2-auth-link-web/v1/auth?redirect_uri=CALLBACK_URL&app_id=APPLICATION_ID&scope=SCOPE&market=MARKET&locale=LOCALE&test=TEST&username=tink">

Step 3

After successful user authentication, your application will have a code available (from the previous step). This code needs to be exchanged at /token endpoint.

Note:
Every subsequent call also must have an Authorization: Bearer eyJhb...seAtPCCQ header. See the Authentication section above.

GET /token
Token query parameters:

response:

{
    "token": {
        "accessToken": "eyJhbGciOiJFUzI1NiIsImtpZCI6IjMxOWRjYTQx79MwMGItNDBmZi1hYzY4LTFiNzFjYmEwZjZkMCIsInR5cCI6IkpXVCJ9.e4pleHAiOjE1ODc2MzQzOTEsImlhdCI6MTU4NzYyNzE5MSwiaXNzIjoidGluazovL2F1dGgiLCJqdGkiOiJlNWY2MzdmYy0yZTMxLTQwNTktYWYyZi1jNzk4MDk5OTVhMDUiLCJvcmlnaW4iOiJtYWluIiwic2NvcGVzIjpbImNhdGVnb3JpZXM6cmVhZCIsInN0YXRpc3RpY3M6cmVhZCIsImFjY291bnRzOnJlYWQiLCJ0cmFuc2FjdGlvbnM6cmVhZCJdLCJzdWIiOiJ0aW5rOi8vYXV0aC91c2VyLzZjNGY1YTE2NjBjZDRhMGFhMmMxZWFkY2E1NmQxYzM0IiwidGluazovL2FwcC9pZCI6ImUxMTJiYjQ3YzI3YzRmN2FiMGZjMDg3ZGRlNzM5ZjY5In0.fKhJtCK8cAciV2ajmVbTTzMRJy0snpmsOviJ023MHreFwOagbhpX3ItSuwzGjg7ecaNfK-h5METJrFTG-odg4A",
        "tokenType": "bearer",
        "expiresIn": 7200,
        "refreshToken": "4cf6c2ec3f6641ad855095fda6dbded8",
        "scope": "categories:read,statistics:read,accounts:read,transactions:read"
    }
}

Step 3

With this access token, we can fetch data from "Provider" APIs. For income verification flow, we can use /account/transactions. 

A list of transactions can be found in /account/transactions.

Example query

GET /account/transactions
Headers:

Query parameters:

 Example response:

{
  "metrics": {
    "COUNT": "1106",
    "NET": "-5046376.59",
    "SUM": "5172376.59",
    "AVG": "4676.651528028933"
  },
  "transactions": [
    {
      "amount": -41256.0,
      "date":"2019-07-27T10:00:00",
      "inserted": "2019-07-27T10:00:00",
      "lastModified": "2019-07-27T10:00:00",
      "description": {
        "info": "Apple Retail",
        "type": "EXPENSES",
        "primaryName": "Shopping",
        "secondaryName": "Electronics"
      },
      "currencyDenominatedAmount": {
        "unscaledValue": -412560,
        "scale": 1,
        "currencyCode": "SEK"
      },
      "currencyDenominatedOriginalAmount": {
        "unscaledValue": -412560,
        "scale": 1,
        "currencyCode": "SEK"
      }
    },
    ...
  ]
}

These error statuses can be recieved during end-user consent process:

INTERNAL_ERROR

PROVIDER_ERROR

USER_CANCELLED

BAD_REQUEST

API version is provided in the base of the requested URL in the form of "v1", "v2" etc. Only major version numbers are used.

API versions are raised only on breaking (i.e. backwards incompatible) changes in the API. Fields may be added but will never be removed during an API version lifecycle. When developing your application, take care to ensure that your application is able to handle additional fields.