Welcome to LUXHUB One - the unified access to multiple PSD2 API providers. LUXHUB One is providing a unified interface - API, flows and security profiles - for all supported PSD2 providers, irrespective of the standard they have implemented for PSD2 compliance.
You can start by exploring our API and providers catalog and register an account to start consuming the APIs in Sandbox - see How to register section below. Remember that Sandbox connects to actual providers PSD2 sandboxes so you might be required to provide eIDAS certificates in order to be able to use the sandbox to connect to a particular provider. In the Sandbox there will also be available two reference banks implementation, one for each generic PSD2 standard: Berlin Group and STET.
Have a look at our providers list to find the APIs you would like to integrate. While registering with LUXHUB One you will be able to decide which providers you would like to integrate.
How to register
To get access to the API in Sandbox mode, you need to have a signed contract with LUXHUB. Please contact us for setting up your account!
Once your account is setup, you will get access to this API and will be able to connect to the providers of your choice in Sandbox mode, as well as to reference provider API implementations available for your convenience. For promotion to production you will have to get in touch with the LUXHUB delivery team who will organize the migration for you.
As part of the registration process there are few steps that will be requested to be performed, irrespective to the providers whose APIs you would like to consume. According to requirements of each specific provider, there might be specific steps that will need to be fulfilled.
How to access the LUXHUB One API
Have you found a provider API you would like to implement? The following steps will teach you what you need to do to integrate the API via the LUXHUB One platform.
1. Security considerations
Consumer connection to LUXHUB One API is secured via MTLS authentication at protocol layer, while the consumer is authenticated via API Key at application level; message signing is also insured via http-signature. On the providers side, LUXHUB One connects via PSD2 APIs so the regulatory compliance requirements of PSD2 must be followed, i.e. using eIDAS for identification (QWAC) and message http-signing (QSEALC) along with applicative authorization via OAuth2 protocol; user authorization for its resources - accounts, balances, transactions history - is given via Strong Customer Authentication, as part of OAuth2 Authorization Code Grant flow.
eIDAS Certificates considerations
The eIDAS certificates referred to in this guide are SSL 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
PSD2 APIs might require usage of both types of certificates, QWAC to access the API and QSeal for http-signature, i.e. message signing. As such it is strongly suggested to provide always a pair of QWAC/QSEALC certificates for onboarding and usage purposes.
LUXHUB will use the eIDAS certificates provided by each consumer to authenticate towards each provider onboarded for the respective consumer.
2. API access
Access to the LUXHUB One API is controlled via API Keys assigned to each consumer via the onboarding process. Please see below the details of how this is implemented.
Further on, each consumer that is accessing the API will have to set HTTP headers, in their requests to access resources of a certain user with a certain provider, that will be pertinent in identifying the provider and the user in question. Similarly, the request will also need to contain the permission request identifier, so the system will be able to identify that the user had indeed granted consent authorization via SCA.
Onboarding of a new consumer of the One API involves a certain amount of steps that have a clear order and purpose, listed below and discussed further in details as needed:
- setting up a contractual relation with the consumer
- setting the consumer in the system as a client of the One API
- register the consumer with the providers it is interested to aggregate, aka provider onboarding
- open up access to the API for the consumer in Sandbox mode; once the consumer is satisfied with the testing of his API he will request access in Production mode
Setting up a contractual relation with the consumer
Usually this step comes after the sales procedure that insures that the consumer is aware of all the functionalities and capabilities of LUXHUB One, as well of all the necessary steps involved in becoming a consumer, potential fallacies, roles and responsibilities of each party, project management items and pricing of the service. The contract will formalize all these aspects so they can agreed upon by each party and might contain various annexes related to the technical procedures to follow during the onboarding and normal operation during the product life cycle.
Please contact LUXHUB Sales team to get in touch and start the process!
Setting the consumer in the system as a client of the One API
This step involves granting the consumer access to the One API endpoints in the base of the contractual relation established at the previous step. This step is mostly technical and involves setting up a secured access to consume the API.
Identification and authentication of the consumer towards the LUXHUB One platform is controlled at 2 levels: protocol level, using MTLS authentication and application level, via API key. As well, message level signing is provided via http-signing of all request/response exchanges via the API.
- Consumer registration with LUXHUB platform: the usage of the API involves server to server communication only and it is not directly involving the end-user in authorizing access, hence the API authorization is provided by the usage of API Key authentication. This allows the platform to identify the consumer and verify its rights to access the respective API. This registration process is done manually, as of now, by LUXHUB One delivery team.
As part of consumer onboarding the first technical step is to define an API key in the LUXHUB API Management platform and to communicate it to the consumer. It is of note that API Key is not a secret and must be included in each request.
2. MTLS setup: this involves the consumer using a SSL client certificate to authenticate itself to LUXHUB One as a registered and approved consumer of the API. The verification of the certificate is done at LUXHUB One firewall level because the SSL connection is terminated at this level. Additional checks are done at the same level, i.e. via firewall rules, for example:
- that the Distinguished Name part of the certificate belongs to a registered consumer. This type of check has the benefit that multiple SSL certificates with same DN can be used so certificate rotation is easier to manage.
- that the certificate is issued by LUXHUB CA
The SSL certificate that the consumer will have to use is issued by LUXHUB own Certification Authority.
Consumer eIDAS certificates (QWAC and QSEALC) will be used to identify LUXHUB One towards the API providers. As such a protocol for obtaining these certificates from the consumer is set in place, along with a procedure of onboarding of the said consumer to ALL providers that he is interested to access.
eIDAS certificates protocol
In order to avoid sharing of private keys, LUXHUB One will create CSR requests for each consumer certificates that it needs to have for its operation, i.e. QWAC and QSEALC. These CSR will be created with the required eIDAS profile and data as to identify the consumer for the purpose of PSD2 API usage. QWAC and QSEALC certificates will be created with a QTSP by the consumer and provided to LUXHUB.
- LUXHUB creates a CSR for eIDAS profiles, both QWAC and QSEALC – private keys remain ALWAYS with LUXHUB
- Send these to consumer
- Consumer gets eIDAS certificates, based on CSR LUXHUB provided, from a QTSP
- Certificates are returned to LUXHUB
- Consumer maintains full control over the certificate (they can revoke it, etc); they also have the responsibility to manage certificates renewal or revocation (by restarting this mentioned process)
- LUXHUB configures these certificates in the system and use them to identify towards ASPSP in context of PSD2 framework
Each consumer will need to indicate to LUXHUB One delivery team the providers whose PSD2 APIs it is interested to consume. The delivery team will be in charge to register the consumer, as TPP, to each of these providers. This process might be automatic, for some providers, or manual, for most providers. As part of this process, the team will have to register the consumer as TPP client for the provider's API first in a sandbox and then in production.
It is to be noted that a majority of providers require a real eIDAS certificate to be provided by the TPP for registration, even in sandbox mode - the PSD2 regulated way of "providing sandbox access to TPP in process of registration" is considered to be a complicated manual process that it is not possible to be supported at this stage.
There are providers that allow registration of TPPs to sandbox access even without an eIDAS certificate. While this is possible and supported it is recommended to use a real certificate to avoid managing different certificates for same consumer but different providers.
The certificates provided by one consumer cannot be use in any way for a different consumer registration, even for testing/sandbox purposes.
Each consumer will have to provide a list of providers, as part of its onboarding procedure, to which it will be registered. Registration to any other provider will be considered outside of the initial setup of a consumer, hence might be subject to new setup fees.
Open up access to the API for the consumer
Once the consumer is registered with the respective providers, his access is setup - i.e. API key is made available, eIDAS certificates are set in the system for egress access, SSL certificate is set for ingress access, etc. - the consumer is ready to begin using the One API. The access will start in a sandbox mode, i.e. accessing providers' PSD2 sandboxes, and, when the consumer decides that he is satisfied with the level of testing of his application, it can be migrated to production.
According to the agreed setup with the consumer a new pair of eIDAS certificates should be provided for production setup.
Note: It is important to note that all considerations above related to consumer onboarding are environment specific, i.e. there is no, necessary, link between the onboarding of the consumer in sandbox and production environments. As such none of the artefacts required for onboarding should not be considered a priori shared between environments. Similarly the effort required to onboard a customer must be considered per environment as well - in the same line, production onboarding effort might prove superior to sandbox onboarding.
Consumer view on system flows
Diagram steps explained:
- End user initiates an account information request. It is assumed that the end user is already logged into the consumer system.
- Consumer shows to the end-user the list of available providers (obtained from LUXHUB One). Access to this list is available based on consumer API Key identification towards LUXHUB One.
- End-user chooses the provider to who he will want to connect for account information purposes.
- Consumer is presenting 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 provider system - made transparently by LUXHUB One - or might take the end-user directly to the consent authorization page.
- End-user performs SCA, in the realm of the provider, thus granting authorization to LUXHUB One, and through it to the consumer, to access his account information.
- The PSD2 API provider issues an access/refreesh tokens pair that will be used by LUXHUB One, identifying itself as consumer, for accessing the end-user accounts information.
- 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: identify the resources to be accessed and also to show that access was authoized by the end-user. This token is binded - 1-to-1 - to an access token, as received from a provider.
- The consumer makes a LUXHB One API call for accounts information.
- LUXHUB One extracts the necessary info form the consumer token 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. The provider verifies access to account information for the respective user is authorized and returns the respective account information.
In case you need support, do not hesitate to check the Support page to find more information or to get in touch with us.