Support

Open banking is a process of securely sharing financial accounts’ data between banks and third-party providers and initiating payments. It leads to innovation, competition, and efficiency – quick, simple, and secure.

The Second Payment Services Directive (PSD2) provides the legal foundation for the development of open banking, better integrated internal market for electronic payments within the European Union. PSD2 mandates that banks allow a third party to access information from the payment account with the goal of ensuring harmonised rules for the provision of payment services in the EU and a high level of consumer protection.

Account information services (AIS) give consumers and businesses an overview of their financial situation by consolidating information across the different payment accounts they may have with one or more payment service providers.

The Account Information Service (AIS) offers the following services:

• transaction reports for a given account or card account, including balances if applicable,
• balances of a given account or card account, - a list of available accounts or card accounts,
• account details of a given account or card account or of the list of all accessible accounts or card accounts relative to a granted consent.

Payment initiation services (PIS) help consumers make online payments and inform the merchant immediately of the payment initiation, allowing for the immediate dispatch of goods or immediate access to services purchased online.

The Payment Initiation Service (PIS) offers the following services:

• initiation and update of a payment request,
• status information of a payment.

Take a look at our banking APIs to see what choices are available. Is there an API you can exploit in one of your applications? Use the supplied APIs to quickly build a fully featured application.

Explore our APIs

Creating an account is free. Click "Create an account", then enter your name, email address, consumer organization, and password. We'll then send you an email with an activation link. Click the link, and you'll be ready to start developing.

Create an account

Before you can use an API, you have to register your TPP application. Log in to this developer portal and click the "Apps" section in the menu. Click the "Create New App" button.

Enter the "Title" of your application and optional "Certificate" (X.509 PEM format), "Description" and "OAuth Redirect URL". Click on "Save" button to complete the registration of your application.

When you register an application, the application is assigned a unique client ID and client secret. You must use the client ID when you call an API that requires you to identify your application by using a client ID or a client ID and client secret. Check the API description for details.

Make a note of your API Secret because it is only displayed once. Your API Secret is stored encrypted, so we cannot retrieve the unencrypted version to tell you the value if you forget it.

You can reset it, which will update the stored value and return the new value to you. To do that, click "Apps" in the main menu, click on the application in question, and then you can click the "Reset API Secret" link in the "Subscriptions" section.

Register app

Invite other members of your organization.

Invite developers

After your application is registered, you need to subscribe to API Product and choose a plan.

We are offering:

• Account Information
  • Consents Service API
  • Confirmation of funds Service API
  • Account Information Service API
• Payment Initiation
  • Payment Initiation Service API

The plan determines the environment – simulation or production. We are offering:

• Simulation
• Default Plan

All plans on Developer Portal are free of charge. In Bankart API portal mandatory PSD2 APIs are available. API specification is available as a Swagger file, in the "API Product" section in the menu. All APIs follow Berlin standard, JSON format is supported.

For subscription you select the desired product and make a subscription to one of the plans. In the next step you select an existing application or create a new application. Once your application is subscribed, you use received credentials to use all APIs included in the subscribed products.

API products

If you want to test APIs with your TPP application, we recommend that you choose the simulation plan. The functionality is the same as in the production environment.

In order to access the simulation APIs, you must have a valid eIDAS certificate (X.509 PEM format) that is uploaded on the developer portal for your application. You can upload it when creating a new app or later when editing the existing app.

After adding your certificate and redirect URL, you are able to use all PSD2 APIs, according to your given role in simulation environment. You will need a simulation payment account, for which you can write to psd2admin@bankart.si.

In order to retrieve a user’s account data, explicit consent has to be created and confirmed by the user. User’s account data are provided only for valid consents. By following the below listed steps a valid consent would be created:

1st step: POST/consents - Create consent

This method creates a consent resource, defining access rights to dedicated accounts of a given PSU-ID. For details please see call parameters description. TPP is also required to redirect the user to the authorisation server with appropriate data that is received from a successful first call (POST Create Consent), redirect links are provided within the response.

Important: Consent can be created for account data, transaction data, balance data with a single method. To obtain only account data, "accounts" has to contain valid account data in this method. To obtain transactions data, "accounts" and "transactions" in the method Create consent has to contain valid account data. To obtain balance data, "accounts" and "balances" in the method Create consent has to contain valid account data.

2nd step: GET/consents/{consentId}/status - Consent status request

Read the status of an account information consent resource. Once the »Consent status request« returns the "consentStatus": "valid", the consent was properly authorised by the user and can be used in further flows for retrieving account data.

Optional methods:

• GET/consents/{consentId} - Get Consent Request
• DELETE/consents/{consentId} - Delete Consent
• GET/consents/{consentId}/authorisations - Get Consent Authorisation Sub-Resources Request
• GET/consents/{consentId}/authorisations/{authorisationId} - Read the SCA status of the consent authorisation

Prerequisite: valid consent (see Create consent) with valid IBAN in "accounts" in the method »Create consent«.

Steps to get account data details:

1st step: GET/accounts - Read Account List

Read the identifiers (resource ID) of the available payment account together with booking balance information, depending on the consent granted. This method requires to provide the consentID as a header parameter, and will return the correct account according to the provided consent.

2nd step: GET/accounts/{account-id} - Read Account Details

Returns details about an account based on the provided resource ID, obtained with the method Read Account List, with balances where applicable.

Prerequisite: valid consent (see Create consent) with valid IBAN in "accounts" and "transactions" in the method »Create consent«.

Steps to get transaction list and details data:

1st step: GET/accounts - Read Account List

Read the identifiers (resource ID) of the available payment account together with booking balance information, depending on the consent granted. This method requires a consentID to be provided as a header parameter, according to which the correct account is returned.

2nd step: GET/accounts/{account-id}/transactions - Read Transaction List

Read transaction reports or transaction lists of a given account addressed by "account-id", depending on the steering parameter "bookingStatus" together with balances.
Important: The »Read Transaction List« call has some query parameters that can be used to narrow down the list of returned data, please check the specifications of this call for more details.

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.

3rd step: GET/accounts/{account-id}/transactions/{transactionId} - Read Transaction Details

Reads transaction details from a given transaction addressed by "resourceId" on a given account addressed by "account-id". This call is only available on transactions as reported in a JSON format.

Prerequisite: valid consent (see Create consent) with valid IBAN in "accounts" and "balances" in the method »Create consent«.

Steps to get balance data:

1st step: GET/accounts - Read Account List

Read the identifiers (resource ID) of the available payment account together with booking balance information, depending on the consent granted. This method requires a "consentID" to be provided as a header parameter, according to which the correct account is returned.

2nd step: GET/accounts/{account-id}/balances Read Balance

Reads account balance data from a given account addressed by "account-id".

Steps to initiate a payment:

1st step: POST/{payment-service}/{payment-product} - Payment initiation request

This method is used to initiate a payment at the ASPSP. Parameters of this call are described in details under the method specification. Important: After the initial »Payment Initiation Request« the user needs to be redirected to the authorisation URL provided in »scaRedirect« of the response.

2nd step: GET/{payment-service}/{payment-product}/{paymentId}/status - Payment initiation status request

This call is optional, but gives essential information regarding the transaction status of a payment initiation.

Optional methods:

• GET/{payment-service}/{payment-product}/{paymentId}/authorisations/{authorisationId} - Read the SCA Status of the payment authorisation
• GET/{payment-service}/{payment-product}/{paymentId} - Get Payment Information
• GET/{payment-service}/{payment-product}/{paymentId}/authorisations - Get Payment Initiation Authorisation Sub-Resources Request

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.

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:

https://api-oauth.bankart.si/psd2/sparkasse/oauth/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/sparkasse/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. 

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.