Intesa Sanpaolo Bank Luxembourg

Intesa Sanpaolo Bank Luxembourg (Berlin Group)

Version: 1.13220190215.037.004

State: Prototyped

Environment:	Sandbox
Base URI:	https://sebklull-psd2api-sbx.luxhub.com/bg/v1
Authorization Endpoint:	https://sebklull-cb-sbx.luxhub.com/api/oauth/authorize
Token Endpoint:	https://sebklull-psd2api-sbx.luxhub.com/api/oauth/token
Types:	PSD2
Passport :

To get full access to the banks’ APIs in Sandbox, you need to be an authorized third-party provider (*) or a payment service provider that has applied for the relevant authorization. Register by filling in the required form and providing us information about you and your company so we can verify your identity and make sure that your company is entitled to get access to the PSD2 Sandbox APIs.

We will send you a registration code once the verification is completed. The registration code will allow you to create an account on the LUXHUB Developer Portal, which will grant you access to the APIs exposed by our customers.

(*)Account Information Service Provider (AISP), Payment Initiation Service Provider (PISP) or Card-Based Payment Instrument Issuer (CBPII) in the context of PSD2 Directive (EU) 2015/2366.

Developer portal based onboarding

As said above, access to onboard to the Developer Portal is open to authorized third-party provider or a payment service provider that has applied for the relevant authorization. According to their status, a process is in place that each TPP has to follow to onboard.

If a TPP is already registered and has access to the Sandbox environment, it can upgrade its access so it can use Sandbox and Production environments. The TPP can do so only by proving that he has the necessary credentials to operate in production in the PSD2 context, i.e. he is in possession of QWAC and QSEALC certificates issued by a PSD2 QTSP. Therefore, the promotion process is based, in portal or API form, on presenting such a proof, i.e. signing a challenge posted by LUXHUB so the signing key can be verified as qualified and belonging to a regulated entity.

Once promotion is done, all users from the corresponding TPP organization will have access to both environments. Here are the steps for portal based promotion:

Follow this link (/profile-menu/organization)
Copy the challenge
Sign the challenge with your private key as per the QSEALC eIDAS certificate
Paste the signed challenge encoded in base64
Submit its certificate (public key) in order to allow us to verify the signature.

Once the signed challenge and signing certificate are submitted and the signature verification is passed, the TPP's organization will be promoted to Production and will have access to both Sandbox and Production environments.

Warning: if getting your challenge signed with your private key requires too much time and could induce a session timeout, you should first copy the UUID that we provide with the challenge. Then, under the section where you paste your signed challenge, you should paste also the UUID linked to this challenge so they can be sync-ed.

Onboarding via API

A TPP can use the Third Party Management API to register itself to use the LUXHUB Platform for whatever API it chooses, manage its organization and developers.

The flow via the API is quite similar to the one proposed via the portal with few different elements. The endpoints in this API are tagged either Registration or Promotion and their usage is described below.

Note: The functionality works as described below for this current version of the API but it might be changed in the future to allow further flexibility in usage and enhance the user experience. As well, several other Platform level APIs will be published in the future to provide more LUXHUB specific services to third parties.

Registration via API

The TPP can register/onboard to the platform via OAuth2 Dynamic Client Registration protocol directly to the production environment. To this purpose the /register endpoint is protected by MTLS authentication, so the TPP will have to use its QWAC eIDAS certificate to access it. As a result, the TPP will have a registered application, with respective (client_id, client_secret) combination, and his organization will be created in the Production environment directly in qualified status, which allows usage of PSD2 APIs in Production.

The TPP has to obtain an OAuth2 access_token, via the Client Credentials Grant flow using the (client_id, client_secret) combination from step above, and use this to, optionally, access other endpoints. These endpoints allow finer grained control via the API, i.e. managing the list of APIs to register to the TPP organization, managing organizations and users, etc. Basically, pretty much everything that can be done in this direction via the portal can be done via the API as well.

All endpoints in the Third Party Management API are protected via MTLS and all, except for/register endpoint, are authorized via:

Client Credentials Grant or,
for those involving the user, Basic Authorization (user/password). This means Promotion tagged endpoints, which involve Developer Portal registration, as well as those not tagged Promotion if and only if the /register/user endpoint was used beforehand to create an user via the API.

Warning: if a TPP is already registered via the Developer Portal it will have to promote its organization via the portal. Otherwise, using the API will mean that a secondary organization will be created for the same TPP.

Promotion via API

A TPP can promote its organization from pending to qualified status, i.e. in order to get Production access to PSD2 APIs, via the Developer Portal, as described above, or via API - using endpoints tagged as Promotion in the Third Party Management API.

Once the TPP decides that he wants to promote his organization, i.e. so it can use the PSD2 APIs published by providers in Production, it will have to use the /promotion/challenge to obtain a challenge form the LUXHUB Platform, sign it with his QSEALC eIDAS certificate and return it via a call to the /promotion/organization endpoint. After the TPP signature is validated and verified its respective organization is moved to qualified status, so the TPP can start using the PSD2 APIs in Production.

In this iteration of the LUXHUB Platform, the Migration endpoints are to be used only by TPPs already registered via the Developer Portal to promote their organizations. The TPPs using the Registration endpoints will have their organization created directly in the qualified status, hence with access to Production environment.

The endpoints tagged Migration are also secured via OAuth2 Client Credentials Grant flow, using the token obtained above.

Sandbox environment considerations

The Sandbox environment offered by the LUXHUB Platform aims to duplicate, as much as deemed possible, the behavior of each ASPSP API in a real Production environment.

The data exposed in each Sandbox is a synthetic representation of the real data available in the respective ASPSP Production environment. As well, for all practical purposes, the journey of a PSU that connects to a TPP app and gives its consent to it to access its account information and/or to initiate payments, will be verbatim to the actual Production implementation, however small discrepancies might appear in the flows and/or data available. All these can be reported and fixed during the operation of the Sandbox.

The LUXHUB Platform Sandbox environment is based on static data. Data is normally static, i.e. it will not be modified as result of Sandbox usage. For example, a payment initiation submitted to an account will appear in transaction history but will not modify the account balance. According to the respective bank implementation of the API it might be that not all the fields needed in the created transaction will be present - this is because the values of such fields might be based on internal reference processes not available to the Sandbox application, but available in real scenarios to the bank’s core banking system. However, all mandatory fields will be present and taken care of in all scenarios.

The PSU identification credentials available for the Sandbox are not necessarily bank specific but generic only. By default, there are three accounts for testing, all with a default password and OTP. The mock authentication for each of these PSUs will work independent of the password used, but it will fail in case any other OTP aside from 123456 is used.

The Sandbox environment is continuously available for testing by the TPPs. Support is available to the TPP during business hours.

Data cleanup will be performed during a “nightly build” process on the Sandbox, i.e. all resources created and/or updated during the day by TPPs, including consent resources, will be reset to initial state.

Sandbox environment is providing verification of the connection to TPP from transport and application layer point of view.

Mutual TLS will be insured for all connected TPPs as well as checks on the role of the TPP
Validation of syntax of the request/response conversations will be done against the API specification provided by the respective standard
Error reporting is done as specified in the documentation associated with each API standard published by the ASPSP
Correctness of flows is verified as well and related documentation made available

Minimal test scenarios recommendations

A TPP connected to an ASPSP's 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.

Disclaimer

Please note that the recommendations below are not exhaustive nor do they try to substitute in any way on the TPP being able to test functionality the way they see it fit. It is merely a suggestion of minimum scenarios that will provide a sanity check of the Sandbox.
TPPs are encouraged to adjust their test flows and procedures to the exact functionality offered by each specific bank API, according to the PSD2 standard API specification implemented, functionality provided and details of implementation. To this purpose please consult the API technical documentation available via LUXHUB Developer Portal and/or get in touch with our Support Team that it is at your disposal to answer questions and provide clarifications.
LUXHUB cannot guarantee that below recommendations are followed to the letter by each bank, however, these same recommendations were made to each bank related to the data provided in the Sandbox. If you encounter issues in following along the lines of the recommendations below, please get in touch with our Support Team which is at your disposal to answer questions and provide clarifications.

TPP role and certificate scenarios

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.
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

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.
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.

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.
Consent creation, of the type supported by each ASPSP according to its exposed standard, should be possible.
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.
Consent lifecycle should be implemented as per respective specification.

Accounts recommendations

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.
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

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

Transactions recommendations

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

Funds confirmation recommendations

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

Payment initiation recommendations

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.
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.
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 which is at your disposal to answer questions and provide clarifications.
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.

In case you need support, do not hesitate to check the Support page to find more information or to get in touch with us.