Getting started

Sign up

The first thing you need to do is to create an account and then sign in. You need to have an account to test the integration of Länsförsäkringar’s APIs in your applications.

Create an App

Once you are logged in, the next step is to configure your Apps. The Apps keep track of your credentials for using our APIs. For each App and each version of an App, a Client ID and a Client Secret will be created.

When your app has been created, you will see your Client ID/App ID and Shared Secret. Copy it and place it for safe keeping.

After your App is created, to be able to test an API, the App needs to gain access. Click on APIs, select an API, click on Access, select the version of the app that you want the access for, click on the radio button under ADD, click on Next and then click on Save.

Testing using Test Client

It is possible to test the APIs by using the Test Client in the Developer Portal. The Test Client can be found by navigating to your app.

1. Click on Test Client under the App menu and select which version of the app to use.
2. Select the API and operation.
3. Add information in Headers and Parameters. (Since the Test Client is using an internal OAuth server for testing, the header Authorization does not need to be set and can be removed.)
4. Click on Setup and then press save.
5. Click on Security, press on Get Token and then Next.
6. Click on Finish.
7. Click on Invoke.

Test using postman

Postman is a great tool to use when testing Länsförsäkringar APIs.

You can call the OAuth2 service in Postman to create an access token. This is needed when testing the APIs.

The URLs for the APIs can be found in Developer Portal when navigating to the APIs.

Purpose of documentation

The purpose of this document is to provide information regarding the APIs implemented in the Sandbox and how the APIs in this version might differ from the Live implementation. The guide also contains information regarding how to test the APIs in the Sandbox.

Sandbox overview

The Sandbox consists of static mocked data. The design of the APIs is influenced by the standards of the Berlin Group 1.2. The Account Information API, Payment Initiation API, Confirmations of Funds API, Consent API and Consent Anonymous API are implemented in the Sandbox.

Testing the APIs

The APIs can be tested through the Test Client in the Developer Portal or by reaching the endpoints from other apps or testing tools.

If using the Test Client in the Developer Portal, you start by creating an App and connecting the App to the APIs you want to test. In the Test Client, you select the API and the operation/service you want to test and add the necessary input (i.e. headers and parameters etc.).

For each request to execute a service (except the Consent Anonymous API), you need to include an authorization token. The token can be created in the Test Client, either by executing the token service API or by setting up the Authorization each time another service is executed. See paragraph Create an access token with Token Service.

Authorization

The APIs are using OAuth2 for authorization, which means that you will need to provide an access token for each API request.

Create an access token with Token Service

To get an access token you need to provide your “App ID” and “Shared Secret”, both of those values are unique to each registered App in the Developer Portal. The credentials are provided to the /v1/oauth2/token endpoint to retrieve an access token.

In the example below “LFBank-4PWAM7XwQcTAJq7FmjyGHF3W“ is the App ID and “da54e197aaeba64b851917fd098c6c8a704cfe26%0A“ is the Shared Secret.

To find the information about your App ID and Shared Secret, go to the “Details page” of your App in the Developer Portal.

Base path https://sandbox.bank.lansforsakringar.se:443

HTTP/1.1 200 OK - Response

{
    “access_token” : “Og6G1pL0Vkf5X0d9PZ5TyMXoEVjqW2ePn80VMMay”,
    “token_type” : “Bearer”,
    “expires_in” : 300
}

The received access token can now be used to call the other APIs. The token is of type “Bearer” and should be placed in the Authorization HTTP header (this needs to be provided when using other testing tools than the Test Client). An example is stated below.

Create an access token in the Test Client

In the Test Client, an access token can be created by calling the service as the following procedure:

1. Select API and operation
2. Delete Authorization header
3. Add input for remaining required headers
4. Click on Setup and select the correct App.
5. Click on Security and Get Token → Next → Finish
6. Click on Invoke

The access token can be found under Request Header.

It is possible to add a token in the Authorization header in Test Client again by filling in the value from Authorization token from request header. By calling the service this way two access tokens will be added in the call.

Invalid Access Token

The access token is valid for 5 minutes. Calling the service with a token that has expired will return 401 Unauthorized - 1012116 - Invalid token and calling the service without a token will return 401 Unauthorized - 1012100 - Credentials invalid or missing.

API Overview

List of APIs

The following APIs are implemented in the Sandbox. They are implemented as RESTful JSON.

Account Information API

• GET /openbanking/ais/v1/accounts
• GET /openbanking/ais/v1/accounts /{account-id}
• GET /openbanking/ais/v1/accounts /{account-id}/balances
• GET /openbanking/ais/v1/accounts /{account-id}/transactions

Payment Initiation API

• GET /openbanking/pis/v1/account-numbers

• POST /openbanking/pis/v1/payments/cross-border-credit-transfers
• POST /openbanking/pis/v1/payments/domestic-giros
• POST /openbanking/pis/v1/payments/domestic-credit-transfers
• POST /openbanking/pis/v1/payments/{paymentId}/authorisations
• GET /openbanking/pis/v1/payments/{paymentId}
• GET /openbanking/pis/v1/payments/{paymentId}/status
• GET /openbanking/pis/v1/payments/{paymentId}/authorisations
• GET /openbanking/pis/v1/payments/{paymentId}/authorisations/{authorisationId}
• DELETE /openbanking/pis/v1/payments/{paymentId}

• POST /openbanking/pis/v1/periodic-payments/domestic-credit-transfers
• POST /openbanking/pis/v1/periodic-payments/{paymentId}/authorisations
• GET /openbanking/pis/v1/periodic-payments/{paymentId}
• GET /openbanking/pis/v1/periodic-payments/{paymentId}/status
• GET /openbanking/pis/v1/periodic-payments/{paymentId}/authorisations
• GET /openbanking/pis/v1/periodic-payments/{paymentId}/authorisations/{authorisationId}
• DELETE /openbanking/pis/v1/periodic-payments/{paymentId}

• POST /openbanking/pis/v1/signing-baskets
• POST /openbanking/pis/v1/signing-baskets/{basketId}/authorisations
• GET /openbanking/pis/v1/signing-baskets/{basketId}
• GET /openbanking/pis/v1/signing-baskets/{basketId}/authorisations
• GET /openbanking/pis/v1/signing-baskets/{basketId}/authorisations/{authorisationId}

Confirmation of Funds API

• POST /openbanking/cbpii/v1/funds-confirmations

Consent Anonymous API

• POST /openbanking/ano/v1/consents
• POST /openbanking/ano/v1/consents/{consentId}/authorisations

Consent API

• GET /openbanking/sec/v1/consents/{consentId}
• GET /openbanking/sec/v1/consents/{consentId}/status
• GET /openbanking/sec/v1/consents/{consentId}/authorisations/{authorisationId}
• DELETE /openbanking/sec/v1/consents/{consentId}

TPP roles

In the Sandbox, the TPP will have the role PIS and AIS and therefore have access to all AIS and PIS services.

Limitations in the Sandbox

In the current version of the Sandbox, only happy cases are implemented, meaning that when a service is executed correctly a code of either 200 (Ok) or 201 (Created) is returned. If incorrect input is provided to the service, a 404-code will be returned with a response body:

{
 "tppMessages": [
  {
   "code": "RESOURCE_UNKNOWN",
   "text": "",
   "category": "ERROR"
  }
 ]
}

There are limitations of information of why the error has occurred, it could be either an invalid header or an invalid parameter etc.

In Sandbox, there is limited validation of the headers. All headers that are listed as required in the API description for each service should not be null but if so, a 404-error message will be returned. When Consent-ID is listed as a required header in the API description, it is implemented with a fixed preset UUID and is listed in Table 1 below. The Authorization header requires to be of the format “Bearer {generated token}”.

Request headers Accept and Content-Type do not need to be set. But if set, they should have value application/json.

There is a validation of the path parameters, which requires that the path parameters must correspond to the implementation in the request. A list of path variables and their values are found in Table 2. The POST services will also return these ids or IDS of the path parameters when executing the services in the Sandbox.

There is also a validation of the parameters (query parameters), and those are described in the documentation of each service. In the documentation, it is listed which different values a parameter could obtain.

For some of the POST services, it is required to input a request body. All required parameters in request.body need to be specified. Most of the parameters are implemented as regex, meaning that it requires the input to follow the structure specified in the API description. For example, a date needs to be of format “YYYY-MM-DD” and will return a 404-error message if specified in another format. As the Sandbox consists of mocked data, despite what the request body consists of, the same mocked data will be returned as a response, which means that the response will be the same despite which date is send in the request.

In the table below, there is a request.body example for each POST service (when body is required) that will generate a happy case.

{
    "debtorAccount":
    {
        "bban": "11111111111",
        "currency": "SEK"
    },
        "creditorAccount":
    {
        "bban": "222222222222",
        "currency": "SEK"
    },
        "instructedAmount":
    {
        "currency": "SEK",
        "amount": 700.00
    }
}

{

    "debtorAccount":
    {
        "bban": "11111111111",
        "currency": "SEK"
    },
        "creditorAccount":
    {
        "number": "1234-1234"
    },
        "instructedAmount":
    {
        "currency": "SEK",
        "amount": 99.99
    }
}

{

    "paymentType": "SEPA",
    "requestedExecutionDate": "2022-01-01",
    "debtorAccount":
    {
        "bban": "11111111111",
        "currency": "SEK"
    },
    "creditorAccountIban":
    {
        "iban": "DE23100120020123456789",
        "currency": "SEK"
    },
    "instructedAmount":
    {
        "currency": "SEK",
        "amount": 700.00
    },
    "creditorName": "Anna Andersson",
    "creditorAddress":
    {
        "street": "Strasse",
        "city": "Berlin",
        "country": "Germany"
    }
}

{
    "debtorAccount":
    {
        "bban": "222222222222",
        "currency": "SEK"
    },
    "creditorAccount":
    {
        "bban": "11111111111",
        "currency": "SEK"
    },
    "instructedAmount":
    {
        "currency": "SEK",
        "amount": 1000.00
    },
    "startDate": "2021-01-01",
    "frequency": "MONTHLY"
}

{
    "paymentIds": ["i_4mSjb1Po08U8nQDHEBy2XYIqbbDRqPVcOc1jk _t4X", "L_1aAo15POaS6PXIsClaOb1l1AlTMc6iFAauii2_A09"]
}

{
    "account": {
        "bban": "222222222222",
        "currency": "SEK"
    },
    "instructedAmount": {
        "currency": "SEK",
        "amount": 700.22
    }
}

Other information

The SCAOauth-link in the mocked responses does not exist, this due to the limitations of the Sandbox implementation. For the Live implementation, it will return a valid link in the response.

Please note that all links in the response will per default redirect to GET operations. Meaning that if a POST operation is executed and one link in the response is a further POST operation, this change must be done manually.

Postman Collection

The attached folder is a postman collection and it is an example of how to execute the different services. Sandbox 1.0.postman_collection.zip