Api documentation

Api documentation get started

Api documentation

Getting started - NextGenPSD2XS2AFrameworkforCroatia 1.3.3 Aug 19th 2019 - HR Country Specific Json Yaml

Developer portal: User Guide

 

 

 

 

 

OTP Bank

 

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

 


 

<w:Sdt SdtDocPart="t" DocPartType="Table of Contents" DocPartUnique="t" ID="-437219659">

Contents

Document History. Error! Bookmark not defined.

Glossary / List of Abbreviations and Terms Used in this Document. 2

1.      Background. 5

1.1.       Purpose. 5

1.2.       Intended audience. 5

1.3.       Scope. 5

2.      Registration. 6

Goal 6

Preconditions. 6

How to access. 6

Overview.. 6

Registering using existing and valid Github account. 8

Third party provider registration. 10

TPP applications. 11

TPP certificate. 13

3.      TPP sandbox users. 16

Goal 16

How to access. 16

Overview.. 16

4.      TPP users. 17

Goal 17

Preconditions. 17

How to access. 17

Overview.. 17

5.      Try API call 19

Goal 19

Preconditions. 19

How to access. 19

Overview.. 19

6.      Testing API using external tools. 21

Goal 21

Preconditions. 21

How to access. 21

Overview.. 21

 


 

1.     Background

This document is used to describe the functionalities of the OTP Bank 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

·         Corporate transactional account in HRK

·         Corporate transactional account multicurrency

Accounts for individuals

·         Retail transactional account in HRK with overdraft

·         Retail giro account in HRK

·         Retail transactional account multicurrency

·         Retail joint ownership transactional account in HRK with overdraft

·         Retail savings account in HRK 

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. 

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