Before You Start
Before you start you should do a few basic tasks in following steps:
- Register your organization
- Invite your developers
- Register your application
Step 1. Register your organization
To register your organization you should navigate to Sign-up. At first you register yourself as your organization administrator by filling your first name, last name, email address, username, password and accepting the End User License Agreement. Then you register your organization by filling its name and description. Your registration is sent to the bank by clicking Register Now button.
After receiving your registration the bank send to your email address confirmation email with link to login yourself into the Developer portal. Your registration is complete after you click to confirmation link and successfully login.
In case you login without successful confirmation the Developer Portal shows you following error message 'Your account has been disabled'.
The Accounts API and Payments API require than your organization name is matching with the name in Financial Services Register provided by National Bank of Slovakia and client certificate.
You need a password to login to the Developer Portal which defines the password policy settings to control the complexity and lifetime of passwords. Your password should comply with following rules:
Step 2. Invite your developers
As an organization administrator you can invite developers from your organization to join. To invite new developers navigate to Dashboard/Organization page and then to Invitations menu item on the left. Clicking to Invite New Users button you start inviting developers. After filling list of developer's emails click to Send Invitation(s) button to send invitations to the bank. Each developer from your invitation list receives confirmation email with registration link into the Developer portal. Current status of your developers' onboarding you can check on Dashboard/Organization page in Developers menu item.
Step 3. Register your application
Before your first API call is made your application should be registered on the Developer Portal. Navigate to Dashboard/Applications page. To add your new application click to Add Application button and fill Application Information, API Management information and Authorization information. To register your new application click to Save button. After receiving your request the Developer Portal generates API Key e.g. l7xx528bd862138c4e9bab60cfb5d4d85df8 for your application identification. Your subscribed APIs have Sandbox plan.
To secure communication an application secret is also generated e.g. Key Secret 3d5e2ac607ff4f5aa6c5132e1f0f0159. Please keep your secret key in safe. However if your application secret is compromised you can request to generate new secret by clicking to Request a New Shared Secret button.
Calback URL is used by the bank authorization server to return responses containing authorization credentials to the application via the your customer user-agent. The bank authorization server require all applications to register one or multiple their redirection endpoints prior to utilizing the authorization endpoint and require the application to provide the complete redirection URI. Redirection endpoint describes OAuth 2.0 protocol in Section 3.1.2. Redirection Endpoint
For OAuth 2.0 Authorization Code Grant supported scopes are:
- AISP in the Accounts APIs
- payments in the Payments APIs
For OAuth 2.0 Client Credentials Grant supported scopes are:
- PISP in the Payments APIs
OAuth 2.0 protocol defines two client types, based on their ability to authenticate securely with the authorization server (i.e., ability to maintain the confidentiality of their client credentials) in Section 2.1. Client Types. Please choose option which best suites your application architecture.
Promote application to Live
To promote your application to Live environment navigate to Dashboard/Applications page and start to edit your application. In API Management tab you can request to change plan to Live.
In Live environment the Accounts API and Payments API require Two-Way SSL communication. At first you should send email with attached client certificate to firstname.lastname@example.org with following body: "As
- Extended Validation certificate
- eIDAS-based site authentication certificate
Extended Validation certificate
An EV SSL Certificate must contain required fields described on CA/Browser forum web site.
Certificate Authorities list
eIDAS-based site authentication certificate
An eIDAS SSL certificate must comply requirements according to an Article 45 of Regulation (EU) No 910/2014. Certificate Authorities list you can find on Slovak National Security Authority web site and EU Trust Service web site.
Two-Way SSL (Mutual Authentication)
For secure communication between your application and the bank server TLS version 1.2+ is required in Sandbox and Live environment. For TLS 1.2 protocol details see RFC 5246. For more requirements to secure communication see Chapter 4.2 Securing communication in Slovak banking API standard ver. 1.0 document on Slovak Banking API Standard page.
The Accounts API and Payments API require secure their communication with clients by Two-Way SSL method in Live environment. In this method, the client and server need to authenticate and validate each other's identities. The authentication message exchange between client and server is called an SSL handshake, and it includes the following steps:
- A client requests access to a protected resource.
- The server presents its certificate to the client.
- The client verifies the server's certificate.
- If successful, the client sends its certificate to the server.
- The server verifies the client’s credentials.
- If successful, the server grants access to the protected resource requested by the client.
To establish a Two-Way SSL connection, you must have the following:
- private key
- client certificate
- certificate authority root certificate
- certificate authority intermediate certificates