About
By definition, certain crucial PSD2 APIs require OAuth2. These are marked accordingly in our API documentation and swagger definitions. You will need OAuth2 in both simulation and production environment.
Here are some examples:
- consent APIs (all within PSD2 Account Information product)
- payment APIs (e.g. payment initiation request)
On top of that, these APIs in principle (when there is no exemption defined by business rules) also require an SCA (strong customer authentication) post step.
OAuth2
We are using the authorization code flow. As a first step, you need to open the GET /oauth/authorize link in a browser with the URL parameters response_type, client_id, redirect_uri, scope, and IBAN (optional).
Possible values for scope are:
- for Account Information: psd2:acc
- for Payment Initiation: psd2:pay
Example for the simulation and production environment:
https://api-oauth.bankart.si/psd2/hub/oauth/authorize?response_type=code&client_id=db...&redirect_uri=https://www.xyztpp.si&scope=psd2:acc&iban=SI56XXXXXXXXXXXXXXX
Example for the sandbox environment:
https://api.bankart.si/psd2/hub/sandbox/oauth2/authorize?response_type=code&client_id=db...&redirect_uri=https://www.xyztpp.si&scope=psd2:acc&iban=SI56XXXXXXXXXXXXXXX
Of course, you need to use your own, i.e., your subscribed application’s client_id (API key) and redirect URI. As the authorization page opens, enter username and password, and select "Allow Access" on the second page. This will send you to the redirect URI with a newly generated access code as an URL parameter. You need to extract this code from this URL to get the token.
To exchange the access code for the token you need some tool that can do a simple POST request, for example curl. You need to pass grant_type, client_id and code as x-www-form-urlencoded data.
Here is an example:
curl -d "grant_type=authorization_code&client_id=dbe...&code=AAL7lhdq6k..." -H "Content-Type: application/x-www-form-urlencoded" -H "accept:application/json" -X POST https://api.bankart.si/psd2/hub/oauth/token
This will return a JSON object with the token, which you can then use to call the OAuth2 protected APIs (insert the token value prefixed with "Bearer" in the "Authorization" header field) or simply paste it in the "Access token" field in the developer portal and call the API this way. Access token is valid for 5 minutes. For details (URLs, parameters etc.) please also see the published swagger documents.
SCA (Strong Customer Authentication)
According to PSD2 Berlin Group standard a SCA step is required after certain crucial, i.e., sensitive API calls:
- Create Consent
- Read transaction lists (to retrieve transactions older than 90 days)*
We are using an implicit flow with a simple redirect (not OAuth2) for this purpose. Please check the API response header for the ASPSP/PISP-SCA-Approach value and, when present, redirect the end user to the URL provided in the _links/scaRedirect response element. There is no direct return of information from this redirect to your app, but certain crucial calls are made in the background to complete the authorization and process the payment or create a consent object.
You are able to check the outcome of SCA with corresponding GET /consents/{consentId}/authorisations/{authorisationId} API call (for details please see the API documentation, i.e., swagger definition).
* Read transaction lists calls are limited to a period of 90 days from the time the request is made. During the first 5 minutes of an AIS consent lifecycle, any GET /transactions request made will not be limited. After this time period, the limitation will apply, and any requests trying to retrieve transactions older than 90 days will be rejected.