Idea::Bank Romania
PSD2 Enabler Developer Portal
USER GUIDE
Glossary / List
of Abbreviations and Terms Used in this Document
|
Abbreviation
/ Term |
Expansion
/ Description |
|
AISP |
Account information service provider |
|
PISP |
Payment initiation service provider |
|
TPP |
Third party provider. A legal entity acting
either as AISP, PISP or both |
|
User |
Individual registered to access the developer
portal |
Contents
Glossary
/ List of Abbreviations and Terms Used in this Document
Registering using existing
and valid Github account
Third party provider
registration
6. Testing API using external
tools
1.
Background
This document is used to describe the functionalities of the Idea::Bank Romania PSD2 enabled developer portal.
1.1.
Purpose
Purpose of this document is to provide details on how to use the product from a functionality point of view. The document won’t cover parts related to configuration and parametrization.
1.2.
Intended
audience
Main audience of this document are individuals and organizations want to use the sandbox to test the public API exposed by the bank.
1.3.
Scope
Descriptions in this document describe the following processes and flows:
1. Registering to use the sandbox environment
2. Accessing API documentation
3. Using the API test console
2. Registration
Goal
Register to get access to test environment of the bank. Registered users can create a test TPP profile and download a testing certificate which is used to access the system and have a dedicated test data for testing the bank exposed API’s.
Preconditions
Access to any valid e-mail address or valid Github account.
How to access
The access to the register form is allowed by clicking the Register menu item on the application menu.
Overview
In order to get the full access to the test environment and obtain the test credentials and dedicated test data TPP must go through the following process. The registration process goes through the following steps:
1. Creating a user account to access the system
2. Registering TPP
3. Registering the test application and acquiring the access credentials for API
4. Acquiring a test certificate to access the system
To launch the process visitors must click on the Register button in the main menu. As a first step of the process the registration form is presented to enter user information.
Figure 1. User registration form - developer portal user
New users must fill in the following fields:
·
First
name
Required, first name of the
user
·
Last name
Required, last name of the
user
·
Email
address
Required, unique and valid
email address which will be used as a username to access the system
·
Company
name
Optional, Name of the company
the user is working for
·
Password
Required, masked, must satisfy
password complexity
·
Password
confirmation
Required, must match the password field
After clicking on the register button, the user will get the message that an email confirmation is required in order to continue the process.
Figure 2. User registration – registration confirmation
Figure 3. User registration - Email confirmation message
Clicking on the provided link, the user will be redirected to the final screen that shows the confirmation message. With this final step of the registration process the user account is created.
Users who try to use the system before completing the email confirmation will be presented with a message that email confirmation is required.
Figure 3. User registration – not confirmed email
Registering using existing and valid Github account
Users that have valid Github account can easily register by associating the Github login with the portal user account. To launch the process of registration using the Github account users can click on the Github option on the login page. After logging to Github new users will have to give permission to access the public data of their profile.
Figure 4. User registration - GIthub authorization to public data
After the authorization is provided users will have to complete the registration by associating the user account of the portal to the Github login.
Figure 4. User registration – completing the registration using Github login
In order to do this, new users must provide the following information:
·
First
name
Required, first name of the
user
·
Last name
Required, last name of the
user
·
Email
address
Required, unique and valid email address
which will be used as a username to access the system
Clicking on the register button the process is complete. Next time users can log in with the Github account and they will be allowed to use the portal. After completing the user registration process users can continue with the TPP registration process.
Without completing the next steps registered users have the privilege to view and download the API definitions.
Third party provider registration
According to PSD2 regulation only registered legal entities
can access the banks API. The registration and verification of the entity is
the responsibility of the accredited national authorities which provides the
TPP certificate for them. To simulate this, in test environment users must
provide the organization information to be registered as third party
providers. Each user can register only
one third party provider. If there is a need to test various profiles like AISP
or PISP use the application section to add applications with different roles.
How to access
The access to the TPP registration one clicks on the Registration menu item under the TPP Information menu.
Overview
To complete the registration as a TPP provider users must complete the TPP registration form.
Figure 6. TPP registration
·
Name
Required, full name of the organization
·
Phone
number
Required, phone number for the
purpose of contacting the organization
·
Email
address
Required, unique and valid business
email address for the purpose of contacting the organization
·
Country
Required, country where the organization is registered
Clicking on Register button and completing the TPP registration process. The system will automatically seed the test data for the registered TPP.
For each registered TPP system generates the following test data:
Accounts for organizations
· Single currency transactional EUR account
· Multicurrency EUR and GPB transactional account
· Credit card
Accounts for individuals
· Single currency EUR transactional account with overdraft and one debit card
· Multicurrency EUR and GPB transactional account
· Gyro EUR account
· JOINT ownership EUR transactional account with overdraft and debit card
· Savings EUR account
Corporate and individual users
· Two organizations as customers each with two authorized users
· Two individual customers with own accounts where the other user is authorized person. Joint account is owned by both retail customers.
Every registered TPP gets a dedicated test data. Sandbox simulator will simulate the execution of the transactions posted and will update the account balances. At any time, system state can be reset to the starting point.
Access to the test data is provided through the sandbox users menu item.
Continuing with the process, users need to add an application to get the access credentials for the API.
TPP applications
Applications allow registered TPPs to select the specific
PSD2 API capabilities they want to test. Every app gets a unique set API client
credentials. Application also provide the users with the needed OAUTH2 client
credentials to access and test the API in the API test console.
How to access
The access to TPP applications is accessed by clicking the Profile -> Applications menu item in the menu
Overview
Applications overview page shows all the created applications. When there are no plications users can click on the create new button.
Figure 7. Application list
When the new application is created users have to provide the following information:
·
Client
name
Required,
name of the application helps the user to identify it
·
Redirect
URI
Required,
???
·
Post
logout URI
Required,
???
Figure 8. Creating applications
After clicking on the Create button the system will store the information and create a new application. The newly created application will be shown with the Client Id and Client Secret. The user has to copy these data right after the application has been created if he wants to use them for Try API Call functionality otherwise, he will have to generate a new the next time he opens the application details this page.
Figure 9. Creating applications – Created application with client id and client secret generated
·
Client Id
The public identifier for application. Clicking
on the Copy button place this information on the clipboard
·
Client
Secret
The secret known only to the application
and the authorization server. Clicking on the Copy button place this information
on the clipboard
Number of applications is not limited and each created application will be shown inside list of applications. The possibility to enable/disable an application by clicking on Enable or Disable buttons provides the possibility to test different scenarios.
TPP certificate
TPP Certificates are self-signed QWASP certificates issued by the bank for the purpose of testing the programmable access to API. In order to obtain the certificate users must fill in the certificate parameters presented on the screen. The system can issue one certificate per registration.
How to access
The access to TPP certificate is allowed by clicking the Profile -> Certificate menu item on the application menu.
Overview
TO create the certificate users must fill in the certificate request form
Figure 3. TPP certificate request
·
Name
Required, Certificate holders name
·
Company
name
Required,
company name
·
State or
Province name
Optional,
·
Locality
name
Optional,
·
Organization
name
Optional
·
Common
name
Required
·
Email
address
Optional
·
Domain
Required,
must match the domain from where the calls to the API will be made
·
NCA ID
Optional, National registry identity
·
NACA Name
Optional, Name of the national registry
·
Has AI role
Optional, selected when the TPP will be acting as AISP
·
Has PI role
Optional, selected when the TPP will be acting as PISP
After filling in the required fields the system will generate the certificate which can be used for testing purposes. Once created the certificate can’t be changed.
After successful certificate creation the system will show the certificate details and will allow the user to download the certificate.
Figure 4. TPP certificate overview and download option
This step completes the process of registration as TPP.
3.
TPP sandbox
users
Goal
The purpose of this function is to provide access to the generated test users in order to obtain the credentials to get the user consent for access.
How to access
The access to TPP sandbox click on the Profile -> Sandbox users menu item.
Overview
The page will show all the customers created in the test environment.
Figure 5 TPP sandbox users
Details about the specific user can be seen by clicking on a sandbox user from existing list as it’s shown below.
Figure 6 TPP sandbox users - Details
4.
TPP users
Goal
Provide the option to add additional users to the same
developer portal profile.
Preconditions
Registered as TPP.
How to access
The access to TPP users is allowed by clicking the Profile -> Users menu item
Overview
The TPP users shows the list of additional users that can access the same profile and test data if there are any. Clicking on the Add new user .
Figure 7 TPP users
A new user can be created by clicking on Create a New User box and by populating only Email field which has to have the same host name that has been used during TPP register process.
Figure 8 TPP users - Create a new one
TPP User can create as many users as he needs, each created user will be shown inside list of users, he also can see details for each user and he has the possibility to enable/disable a user by clicking on button Enable or Disable.
5.
Try API call
Goal
TPP User has
option to test APIs using try API call functionality.
Preconditions
The permission to this link only has logged and registered TPP User with confirmed mail.
How to access
The access to try API call is allowed by clicking the APIs application top menu item and by selecting any of the available API from dropdown list. A new screen will be shown with all available documentation for that specific API, then by clicking Try link from API documentation header the user will be redirected to try API call.
Overview
The try API call screen is shown below. Follow these few steps to test try API call functionality:
· Chose an Api, Api Version and an Api method from dropdown lists. Request URL will be generated automatically.
· Enter the Client Id and the Client Secret, these values have been provided during application creation process (see chapter TPP applications).
· Select a Grant Type:
- Client Credentials;
- Password Credentials.
· If Password Credentials Grant Type is chosen two new fields will appear, Username and Password. Enter these values.
· Add header parameters Key and Value (if necessary).
· Add request Body (if necessary).
· Finally, click on button Send Request.
Client Id - The client identifier issued to the client during the Application registration process.
Client Secret - The client secret issued to the client during the Application registration process.
Figure 9. Try API call
6.
Testing API
using external tools
Goal
Use the sandbox environment to test the banks API.
Preconditions
Created and active application for the TPP. On how to create the application please consult section two, chapter APP registration. Sandbox users. Created and active certificate for the TPP.
How to access
In order to test the API with the external in this manual we will use Postman (https://www.getpostman.com/) but any tool free for testing you can use any tool.
Overview
1. Steps to test the application are following:
2. Get the authorization token and provide consent for accessing the accounts
3. Call the API with the token
The first step is to configure the postman tool to acquire the access token. Access token can be acquired using different flows in this example we are using Implicit flow.
In order to start the proces use the edit collection option from postman
Figure 16. Configuration
for a API call collection
Next step is to select the Authorization tab and select the Get New Access Token option. This will launch the dialog for filling in the parameters for getting a new access token.
Figure 17. Configuration
for a API call collection. Authorization section
Once you get to the get new access token dialog fill in the following fields with the proper data:
· Token Name: Token Name
· Grant Type: Implicit
· Callback URL: Put the https://www.getpostman.com/oauth2/callback
· Auth URL: Put the URL of the authorization endpoint. The format of this URL is {BaseUrl}/IAM/Connect/authorize.
· Client ID: Copy and paste the Client ID of your test application.
· Scope: Put AssescoSEE.PSD2
· Client Authentication: Send as basic header
Figure 18. Get new
access token parameters
After you have filled in the parameters request the new token. The flow will take you to the IAM login page where you will have to login on behalf of one of the Sandbox users. You can choose any Sandbox user and input the username and password
Figure 19. IAM login page
After you login as one of the customers using the provided username and password the system will ask you provide the consent for the users accounts. The simplest approach is select All accunts but you can tailor the consents based on your preference and test cases.
Figure 20. IAM Consents page
Once the consent is confirmed new access token will be issued.
Figure 20. New access token
Final step after getting the token is to call the API and test. The following example shows a call to get the list of accounts for the customer. List of APIs with required parameters and responses you can find on the portal under the section APIs.
Figure 21. Successful API call