Get started

Your organization

Within LUXHUB’s Developer Portal, an organization is a group of registered users belonging to the same company. Each member of an organization can share applications with other members, modify application names, view monitoring results of the shared applications and access application security credentials.

All developers of the same company registered to the LUXHUB Developer Portal will belong to the same organization.

1. Security

eIDAS Certificates considerations

The eIDAS certificates referred to in this guide are regular certificates with dedicated protection profiles that allows to be used in the PSD2 context. To achieve the PSD2 security requirements, banks and PSD2 service providers will use Qualified Certificates for Websites and Qualified Certificates for Electronic Seals. Those certificates will be issued by Qualified Trust Service Providers (QTSPs) based on the new technical standard, ETSI TS 119 495, which was published in May 2018. Qualified Certificates enable identification and verification of the payment institution by a third party. Identification will be based on the legal name of an organization, registration number and its main role(s) in the payments space.

There are two types of such certificates:

• QWAC (Qualified Website Authentication Certificate): used as Client Certificates in MA-TLS
• QSeal (Qualified Certificate for Seals) : used to sign requests using http-signature

All PSD2 APIs require both types of certificates, QWAC to access the API and QSeal for http-signature, i.e. message signing.

LUXHUB implementation of certificates

Our PSD2 APIs are protected by Mutual TLS protocols based on eIDAS Certificates, as required by the PSD2 European Directive. This means that if you want to access one of our PSD2 APIs, you need to use an eIDAS TLS Client Certificate for your requests. If you don’t have such a certificate, you can download a mock eIDAS Certificate from our Developer Portal (Log in, then go to Applications -> select Application -> Download QWAC Certificate). Our mock certificate nevertheless only allow access to Sandbox APIs. To access production, you need to get your own PSD2 eIDAS Certificate from a Qualified Trust Service Provider.

At the application level, the PSD2 APIs require message signing following http-signature specification, with the signing QSeal certificate (different from the one used as client Certificate). To access the Sandbox, we also provide you such a mock certificate for message signing. The download QSeal certificate button is located just next to the one for downloading a QWAC Certificate.

2. Access Management

Our APIs use OAuth2 as authorization mechanism for access management to the endpoints. The main points related to the implementation of OAuth2 in the context of PSD2 APIs are presented below.

API Authorization

Berlin Group specifications do not impose any specific authorization framework to be used, whereas STET specifications specifically mentioned OAuth2 as authorization mechanism. Therefore, LUXHUB decided to employ state of the art authorization by protecting all endpoints via OAuth2 authorization. Please consult RFC 6749 for more details about this authorization framework.

Authorization Code Grant

The most used flow is Authorization Code grant, which allows PSU to authorize (give consent) to its resources in a secure manner. The authorization code provides a few important security benefits, such as the ability to authenticate the client, as well as the transmission of the access token directly to the client without passing it through the resource owner’s user-agent and potentially exposing it to others, including the resource owner. [https://tools.ietf.org/html/rfc6749#page-24]

Client Credentials Grant

There are few endpoints were the Client Credentials flow is also allowed, in which cases the respective resources to which it is granted access are considered completely detached from the PSU until they are authorized by him - they are considered to belong to the TPP up to this moment.

Client credentials are used as an authorization grant typically when the client is acting on its own behalf (the client is also the resource owner) or is requesting access to protected resources based on an authorization previously arranged with the authorization server. [https://tools.ietf.org/html/rfc6749#page-40]

Proof Key for Code Exchange

As an additional security measure to protect the Authorization Code Grant in OAuth2 flow, LUXHUB is implementing Proof Key for Code Exchange (PKCE) as described in [https://tools.ietf.org/html/rfc7636]. This mitigates the threat of having the authorization code intercepted. The technique involves the client first creating a secret, and then using that secret again when exchanging the authorization code for an access token. This way if the code is intercepted, it will not be useful since the token request relies on the initial secret.

Registering your application for API access

To access an API you need to obtain your OAuth2 credentials (client_id and client_secret) and use them to get tokens within the scope needed for the endpoint you are trying to access. There are two options to do so:

• Dynamic registration based on eIDAS Certificate.

  For all our PSD2 APIs, we provide OAuth2.0 Dynamic Client Registration Endpoints. You just need to call the register endpoint (/api/oauth/register) using your eIDAS TLS Client Certificate. In the request, you will have to provide the required redirect URI to your application, where the customer will be redirected after authentication. In the response, you will receive the credentials that you will need to use in order to get details about the API exposed on the LUXHUB platform and register access for your application to the ones that you deem interesting.

  This dynamic access mode for TPPs is not available in sandbox environment, but ONLY in production environment. Details about how it is to be used will be published soon.

• Use our Developer Portal

  If you don’t have an eIDAS Certificate yet or if you want to create more than one set of OAuth Credentials, you can use the Developer Portal for authorizing your application. If you don’t have an account yet, you need to register first (see How to register section above). Once you are logged in, you can go to the Applications section and create a new application.

  Credentials management and API access is managed at application level, i.e. each application will receive a pair of (client_id, client_secret) credentials and will have to register the APIs to which it requires access.

  You can change the APIs supported by your application at any time, but keep in mind that you have to do two important - immutable - choices:

  1. Environment: You cannot mix production APIs with sandbox APIs
  2. Category: As of now ONLY applications using PSD2 API can be created, in the near future non-PSD2 APIs will be offered as well. The current documentation will be updated to reflect this change once available.

  When creating an application you also have to provide the redirect URLs of your application. This is where your application’s users (named Payment Service User - PSU - in PSD2 lingo) will be redirected after doing strong customer authentication in the bank realm. Depending on your implementation, you may implement several redirect URLs (for example different endpoints for consent approval, and for payment authorization)

  The redirect URLs defined here will have to match the URLs provided when the application calls /authorization endpoint (details in sections below).

  Finally you will have to upload an X.509 Certificate, which will help us generate a PSD2-compliant OAuth2 client_id. In production, you have to use your own eIDAS Certificate granted by a QTSP - the same certificate used to call the bank’s API. In sandbox, we will provide you a mock certificate that you can use. You can download your certificate from the Applications page. Binding a real eIDAS certificate to your application via the portal is also supported in sandbox, in which case the said certificate needs to be uploaded.

3. Message signing

STET standard

STET specification enforces message signing, based on http-signature protocol as defined in [https://tools.ietf.org/html/draft-cavage-http-signatures-10], for requests and makes it optional for responses. Please see chapter 3.5 Applicative authentication in STET PSD2 API Documentation Part 1: Framework for details on how the message signing should be implemented.

The electronic signature of the TPP has to be based on a qualified certificate for electronic seals. This qualified certificate has to be issued by a qualified trust service provider according to the eIDAS regulation eIDAS. The content of the certificate has to be compliant with the requirements of EBA RTS on SCA and SCC. The certificate of the TPP has to indicate all roles the TPP is authorized to use. The public key needed for signature verification is requested to be an URL aiming to provide the relevant Qualified Certificate.

Berlin Group standard

Berlin Group specification does not require ASPSP to enforce HTTP message signing, however, LUXHUB considered this as best practice that should be enforced for all communication.

Therefore all requests sent by TPPs to an ASPSP hosted on LUXHUB platform will have to be signed at application level using the http-signature protocol as defined in [https://tools.ietf.org/html/draft-cavage-http-signatures-10].

The electronic signature of the TPP has to be based on a qualified certificate for electronic seals. This qualified certificate has to be issued by a qualified trust service provider according to the eIDAS regulation eIDAS. The content of the certificate has to be compliant with the requirements of EBA RTS on SCA and SCC. The certificate of the TPP has to indicate all roles the TPP is authorized to use. The corresponding public key will be present as a header in all the requests made towards the API.

For more details on this subject please see Section 4.2 in Berlin Group NextGenPSD2 XS2A Framework Implementation Guidelines.

For signing you requests in the case of using mock QSeal certificates downloaded from LUXHUB Developer Portal please use the certificate named QSealC-cert.pem and the key named QSealC-key.pem.

BIC query parameter

LUXHUB is a multi tenant platform and among the ASPSP customers hosted on the platform there are banks that have multiple entities published under the same API. In order to accomodate such scenario an additional query parameter Bank Identification Code (BIC) is added to all endpoints.

The value used for this parameter needs to match exactly the BIC code of the entity your application is trying to access. Furthermore you need to have a valid PSD2 passport for the country where the respective entity resides. Please see the API page in the portal for more details.

Extended transaction history

As required by the EBA RTS on SCA and SCC, there should be additional SCA performed whenever a transactions history for more than 90 days is requested by a TPP. Berlin Group specifications do not provide dedicated handling of this scenario, whereas STET standard describes it in details and proposes a solution.

LUXHUB decided to implement the same solution as for the STET standard for the Berlin Group standard and offer it as a value addition to its customers.

The AISP will be able to ask for an extended transaction history with the very first access token retrieved after a token request. So, In this case a single SCA will be required and used to get the token and to ask for an extended transaction history. Any further extended transaction history request will be considered as out of scope of this SCA.
If the access token scope cannot cover the request (case of extended transaction history request for instance):

• The request will be rejected with HTTP403 with an error equal to insufficient_scope.
• The refresh token will be revoked so the request could be replayed once a new token, having the right scope, would have been requested and provided.
• The new refresh token will be valid up to 90 days.

The additional scope to be used for this case in Berlin Group implementations is AIS_EXT - this is additional scope and not replacing the regular one. For STET implementation this same scope is named extended_transaction_history.

Please see diagram below for details of the flow.

Consent

To access a PSU’s account, you have to obtain the PSU’s consent 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
• STET - current supported version is 1.4.1.3

Berlin Group: Global Consent and Detailed Consent

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 involve 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 <Base64(client_id:client_secret)>' \
            -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://<host>/api/oauth/token' \
            --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:<br>

• 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: <as_per_standard_documentation>' \
            -H 'Authorization: Bearer <access token from previous step>' \
            -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://<host>/bg/v1/consents' \
            --cert QWAC-cert.pem --key QWAC-key.pem
            

• example request (global consent):

curl \
            -H 'Signature: <as_per_standard_documentation>' \
            -H 'Authorization: Bearer <access token from previous step>' \
            -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://<host>/bg/v1/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://<host>/api/oauth/authorize?response_type=code&scope=AIS:<consent-id>&client_id=<your_client_id>&redirect_uri=http://127.0.0.1:9003/redirect&state=12345678-1234-1234-1234-1234567890ab' \
            --cert QWAC-cert.pem --key QWAC-key.pem
            

4. Your application has to retrieve the OAuth2 authorization code. Strong Customer Authnetication 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 '<TPP redirect URL>?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 <Base64(client_id:client_secret)>' \
            -H 'Content-Type : application/x-www-form-urlencoded' \
            -d 'grant_type=authorization_code&redirect_uri=http://127.0.0.1:9003/redirect&code=<authorization-code>&scope=AIS:<consent-id>' \-X POST 'https://<host>/api/oauth/token' \
            --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: <as_per_standard_documentation>' \
            -H 'Authorization: Bearer <access token from previous step>' \
            -H 'Consent-ID: <consent ID>' \
            -H 'X-Request-ID: 12345678-1234-1234-1234-1234567890ab' \
            -X GET 'https://<host>/bg/v1/accounts \--cert QWAC-cert.pem --key QWAC-key.pem
            

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: <as_per_standard_documentation>' \
            -H 'Authorization: Bearer <access token from previous step>' \
            -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://<host>/bg/v1/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: <as_per_standard_documentation>' \
            -H 'Authorization: Bearer <access token from previous step>' \
            -H 'Consent-ID: <consent ID>' \
            -H 'X-Request-ID: 12345678-1234-1234-1234-1234567890ab' \
            -H 'Content-Type: application/json' \
            -X GET 'https://<host>/bg/v1/accounts' \
            --cert QWAC-cert.pem --key QWAC-key.pem
            

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

STET: Full AISP Model and Mixed Model**

This schema shows the requests to be performed in the case where an API requires the STET Full AISP. The requests shown in yellow are explained in detail below.

The flow presented below in details, and in the diagram above, is a reference flow suggested by LUXHUB and not the only possible one.

1. Request an authorization code for the AIS API access. After calling below URL, the PSU will be redirected to SCA of the chosen bank.

• example request:

curl \
            -X GET 'https://<host>/api/oauth/authorize?response_type=code&scope=aisp&client_id=<client_id>&redirect_uri=http://127.0.0.1:9003/redirect&state=12345678-1234-1234-1234-1234567890ab' \
            --cert QWAC-cert.pem --key QWAC-key.pem
            

2. Once the PSU has done SCA with the bank, he will be redirected to your redirect URL. The following request has to be served by your application.

• example request:

curl\
            -X GET '<TPP redirect URL>?code=<authorization-code> '
            

3. Once you have received the authorization code, you can ask for access and refresh tokens.

• example request:

curl \
            -H 'Authorization: Basic <Base64(client_id, client_secret)>' \
            -H 'Content-Type : application/x-www-form-urlencoded' \
            -d 'grant_type=authorization_code&redirect_uri=http://127.0.0.1:9003/redirect&code=<authorization-code>&scope=aisp' \
            -X POST 'https://<host>/api/oauth/token' \
            --cert QWAC-cert.pem --key QWAC-key.pem
            

4. 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: <as_per_standard_documentation>' \
            -H 'Authorization: Bearer <access token from previous step>' \
            -H 'X-Request-ID: 123456-1234-1234-1234567890ab' \
            -X GET 'https://<host>/stet/v1/accounts' \
            --cert QWAC-cert.pem --key QWAC-key.pem
            

5. (mixed model only) Finally, if the selected bank implements the mixed consent model, you have to inform the bank about the accounts and scopes you would like to access.

• example request:

curl \
            -H 'Signature: <as_per_standard_documentation>' \
            -H 'Authorization: Bearer <access token from previous step>' \
            -H 'Content-Type : application/json' \
            -H 'X-Request-ID: 123456-1234-1234-1234567890ab' \
            -X PUT 'https://<host>/stet/v1/consents' \
            -d '{"balances": [{"Iban": "YY64COJH41059545330222956960771455"}],"transactions": [{"Iban": "YY64COJH41059545330222956960771455"}],"trustedBeneficiaries": true,"psuIdentity": true}' \
            --cert QWAC-cert.pem --key QWAC-key.pem
            

Berlin Group

This diagram shows the requests to be performed in the case of an API of a bank which uses the Berlin Group specification for Payment initiation.
The requests shown in yellow are explained in details below.

It is to be noted for Berlin Group specifications that the Payment Initiation resource management and life cycle is fully separated from the life cycle and management of the Authorisation resource. Basically the Authorisation resource is used for authorizing the Payment Initiation resource, hence the Authorisation resource endpoints need to be protected by Authorization Code Grant, which involve PSU authentication, whereas Payment Initiation resource can be protected by Client Credentials Grant only. This kind of approach will allow for the Payment Initiation resource, and its status, retrieval by the TPP even before authorization by the PSU. The payment flow will allow to the TPP to retrieve Payment Initiation resource, 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.

Another benefit of this approach is a unified handling of payment flows between Berlin Group specifications and STET, which actually employs exactly the model mentioned above from an authorization perspective, while maintaining a simplified resource representation that does not involve the additional Authorisation resource.

In the example requests below, we will use the sepa-credit-transfer simple payments for illustrating the requests to be made by a TPP for payment initiation.

1. To start, you have to obtain an access token using the client credentials flow. This access token is not related to a PSU’s resources.

• example request:

curl \
            -H 'Authorization: Basic <Base64(client_id:client_secret)>' \
            -H 'Content-Type : application/x-www-form-urlencoded' \
            -d 'grant_type=client_credentials&scope=PIS:payment' \
            -X POST 'https://<host>/api/oauth/token' \
            --cert QWAC-cert.pem --key QWAC-key.pem
            

2. The next step is to call the products endpoint to create a new payment resource.

• example request:

curl \
            -H 'PSU-IP-Address: "123.123.123.123"' \
            -H 'TPP-Redirect-Preferred: true' \
            -H 'Signature: <as_per_standard_documentation>' \
            -H 'Authorization: Bearer <access token from previous step>' \
            -H 'X-Request-ID: 12345678-1234-1234-1234-1234567890ab' \
            -H 'Content-Type: application/json' \
            -d '{"endToEndIdentification":"123456-1234-1234-1234567890ab", "debtorAccount":{"iban":"FR7612345987650123456789014","currency":"EUR"}, "instructedAmount":{"currency":"EUR","amount":"30"}, "creditorAccount":{"iban":"FR1420041010050500013M02606","currency":"EUR"}, "creditorName":"SFR","creditorAddress":{"street":"rue blue","buildingNumber":"89","city":"Paris","postalCode":"75000","country":"FR"}, "remittanceInformationUnstructured":"AwesomeTPP"}' \
            -X POST 'https://<host>/bg/v1/payments/sepa-credit-transfers' \
            --cert QWAC-cert.pem --key QWAC-key.pem \
            

3. In the following step, you will have to create an authorization resource for this payment.

• example request:

curl \
            -H 'Signature: <as_per_standard_documentation>' \
            -H 'Authorization: Bearer <access token from previous step>' \
            -H 'X-Request-ID: 12345678-1234-1234-1234-1234567890ab' \
            -H 'Content-Type: application/json' \
            -X POST 'https://<host>/bg/v1/payments/<payment-id>/authorisations' \
            --cert QWAC-cert.pem --key QWAC-key.pem
            

• This current step is described from the point of view of a TPP accessing the API of a bank that implemented Berlin Group standard for payments using the concept of “explicit authorisation”. In this concept the authorisation resource has to be created explicitly by the TPP, i.e. by calling the POST endpoint of this resource. This model is more generic and allows as well for multiple SCA flow.
• There is another model of payment accepted by Berlin Group specification, the so called “implicit authorisation”. In this model, the authorisation resource is created implicitly by the bank together with the payment initiation resource, so there is no need to explicitly call the POST /authorisations endpoint. This model can be applied only for the single SCA flow, where the payment is authorized by a single PSU.
  Additional details about these two models can be found in the official documentation of Berlin Group.

4. The next step will actually authorize the payment authorisation resource. This is achieved by redirecting the PSU to his bank for SCA.

• example request:

curl \
            -X GET 'https://<host>/api/oauth/authorize?response_type=code&scope=PIS:<authorisation-id>&client_id=<your_client_id>&redirect_uri=http://127.0.0.1:9003/redirect_payment&state=12345678-1234-1234-1234-1234567890ab&resource=payments/<payment-id>/<authorization-id>' \
            --cert QWAC-cert.pem --key QWAC-key.pem
            

5. Your application has to retrieve the OAuth2 authorization code. This is achieved by the bank’s SCA redirecting the PSU to the redirect URL defined in your request.
   Your application should accept 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) while ensuring that your application is listening at the specified redirection URL.

• example request:

curl \
            -X GET '<TPP redirect URL>?code=<authorization-code>'
            

6. Once you have received the authorization code, you can ask for OAuth2 access and refresh tokens to access the status of the payment initiation.

• example request:

curl \
            -H 'Authorization: Basic <Base64(client_id:client_secret)>' \
            -H 'Content-Type : application/x-www-form-urlencoded' \
            -d 'grant_type=authorization_code&redirect_uri=http://127.0.0.1:9003/redirect_payment&code=<authorization-code>&scope=PIS:<payment-id>' \
            -X POST 'https://<host>/api/oauth/token' \
            --cert QWAC-cert.pem --key QWAC-key.pem
            

7. Your payment initiation request is now authorized and you can check its status by calling the following request

• example request:

curl \
            -H 'Signature: <as_per_standard_documentation>' \
            -H 'Authorization: Bearer <access token from previous step>' \
            -H 'X-Request-ID: 12345678-1234-1234-1234-1234567890ab' \
            -H 'Content-Type: application/json' \
            -X GET 'https://<host>/bg/v1/payments/<payment-id>' \
            --cert QWAC-cert.pem --key QWAC-key.pem
            

STET

Below diagram shows the requests to be performed in the case of an API which uses STET specification for Payment Initiation.
The requests shown in yellow are explained in detail below.

1. To start, you have to get an access token based on your OAuth2.0 credentials.

• example request:

curl \
            -H 'Authorization: Basic <Base64(client_id, client_secret)>' \
            -H 'Content-Type : application/x-www-form-urlencoded' \
            -d 'grant_type=client_credentials&scope=pisp' \
            -X POST 'https://<host>/api/oauth/token' \
            --cert QWAC-cert.pem --key QWAC-key.pem
            

2. Then you have to create a payment resource

• example request:

curl -i \
            -H 'Signature: <as_per_standard_documentation>' \
            -H 'Authorization: Bearer <access_token from previous step>' \
            -H 'X-Request-ID: 12345678-1234-1234-1234-1234567890ab' \
            -H 'Content-Type: application/json' \
            -d '{"paymentInformationId":"0f49608cd17a49048cc808dfa1047572", "creationDateTime":"2019-01-18T17:07:43.455Z", "numberOfTransactions":1, "initiatingParty":{ "name":"AwesomeTPP","postalAddress":{"country":"LU","addressLine":[null,null]}, "organisationId":{"identification":"12LU5","schemeName":"COID","issuer":"ACPR"} }, "paymentTypeInformation":{"serviceLevel":"SEPA","localInstrument":"INST","categoryPurpose":"DVPM"}, "debtor":{"name":"John Smith"}, "debtorAccount":{"iban":"YY64COJH41059545330222956960771321"}, "ultimateCreditor":{ "name":"myMerchant","postalAddress":{"country":"FR","addressLine":["18 rue de la DSP2","75008 PARIS"]}, "organisationId":{"identification":"852126789","schemeName":"SIREN","issuer":"FR"},"privateId":null }, "paymentInformationStatus":"RCVD","creditTransferTransaction": [{ "paymentId":{"instructionId":"01ab09d3e59e4e2a95ddb83e4d7a0dbe","endToEndId":"5f429404c96843e2a791cd8a5150b6a0"}, "instructedAmount":{"currency":"EUR","amount":"1"}, "remittanceInformation":["Fake remittance information."] }], "supplementaryData":{"acceptedAuthenticationApproach":["REDIRECT"] }}' \
            -X POST 'https://<host>/stet/v1/payment-requests' \
            --cert QWAC-cert.pem --key QWAC-key.pem
            

3. You have to authorize (and authenticate) the PSU. After calling this URL, the PSU will be redirected to SCA of the chosen bank.

• example request:

curl \
            -X GET 'https://<host>/api/oauth/authorize?response_type=code&scope=pisp&client_id=<client_id>&redirect_uri=http://127.0.0.1:9003/redirect_payment&state=12345678-1234-1234-1234-1234567890ab&resource=<payment-id as found in previous header "location" of previous response> \
            --cert QWAC-cert.pem --key QWAC-key.pem
            

4. Once the PSU has performed SCA for payment authorization, he will be redirected to your redirect URL. The following request has to be served by your application.

• example request:

curl\
            -X GET '<TPP redirect URL>?code=<authorization-code>'
            

5. Once you have received the authorization code, you can ask for access and refresh tokens.

• example request:

curl \
            -H 'Authorization: Basic <Base64(client_id, client_secret)>' \
            -H 'Content-Type : application/x-www-form-urlencoded' \
            -d 'grant_type=authorization_code&redirect_uri=http://127.0.0.1:9003/redirect_payment&code=<authorization-code>&scope=pisp' \
            -X POST 'https://<host>/api/oauth/token' \
            --cert QWAC-cert.pem --key QWAC-key.pem
            

6. Finally, you can retrieve the status of your payment initiation

• example request:

curl \
            -H 'Signature: <as_per_standard_documentation>' \
            -H 'Authorization: Bearer <access token from previous step>' \
            -H 'Content-Type : application/json' \
            -H 'X-Request-ID: 123456-1234-1234-1234567890ab' \
            -X GET 'https://<host>/stet/v1/payment-requests/<payment-id>' \
            --cert QWAC-cert.pem --key QWAC-key.pem
            

Consent

According to PSD2 directive, the PSU has to give his consent for a TPP to be able to access funds confirmation services API. However, it is not exactly specified how this should be done. It is further assumed, based on current industry practices, that a valid way of giving consent might be as out of band, i.e. based on an agreement between TPP, PSU and bank outside of the scope of the API.

STET specification

Taking into account the generic consideration above regarding consent, the STET specification allows funds confirmation consent to be given in two distinct ways:

• via an out of band agreement between TPP, PSU and bank, where the bank has a record of the PSU consent for the respective TPP and based on this a Client Credentials OAuth2 flow is allowed. It is entirely up to the bank to verify such am out-of-band consent exists and it is authorized by the respective PSU for the respective TPP. If this option is used, LUXHUB will allow funds confirmation endpoint access for ALL registered TPPs via CLient Credentials Grant and it is up to the ASPSP to restricted according to the existing authorized consent.
• via dedicated API authorization scope, i.e. a dedicated OAuth2 authorize request has to be made by the TPP, as part of the Authorization Code grant. The scope requested should be "cbpii". In this approach the PSU will be able to authorize the consent for funds confirmation using SCA, in a similar flow as in the case of account information services consent. Please note that the CBPII consent is not to be mixed with AISP consent, neither business wise or technically, as in OAuth2 scopes.

LUXHUB supports both approaches described above; please refer below diagram for details.

Berlin Group specification

Berlin Group specification considers, in its current - 1.3 - implementation, the consent for funds confirmation services as out of scope for the XS2A API. Therefore the only approach supported is the one based on the Client Credentials flow and this is not part of the Berlin Group specifications.

However, recognizing the market's need, LUXHUB is also supporting an approach similar with the one supported by STET specification, based on dedicated scope for funds confirmation services consent and Authorization Code grant. The scope requested should be "PIIS". In this approach, the PSU will be able to authorize the consent for funds confirmation using SCA, within a similar flow as in the case of account information services consent. Please note that the CBPII consent is not to be mixed with AISP consent, neither business wise or technically, as in OAuth2 scopes.

Please refer above diagram for details; it is of note that the technical scope used is named "PIIS" in case of Berlin Group implementation as oppsed to "cbpii" in case of STET.

Furthermore, please note that with this type of flow only consent for funds confirmation for ALL eligible accounts is possible and not specific account consent. Same is valid for STET standard as described above.

Minimal test scenarios recommendations

A TPP connected to an ASPSP sandbox in LUXHUB environment is recommended to test all services and payment products available, in positive and negative test scenarios. Due to the fact that sandbox data is static, below we suggest an approach on how to test positive and negative scenarios based on dedicated data.

TPP role and certificate scenarios

1. The TPP should be able to register his application on LUXHUB developer portal with either an eIDAS certificate, provided to him by a QTSP, or with a mock certificate generated on the portal itself.

2. The sandbox will check that: correct certificate is provided by TPP, correct role is used while addressing an AIS, PIS or PIIS/CBPII service.

   • In the current version of the sandbox the generated certificates and related resources - organizations, applications, etc. - are not deleted as part of the nightly cleanup process so they can be reused.

Request/response validation

1. TPP requests against each API endpoint will be validated against the proposed interface of the respective API method as in production, i.e. against the published API specification for each ASPSP.
2. ASPSP responses should be validated both by the sandbox and the TPP against that same API specifications published by the ASPSP.
   • The validations referred above are purely technical, i.e. it will deal with data format and structure and not with its content. This type of business validation will be described later in this document.
   • The endpoints made available and their respective data structures are specific to each ASPSP and under its responsibility.

Consent recommendations

1. The consent management in LUXHUB sandbox is dynamic, i.e. consents are managed like resources themselves. Therefore, the end to end production flows can be implemented and consent management can also be tested as such in the sandbox.
2. Consent creation, of the type supported by each ASPSP according to its exposed standard, should be possible.
3. Consent verification should be possible in the sandbox, when used to access resources involved. Appropriate error handling, as per standard specifications, needs to be in place for invalid consents.
4. Consent lifecycle should be implemented as per respective specification.

Accounts recommendations

1. The sandbox environment should be able to simulate different behaviors of the API based on the account data configured. There should be a sufficient number of accounts available to allow all scenarios defined by each ASPSP.
2. ASPSP should offer accounts, at least with IBAN or BBAN identification, with different transaction history and balances. The consent management should be applicable to the accounts defined by the ASPSP.
   • there should be at least one account configured for high volume of data, i.e. a big volume of transactions should be available for at least one account. For this account, TPP can test pagination option offered by ASPSP. What constitutes “high volume” as well as page size should be defined by each ASPSP. This recommendation is valid for accounts that do offer pagination and/or high volumes.
   • there should be at least one blocked account, i.e. an account which, although consent might have been authorized, is blocked so access should not be granted. This can also be simulated by entering a wrong OTP code in the SCA page.
   • there should be accounts that will allow testing the respective consent models supported by the ASPSP:
     • for detailed consent there should be at least 2 accounts defined to allow the PSU to authorize consent only to one of them
     • if consent is expired, revoked by TPP, revoked by PSU or its access frequency exceeded the access to the respective authorized accounts should not be allowed (similar for balances and transactions)
   • the TPP should be able to perform a test to access accounts information with PSU present to verify access is allowed after exhaustion of allowed access when PSU is not present (frequency indicator in consent). In sandbox environment this indicator cannot be changed, it is fixed at 4 times a day.
   • there should be an account, or more, having all available balances according to ASPSP business implementation
   • there should be an account giving access to each type of currency supported by the ASPSP
   • there should be an account, or more, having transactions of each type supported by ASPSP
   • there should be accounts with such balances that can allow different type of payments - while data is stateless in the sandbox, it should make logical sense
   • there should be enough accounts in the system to allow payment initiation for different scenarios

Card accounts recommendations

Berlin Group API standard has dedicated end-points for handling of card accounts. However, these are different just in the way they are presented to the API clients, their behavior and data is quite similar to other payment accounts exposed via the API.
Card accounts are normally the target for funds confirmation use cases as well, as it is common industry practice, for such accounts, to verify funds availability before payment initiation.
Therefore, the same recommendations as in the case of generic payment accounts apply.

Balances recommendations

1. All type of balances supported by the ASPSP in its other online interfaces should be available in the sandbox.

Transactions recommendations

1. All type of transactions supported by the ASPSP in its other online interfaces should be available in the sandbox.
2. A big enough number of transactions should be supported to test pagination functionality if offered by ASPSP.

Funds confirmation recommendations

1. TPP role conformity should be evaluated for access to funds information endpoints.
2. It should be possible to test availability of funds in positive and negative scenarios.

Payment initiation recommendations

1. It should be possible to make a payment initiation and authorize it via SCA. Cancellation of said payment should be possible if supported by the respective ASPSP. Negative scenarios should be possible as well, including successful SCA but not executed payment for business or technical reasons, i.e. daily limits exceeded, invalid amount, date, etc.

2. It should be possible to make a payment initiation with SCA exemption. A dedicated account not requiring SCA for payment initiation can be setup for this purpose.
3. Multiple SCA scenarios should be supported if supported in real production by the respective bank. Usually there will be a dedicated account setup in the system that will require multiple SCA flow. If you encounter issues in working with this flow, please get in touch with our Support Team that it is at your disposal to answer questions and provide clarifications.
4. Signing basket scenarios should be supported if supported in real production by the respective bank. If you encounter issues in working with this flow, please get in touch with our Support Team that it is at your disposal to answer questions and provide clarifications.