Professional Documents
Culture Documents
TPP Documentation SG PrivateBanking Final Version 2
TPP Documentation SG PrivateBanking Final Version 2
LUXEMBOURG
PSD2 API Solution -
Documentation for TPPs
Addressees:
Business Analysts, Project Managers, Developers, Architects, IT
Disclaimer
This document is published by Société Générale LUXEMBOURG,“so-
ciété anonyme” under the law of the Grand Duchy of Luxembourg, regis-
tered with the Luxembourg Register of Commerce under number B 6061,
whose registered office is at 11, avenue Emile Reuter, L-2420 Luxem-
bourg.
SOCIETE GENERALE VAT No: LU10807024.
Contacts: (+352) 47 93 11 1.
Support Contact
WORLD-PRIV-Support-PSD2-Sandbox@socgen.com
1 Introduction ...................................................................................................................................... 3
2 Environment preparation .................................................................................................................. 5
2.1 Register and Login ................................................................................................................. 6
2.2 Upload TPP certificate ............................................................................................................ 7
2.3 Certificate Status Validation ................................................................................................. 10
2.4 Creating application .............................................................................................................. 11
2.5 Generate key ........................................................................................................................ 13
2.6 Add TPP Redirect (Callback) URL ....................................................................................... 15
2.7 Add the TPP SECRET .......................................................................................................... 16
2.8 Subscribe to API ................................................................................................................... 18
3 Using PSD2 API............................................................................................................................... 19
3.1 Pre-authentication ................................................................................................................... 19
3.2 Call API Endpoints ................................................................................................................. 24
4 References ....................................................................................................................................... 36
5 Glossary .......................................................................................................................................... 38
Document history
The document assumes that TPP has basic knowledge about Payment Services Directive 2 (PSD2) regulation of the
European Union, its terminology and use cases. Please refer to the References section below for an overview and
detailed information about the regulation. In addition, TPP will also find a Glossary below with the most important
PSD2 terms.
The document assumes that TPP is aware about the registration to the NCA in order to obtain the PSD2 authorization.
The document assumes that TPP is aware about the request for a PSD2 certificate from QTSP (Qualified Trust Service
Provider).
TPPs can use the SOCIETE GENERALE PSD2 Application Programming Interface (“API”) Solution (the “API
Solution”) to connect their services. SOCIETE GENERALE will rely on NextGenPSD2 Access to Account Interop-
erability Framework specified by The Berlin Group version 1.3.2 and available on the website https://www.berlin-
group.org/psd2-access-to-bank-accounts. To use the SOCIETE GENERALE public API, the TPP must sign up at
the integrated API Management tool. After login he can subscribe to the API PSD2. The subscription is mandatory to
use the API. This process is explained in this document.
The SOCIETE GENERALE API Solution will follow this Berlin Group Specification for the comply-only features.
Thus, it is possible for an end customer - amongst other functions - to get a balance or postings of the customer’s
payment accounts, make a payment initiation via a Third-Party Provider (TPP). All available methods will be de-
scribed in the section Call API Endpoints.
Note: Additional identification of the TPP at application level with QSealC (Qualified Electronic Seal Certificates) is
not part of the solution. TPP must request data, ASPSP only responses to requests.
Representational state transfer (“REST”) is used for communication through requests and responses.
Please also note that TPP will have the possibility to use a non-production environment to test the solution. All URLs
will be written in next chapters.
Environment preparation process is the same in the non-production and production environment: The returned results
(AIS) when a consent is established between a client and the TPP are the same when a client logs directly to the
eBanking application. A certificate check will be done against the trusted center having issued it, role check, authori-
zation on the APIs according to the role.
To be able to work in the API Store, the TPP must be identified and this requires a one-time registration,
To register, please click on the "Sign-up" button at the top of the page. A form will open in which TPP can enter the
necessary data.
After logging to the API store, the TPP is redirected to the PSD2 Certificate upload form
This action is automatically performed with a scheduled job, the solution will calls the CRLs: “Certificate Revoca-
tion Lists” provided by the Trusted center, if the certificate is not revoked, the status of the uploaded certificate will
be “VALID”
Afterwards TPP must select the application to use in order to "consume" it. This application practically serves as a
storage location for the later API.
Now another area opens, then an already created entry "DefaultApplication" is displayed. This application has already
been automatically added for TPP during the registration process, as a new application will be created the "DefaultAp-
plication" and can be ignored.
TPP Adds the first own application via the button "ADD APPLICATION".
TPP will now be guided through the installation with the following dialog. First give the application a meaningful
name such as the TPP company name. Enter this name in the upper field "Name".
TPP is welcome to fill in the other fields if required, but they are not mandatory for using the API.
In order to communicate with the API, the system needs keys, here called "Production Keys". These keys must be
generated once. Open the newly created application then click on the “Productions keys” tab.
The button "Generate Keys" initiates the generation. Please click on the button. No need to make any changes to the
settings above.
Redirect URLs are a part of the OAuth flow. After a user successfully authorizes an application, the authorization
server will redirect the user back to the application with either an authorization code or access token in the URL.
• Click on “TPP-MANAGEMENT”
This secret needs to be stored in a dedicated zone (such as password vault). As it will be used for all con-
sent creation requests, the secret should be stored in a TPP configuration file.
A subscription to the API is mandatory before consuming it. This process also only takes place once. Please click on
"APIs" in the left side menu. Then select the PSD2 API by clicking on the coloured icon
Select the newly created application and confirm the process with the button "Subscribe".
Please close the success message by clicking on the button "Stay on this page".
The following workflows shows the process of creating a consent for account information, requesting account infor-
mation and initiating a payment via the Berlin Group API.
Each request (AIS, PIS) should be preceded by an authentication step (Pre-authentication)
3.1 Pre-authentication
A pre-step authentication is used to enable access to the system (login). However, the API calls required for this ex-
ist outside the PSD2 API. Hence the name "pre-step".
This means that login must be always the first step. After the login, the TPP can request AI, PI services.
The system therefore offers the Authorization Code Flow ("GUI") process:
The login is performed by the Authorization code flow (redirect approach) where the PSU enters the credentials
and the 2FA via the interface at the ASPSP. Thus, the relevant data traffic takes place between PSU and OAuth
without having to supply the TPP with confidential information.
After successful pre-step authentication the TPP will receive a session based PSD2 access token. This PSD2 access
token is needed for every Berlin Group API call.
The TPP must provide the token in the header field “PSD2-AUTHORIZATION”.
The PSU enters its credentials directly at the OAuth server, which significantly increases security. If a SCA is re-
quired, it is also mapped via the OAuth server and the TAN recorded there.
• Required for the first API call: will give an exemption period (e.g. 90 days)
• Only necessary if SCA must be performed
• User enters credentials in OAuth GUI
User enters TAN in OAuth GUI
For your information, this flow shows the execution of the Strong Customer Authentication
The TPP must send the Bank a Callback URL. Callback URL of TPP is necessary to deliver PSD2 access token af-
ter successful login. As a reminder, this URL is the one provided during the TPP registration.
The authorization code flow (without SCA) can be represented by the following schema:
Once authentication is performed, TPP can call API endpoints to submit payments, to get accounts list, to get ac-
count details…
Each endpoint is described in the PSD2 API Swagger, with following details:
Note: all endpoints require X-Request-ID input in the header section. This parameter is the ID of the request, must
be unique to the call, and generated by TPP.
PRODUCTION https://api.privatebanking.societegenerale.lu/ebank-
ingPsd2/store/api-docs/admin/PSD2/v1
Another full description is available in the store under API menu, and "API console" of the PSD2 API
The PSU must provide the account data (e.g. IBANs) to the TPP. The TPP will then explicitly request a consent for
these specific accounts at once.
Note: it is not possible to grant consent to a single account, all cash accounts are visible to PSU through TPP applica-
tion ("allPsd2": "allAccounts" all the cash accounts)
PSU and TPP need to agree on consent scope before TPP request the particular consent.
For each consent creation a Consent-ID will be generated and handed transmitted to the TPP. The TPP will need this
Consent-ID for each account information request later.
If a certificate gets invalid, the consent gets invalid. At every request the Consent-ID will get validated and its status
can change if the consent is not valid anymore.
The maximum number of accesses to an account will be determined and communicated by the ASPSP. In each case
it will be valid from 0 to maximum 24 hours.
For Account Informations Service (AIS), after giving his consent to TPP, the client can access with no limit to his
accounts through the TPP applications for 90 days without SCA.
TPP can access to the accounts informations without involving the client during this period, however, the access
number per day to account information when balances/transactions are requested should be limited.
The Following json is returned by the ASPSP to TPP and the access limit is defined under the key: frequencyPer-
Day
{
"access": {
"allPsd2": "allAccounts"
},
"recurringIndicator": false,
"validUntil": "2020-12-31",
"frequencyPerDay": 4,
"combinedServiceIndicator": false
}
Once a consent is created, the following endpoints allow to get the consent status based on the {consentId}
Code Description
received The consent data have been received and are technically correct. The data is
not authorised yet.
rejected The consent data have been rejected e.g. since no successful authorisation
has taken place.
valid The consent is accepted and valid for GET account data calls and others as
specified in the consent object.
revokedByPsu The consent has been revoked by the PSU towards the ASPSP.
expired The consent expired.
terminatedByTpp The corresponding TPP has terminated the consent by applying the DELETE
method to the consent resource.
• POST {BASE_URL}/v1/consents/{consentId}/authorisations:
Start the authorisation process for a consent
• PUT {BASE_URL}/v1/consents/{consentId}/authorisations/{authorisationId}:
Read the SCA status of the consent authorisation
GET/v1/accounts → must be initially the first call. But only first time because after the call the account-ids are set.
From now on this call is optional.
GET {BASE_URL}/v1/accounts/{account-id}/balances
GET {BASE_URL}/v1/accounts/{account-id}/transactions/
GET {BASE_URL}/v1/accounts/{account-id}/transactions/
➢ There will always be a SCA necessary for each payment. No SCA exemption is foreseen.
➢ Whitelist beneficiaries are not managed in PSD2 solution
➢ Client should use eBanking application to initiate account transfers
Documentation:
https://docs.wso2.com/display/AM250/WSO2+API+Man-
ager+Documentation
AIS Account Information Service means an online This service may be used by an AISP
service to provide consolidated information on to request information about the ac-
one or more payment accounts held by the pay- count of a PSU. The account is man-
ment service user with either another payment aged by the ASPSP providing the
service provider or with more than one payment XS2A Interface. Functionality and re-
service provider; according to article 4 (16) of strictions of this service comply with
[PSD2] and as regulated by article 67 of [PSD2]. the requirements defined by article 67
of [PSD2].
PIS Payment Initiation Service means a service to ini- This service may be used by a PISP to
tiate a payment order at the request of the pay- initiate a single payment on behalf of a
ment service user with respect to a payment ac- PSU using a given account of that PSU.
count held at another payment service provider The account is managed by the ASPSP
according to article 4 (15) of [PSD2] and as regu- providing the XS2A Interface. Func-
lated by article 66 of [PSD2]. tionality and restrictions of this service