Account Information Service (AIS)

LUXHUB One provides a unified interface to access the PSD2 APIs of multiple providers, establishing a common data model, security profiles and authorization flows to overcome the complexities caused by differing implementation standards.

Therefore, as a consumer of LUXHUB One, you are able to seamlessly integrate the APIs of various PSD2 providers and thus provide easy access to PSD2 account information  (AIS) and payment initiation services to your customers.

In this tab you will find an explanation on AIS flow and implementation details:

• Introduction
• AIS flow
• Transactions older than 90 days
• API calls
  
  • Getting a list of providers
  • Creating a global permission
  • Retrieving a list of accounts
  • Creating a detailed permission
  • Retrieving a list of transactions of an account
  • Getting the balances of an account
  • Additional API calls

Please refer to "Documentation" tab for general implementation details prior to reviewing AIS implementation details below.

Introduction

LUXHUB One enables access, analysis and consolidation to an individual or SME's account data from their bank or other financial institution (e-money wallet provider for e.g.) with their explicit consent. This data could be a list of accounts, a specific account’s balance or the list of incoming and outgoing transactions on a specific account.

Popular services include account aggregation apps that group various online banking accounts under a single user interface, or real-time credit scoring based on cash account movements, but it will be up to you to decide how to use the account information you obtain via LUXHUB One API.

The PSD2 regulation requires that the access to account information is limited to information for which the end customer has issued the order and authorisation of, and which is required within the scope of the service to be performed.

AIS flow

1. End-user initiates an account information request. It is assumed that the end user is already logged into the consumer system.

2. Consumer shows the list of available providers (obtained from LUXHUB One) to the end-user. LUXHUB One will return only providers setup for your organisation out of all supported providers.

3. End-user chooses the provider to whom he wants to connect to recover account information.

4. Consumer presents a consent request capture page towards the end-user. Once the user confirms that he wants to authorize the consent, the consumer initiates a consent request for the respective provider. According to provider type, this might mean an additional request for establishing consent in the provider system - made transparently by LUXHUB One - or may take the end-user directly to the consent authorization page.

5. End-user performs the strong customer authentication (SCA) in the realm of the provider, thus granting authorization to LUXHUB One - and through it to the consumer - to access his account information.

6. Following the successful SCA, LUXHUB One receives an authorization code to be exchanged for the access/refresh tokens.

7. The PSD2 API provider issues an access/refresh tokens pair that will be used by LUXHUB One, identifying itself as consumer, for accessing the end-user account information.

8. LUXHUB One creates a consumer token, identifying the consumer, provider, end-user authorized relation - and provides it to the consumer. Each of the LUXHUB One API calls made by the consumer will have to use this token in a header in order to identify the resources to be accessed and also to show that access was authorized by the end-user. This token is bound - 1-to-1 - to an access token, as received from a provider.

9. The consumer makes a LUXHUB One API call to request a specific account information.

10. LUXHUB One extracts the necessary info from the consumer token that was sent, identifies the corresponding access token for the respective provider to which the request is addressed and forwards the call to the respective provider with the access token as authorization bearer token.

11. The provider verifies that the access to account information for the respective user is authorized and returns the relevant account information.

12. Account information is sent to the Consumer in the format specified by the LUXHUB One API. 

Transactions older than 90 days

When LUXHUB One is requesting the consent for account information, it adds the scope for extended transaction history too. This way, when the end-user is authorizing the consent for AIS, it is also doing it for extended transaction history (the end-user will be warned about it during consent authorization at provider side). Some providers do not allow this and a second consent authorization is needed with extended transaction history scope. In this case, LUXHUB One will respond with a 302 (/accounts/{accountId}/transactions endpoint), including a Location header with the URL for the SCA to authorize the consent with extended transactions history scope for older than 90 days.

API calls

Note: the client credentials access token (Oauth2 credentials) obtained from the developer portal during the onboarding process must be added to every call made to LUXHUB One API through header “Authorization”. E.g.: Authorization: Bearer ACCESS_TOKEN. 

Getting a list of providers

To retrieve a list of providers you will need to make a call to [GET] /providers endpoint. Below an example of how to retrieve provider list.

curl –location –request GET ‘https://apis-sbx.luxhub.com/oneapi/v1/providers’

Creating a global permission

When connecting a user, a permission needs to be created in order to get a list of user's accounts managed by the provider.

You will need to use [POST] /users/{userId}/permissions endpoint to create a new permission.

The user will be redirected to his chosen provider and will perform SCA. Upon successful SCA with the provider, the permission will move to an authorized status and grant access to the user’s account list.

This call returns the details of the permission, including the URL where the user will be redirected for permission authorization.

Please find below and example using cURL.

curl –location –request POST ‘https://apis-sbx.luxhub.com/oneapi/v1/users/{userId}/permissions’ \
--header ‘Digest: {the calculated digest (see calculate digest section)}’ \
--header ‘Date: Mon, 22 Jun 2020 12:25:30 GMT’ \
--header ‘Signature: {the calculated signature (see message signing section)}‘\
--header ‘X-Request-ID: 6d8bcdd1-f172-4582-bf78-ae51f4b361b9’ \
--header ‘TPP-Signature-Certificate: {the certificate downloaded from portal}’ \
--header ‘Content-Type: application/json’ \
--data-raw ‘{“BIC”: “DEMOLULLLBG”}’

Please note that userId parameter refers to the user id in your application.

As response you will receive the following structure:

{
  “BIC”: “DEMOLULLLBG”,
  “authorization_uri”: “the SCA url”,
  “permissionId”: “the permission id”,
  “status”: “received”
}

You must store the created permission since it will be required to request the list of accounts of the user on the given provider.

You also must redirect the user to the URL you received in property authorization_uri. On that page the user will be requested to enter his credentials and grant access to his accounts.
After completing the SCA, the user will be redirected to the callback url you have provided as part of your onboarding.

Retrieving a list of accounts

To retrieve a list of user's accounts, you will need to make a call to [GET] /accounts endpoint while informing the provider BIC code, user id and permission id.
Another important information to provide is header PSU-IP-Address. When IP address is not provided, consumers will be able to make only 4 requests per day.

Please find below an example.

curl –location –request GET ‘https://apis-sbx.luxhub.com/oneapi/v1/accounts’ \
--header ‘LH-BIC-Provider: DEMOLULLLBG’ \
--header ‘LH-USER-Id: {the user id}’ \
--header ‘LH-Token-Information: {the permission id}‘ \
--header ‘X-Request-ID: 6d8bcdd1-f172-4582-bf78-ae51f4b361b9’ \
--header ‘Signature: {the calculated signature (see message signing section)}’ \
--header ‘TPP-Signature-Certificate: {the certificate downloaded from portal}’ \
--header ‘Date: Mon, 22 Jun 2020 12:25:30 GMT’ \
--header ‘PSU-IP-Address: 127.0.0.1’

As response you will receive the following structure:

{
  “accounts”: [
    {
      “accountId”: {
        “bban”: “BARC12345612345678”,
        “currency”: “EUR”,
        “iban”: “PT50000201231234567890154”,
        “maskedPan”: “123456xxxxxx1234”,
        “msisdn”: “+49 170 1234567”,
        “pan”: “5409050000000000”
      },
      “bicFi”: “SCOEFR21XXX”,
      “name”: “My cash account”,
      “resourceId”: “6004924001000001”,
      “type”: “CACC”
    }
  ]
}

Then you will need to present to the user the list of accounts that you just obtained.

The user will choose one or several accounts that he allows you to retrieve the information on his behalf.

After that you will need to create a detailed permission to access information of those accounts.

Creating a detailed permission

In order to grant access to transactions and balances of a given account, consumers must request a detailed permission as specified by most of providers.

The request is similar to global permission, but now consumer informs the provider to which accounts it needs access to transactions and balances.

curl –location –request POST ‘https://apis-sbx.luxhub.com/oneapi/v1/users/{userId}/permissions’ \
--header ‘Digest: {the calculated digest (see calculate digest section)}’ \
--header ‘Date: Mon, 22 Jun 2020 12:25:30 GMT’ \
--header ‘Signature: {the calculated signature (see message signing section)}‘\
--header ‘X-Request-ID: 6d8bcdd1-f172-4582-bf78-ae51f4b361b9’ \
--header ‘TPP-Signature-Certificate: {the certificate downloaded from portal for the signature}’ \
--header ‘Content-Type: application/json’ \
--data-raw ‘{See sample request body below}’

In order to request detailed permission, the payload must look like following example:

{
  “BIC”: “DEMOLULLLBG”,
  “accountAccess”: {
    “accounts”: [
      {
        “currency”: “EUR”,
        “iban”: “PT50000201231234567890154”
      }
    ],
    “balances”: [
      {
        “currency”: “EUR”,
        “iban”: “PT50000201231234567890154”
      }
    ],
    “transactions”: [
      {
        “currency”: “EUR”,
        “iban”: “PT50000201231234567890154”
      }
    ]
  }
}

As response you will receive same structure as global permission. You must store the permission id in order to get balances and transactions of the said accounts.

Retrieving a list of transactions of an account

In order to request transactions of an account, you must create a detailed permission in advance. 

Once this is done, you can use [GET] /accounts/{accountId}/transactions endpoint to retrieve the transactions of a given account identified by accountId parameter.

The value of accountId parameter must be the value of property resourceId retrieved when calling /accounts.

Just like /accounts endpoint, you must inform provider BIC code, user id and permission id.

Please find below an example.

curl –location –request GET ‘https://apis-sbx.luxhub.com/oneapi/v1/accounts/{accountId}/transactions?bookingStatus=both’ \
--header ‘LH-BIC-Provider: DEMOLULLLBG’ \
--header ‘LH-USER-Id: {the user id}’ \
--header ‘LH-Token-Information: {the permission id}‘ \
--header ‘X-Request-ID: 6d8bcdd1-f172-4582-bf78-ae51f4b361b9’ \
--header ‘Signature: {the calculated signature (see message signing section)}’ \
--header ‘TPP-Signature-Certificate: {the certificate downloaded from portal}’ \
--header ‘Date: Mon, 22 Jun 2020 12:25:30 GMT’ \
--header ‘PSU-IP-Address: 127.0.0.1’

As response you will receive the following structure:

{
  “transactions”: [
    {
      “bookingDate”: “2020-09-18”,
      “creditorAccount”: {
        “currency”: “EUR”,
        “iban”: “PT50000201231234567890154”
      },
      “creditorName”: “Creditor Name”,
      “debtorAccount”: {
        “currency”: “EUR”,
        “iban”: “PT50000201231234567890154”
      },
      “debtorName”: “Debtor Name”,
      “entryReference”: “string”,
      “remittanceInformation”: {
        “additionalInformation”: “some additional information”,
        “structured”: [
          “structured value 1”,
          “structured value 2”
        ],
      “resourceId”: “6004924001000001”,
      “status”: “BOOK”,
      “transactionAmount”: {
        “amount”: “12.25”,
        “currency”: “EUR”
      },
      “type”: “CRDT”,
      “valueDate”: “2020-09-18”
    }
  ]
}

Getting the balances of an account

In order to request balances of an account, consumers must create a detailed permission in advance. 

After that, [GET] /accounts/{accountId}/balances endpoint can be used to return the balances of a given account identified by accountId parameter.

The value of accountId parameter must be the value of property resourceId retrieved when calling /accounts.

Just like /accounts endpoint, consumers must inform provider BIC code, user id and permission id.

Please find below an example.

curl –location –request GET ‘https://apis-sbx.luxhub.com/oneapi/v1/accounts/{accountId}/balances \
--header ‘LH-BIC-Provider: DEMOLULLLBG’ \
--header ‘LH-USER-Id: {the user id}’ \
--header ‘LH-Token-Information: {the permission id}‘ \
--header ‘X-Request-ID: 6d8bcdd1-f172-4582-bf78-ae51f4b361b9’ \
--header ‘Signature: {the calculated signature (see message signing section)}’ \
--header ‘TPP-Signature-Certificate: {the certificate downloaded from portal}’ \
--header ‘Date: Mon, 22 Jun 2020 12:25:30 GMT’ \
--header ‘PSU-IP-Address: 127.0.0.1’

As response you will receive the following structure:

{
  “balances”: [
    {
      “balanceAmount”: {
        “amount”: “123.45”,
        “currency”: “EUR”
      },
      “balanceType”: “CLBD”
    }
  ]
}

Now that you obtained transactions and balances of a specific account, you can display the information in your application.

Additional API calls

Please refer to the "Endpoints" tab for a full list of API operations.