Andbank

Andbank XS2A (Berlin Group)

Version:  1.13220190215.037.005
State:  Prototyped
Environment: Sandbox
Base URI: https://bacalull-psd2api-sbx.luxhub.com/bg/v1
Authorization Endpoint: https://bacalull-cb-sbx.luxhub.com/api/oauth/authorize
Token Endpoint: https://bacalull-psd2api-sbx.luxhub.com/api/oauth/token
Categories: PSD2
Passport :

Account Information Services (AIS)

All APIs are protected by OAuth2 authorization. To receive authorization & access tokens, the PSU has to give consent for the application to access his resources - in case of Account Information Services (AIS) these are: accounts, balances and transaction history. The PSU authentication is required to be a Strong Customer Authentication (SCA), i.e. at least two factors, and to be done in the ASPSP (bank) realm.

Depending on each bank, the application might have to implement a different consent management flow. Please refer to the API documentation to discover which consent flow is supported by the Bank you have chosen.

According to PSD2 directive, it is the TPP’s (this means “your”) responsibility to ensure that a PSU has all required information when he gives consent to an application to access his financial data.

Consent

To access a PSU’s account, you have to obtain the PSU’s consent beforehand, in order to access his accounts.

First, the PSU has to select a bank in your application. Once this is done, you have to show to the PSU a clear description of which data you would like to access from his bank.
This is what we call the scope of the consent.

Next, the PSU has to authorize this consent. This process depends on the API specification and consent model implemented by the PSU’s bank.
Below, you will find the required requests to be executed until you have a valid consent to access a PSU’s account data.

These requests are not directly covered by the PSD2 Specification, but they are derived from other standards such as OAuth2.
For the actual PSD2 requests, you can look at the API specifications and at the official documentation of the PSD2 API standards supported by the LUXHUB platform:

Berlin Group - current supported version is 1.3 20190215

This diagram shows the requests to be performed in the case where an API requires Berlin Group’s Global Consent Model as well as the first part of Berlin Group’s Detailed Consent Model.
The requests shown in yellow are explained in detail below.

It is to be noted for Berlin Group specifications that the Consent resource management and lifecycle is fully separated by the lifecycle and management of the Authorisation resource. Basically the Authorisation resource is used for authorizing the Consent resource, hence the Authorisation resource endpoints need to be protected by Authorization Code Grant, which involves PSU authentication, whereas Consent resource can be protected by Client Credentials Grant only. This kind of approach will allow for the Consent resource, and its status, retrieval by the TPP even before authorization by the PSU. Similarly, as will be explained later, payment flows will benefit also on the TPP being able to retrieve Payment Initiation, and dependent entities like Authorisation, before authorization by the PSU. This way simple management of implicit and explicit authorisation flows can be achieved. Signing Baskets flows will also benefit from the same feature.

The flow presented below in details, and in the diagram above, is a reference flow suggested by LUXHUB and not the only possible one. It is designed to show most of the complexities of the scenarios possible during the PSD2 consent authorization for Berlin Group standard implementation.

For illustrating flows described in this document we will use cURL, which is an utility present on the majority of operating systems allowing for fast testing of the API authorization and endpoints. Some requests will not contain verbatim all parameters needed or not all parameters will be explained in details, for the sake of simplicity.

For all request, please use the appropiate QWAC and/or QSeal certificates, either real eIDAS ones provided by a QTSP or mock ones downloaded from LUXHUB Developer Portal. In the case of mock certificates, the following file naming is used:

QWAC: QWAC-cert.pem and respectively QWAC-key.pem

QSeal: QSeal-cert.pem and respectively QSeal-key.pem

For exhaustive details on what and how all parameters of a certain request should be set, as well as for exact definitions of the responses to be expected from the API, please consult the swagger documentation of each respective API.

 

1. Request a token according to the OAuth2 client credentials grant. This token allows you to create a consent resource.

  • example request:
curl \
             -H 'Authorization: Basic ' \
             -H 'Content-Type : application/x-www-form-urlencoded' \
             -H 'X-Request-ID: 12345678-1234-1234-1234-1234567890ab' \
             -d 'grant_type=client_credentials&scope=AIS' \
             -X POST 'https://<Token Endpoint>' \
             --cert QWAC-cert.pem --key QWAC-key.pem​

2. Create a consent resource which allows you to retrieve further information about the accounts of a PSU. Depending on the supported consent model by the ASPSP:

· global consent model: you can use this consent - once authorized - to retrieve the details of the PSU’s accounts.

· detailed consent model: you can use this consent - once authorized - to retrieve the list of the PSU’s accounts.
At this moment in its life cycle, the consent is not yet bound to a PSU. The access to this resource is controlled via the access token obtained in step 1.

example request for (detailed consent):

curl \
             -H 'Signature: ' \
             -H 'Authorization: Bearer ' \
             -H 'X-Request-ID: 12345678-1234-1234-1234-1234567890ab' \
             -H 'Content-Type: application/json' \
             -d '{"access":"availableAccounts":"allAccounts"},"recurringIndicator":false,"validUntil":"2019-03-14","frequencyPerDay":4,"combinedServiceIndicator":false}' \
             -X POST 'https://<Base URI>/consents' \
             --cert QWAC-cert.pem --key QWAC-key.pem

 

  • example request (global consent):
curl \
             -H 'Signature: ' \
             -H 'Authorization: Bearer ' \
             -H 'X-Request-ID: 12345678-1234-1234-1234-1234567890ab' \
             -H 'Content-Type: application/json' \
             -d '{"access":{"allPsd2":"allAccounts"},"recurringIndicator":false,"validUntil":"2019-03-14","frequencyPerDay":4,"combinedServiceIndicator":false}' \
             -X POST 'https://<Base URI>/consents' \
             --cert QWAC-cert.pem --key QWAC-key.pem

3. Redirect the PSU to the SCA for authentication and authorization of the consent. This step will bind the consent to a PSU. Further API calls will be authorized based on access token received as a result of OAuth2 Authorization Code Grant, i.e. after PSU authentication in bank system. After consent authorization, the respective consent resource is bound to the PSU that authorized it.

  • example request:
curl \
         -X GET 'https://<Authorization Endpoint>?response_type=code&scope=AIS:<consent_id>&client_id=<client_id>&redirect_uri=http%3A%2F%2F127.0.0.1%3A9003%2Fredirect&state=12345678-1234-1234-1234-1234567890ab&code_challenge=<code_challenge_pkcs>&code_challenge_method=S256'

 

 

4. Your application has to retrieve the OAuth2 authorization code. Strong Customer Authentication of the PSU is required as part of this step. After SCA, the PSU is redirected back to the TPP application.
Your application should use the parameters specified below.
You can try this redirection by pasting the GET request from step 3 into your browser (you have to configure your browser to use the Mock Certificate for its requests) while ensuring that your application is listening at the specified redirection URL.

 

  • example request:

    curl \
                 -X GET 'http://127.0.0.1:9003/redirect?code=<authorization_code>'​

 

 

5. Once you have received the authorization code, you can ask for OAuth2 access and refresh tokens to access the /accounts resource.

    • example request:

      curl \
                   -H 'Authorization: Basic ' \
                   -H 'Content-Type : application/x-www-form-urlencoded' \
                   -d 'grant_type=authorization_code&redirect_uri=http%3A%2F%2F127.0.0.1%3A9003%2Fredirect&code=&scope=AIS:<consent_id>' \-X POST 'https://<Token Endpoint>' \
                   --cert QWAC-cert.pem --key QWAC-key.pem​

     

    6. (detailed model only) You have a valid consent you can use to retrieve a list of accounts on the /accounts endpoint
    The list of accounts has to be shown to the PSU to allow him to select the accounts he wants to give consent to.
    • example request:

      curl \
                   -H 'Signature: ' \
                   -H 'Authorization: Bearer ' \
                   -H 'Consent-ID: ' \
                   -H 'X-Request-ID: 12345678-1234-1234-1234-1234567890ab' \
                   -X GET 'https://<Base URI>/accounts \--cert QWAC-cert.pem --key QWAC-key.pem​
  1.  

7. (detailed model only) Once the PSU has selected the accounts, you have to create a new consent resource which allows you to retrieve details for the chosen accounts of the PSU.

    • example request:

      curl \
                   -H 'Signature: ' \
                   -H 'Authorization: Bearer ' \
                   -H 'X-Request-ID: 12345678-1234-1234-1234-1234567890ab' \
                   -H 'Content-Type: application/json' \
                   -d '{"access":{"accounts":[{"iban":"FR7612345987650123456789014"}],"balances":[{"iban":"FR7612345987650123456789014"}],"transactions":[{}]},"recurringIndicator":true,"validUntil":"2019-03-14","frequencyPerDay":4,"combinedServiceIndicator":false}' \
                   -X POST 'https://<Base URI>/consents' \
                   --cert QWAC-cert.pem --key QWAC-key.pem​

     

8. (detailed model only) You have to repeat the request to /api/oauth/authorize as you did already in step 3, but using the consent ID obtained in step 7.

9. (detailed model only) You have to repeat the request to the redirect URL as you did already in step 4, but using the authorization code obtained in step 8.

10. (detailed model only) You have to repeat the request to /api/oauth/token as you did already in step 5, but using the authorization code obtained in step 8/9.

11. You are now ready to call the /accounts resource with all details according to the scope of the TPP’s consent.

  • example request:

    curl \
                 -H 'Signature: ' \
                 -H 'Authorization: Bearer ' \
                 -H 'Consent-ID: ' \
                 -H 'X-Request-ID: 12345678-1234-1234-1234-1234567890ab' \
                 -H 'Content-Type: application/json' \
                 -X GET 'https://<Base URI>/accounts' \
                 --cert QWAC-cert.pem --key QWAC-key.pem​

 

 

It is worth noting that the Berlin Group specifications provide separate endpoints for card accounts and related entities access - however, the authorization grants used are the same like in case of regular payment accounts.

 
 

This website uses cookies. By continuing to use our website, you accept the use of these cookies.