Specification of the API provided by Alior Bank

---

What is it?

Confirmation of Available Funds allows confirming the availability on the payers account of the amount necessary to execute the payment transaction.

How to make it work?

You have to follow a few easy steps to register, create and build an app using our available APIs:

1. You need to create a new app by going to My APPS and clicking on "Create New APP".

2. Then you will need to register your app by filling in the form with:
- the name of the app
- the selection of services that it will use
- a short description
- OAuth redirect URL
Please remember: all services must be secured by OAuth service first, so always select the Authorisation (AS) services and then the business services that you need.
OAuth redirect URL is the site that the client will be directed to after the authorisation process ends (for example: https://tppapp:8080/callback).

 

3. Once the registration is completed, you will receive a Client ID and Secret.

The Client ID and Secret will be used with all the APIs that you use and they are provided for each app.
Please remember:  the secret will be presented to you only once, so please make note of it.
If you forget the Secret you can always use the "secret reset" service.
If you have a secret and you don't know which app it is for, you can use the "verify secret" service.
Both services can be accessed from an app's profile page (go to My APPS and then click on an app profile tile).

How is my app performing?

Our sandbox offers the analytics functionality which you can use in order to get stats on: success rate, latency, data usage and a few more.
You can see the statistics for a single app or all of you applications.
The analytics functionality is accessed from My APPS and then after clicking on a particular application's profile. It is in the top right secondary menu list.

What do all acronyms mean?

AIS  - Account Information Services - a set of APIs that under the PSD2 regulation give TPPs access to basic information on the account and transaction history that goes three months back
AISP - Account Information Services Provider - an entity that works alongside customer and bank and offers tools that allow companies and consumers to have a consolidated view of their financial situation.
AS - Authorisation Services - APIs that allow secure operations of business APIs. As standard these include OAuth athorisation service.
ASP (ASPSP) - Account Service Provider or Account Servicing Payment Service Provider - Financial institutions that offer payment accounts (e.g. current accounts, credit cards) with online access to those accounts through APIs
CAF or COF - Confirmation of Available Funds or Confirmation of Funds - a set of APIs that allow for verification if a transaction will exceed currently available funds in the payment account
PSP (PISP) -Payment Service Provder or Payment Initiation Service Provider - an organisation that offers companies, retailers, merchants etc. an online solution for accepting electronic payments
PIS - Payment Initiation Services or Payment Information Services - a set of APIs that allow initiation, completion and  checking the status of transfers from payment accounts
TPP (TPPSP) - Third Party Provider or Third Party Payment Service Providers - companies that are providing services as AISPs or PISPs
XSTA (XS2A) - Access to Accounts - allows TPPs  access to the bank accounts of EU consumers

Is this secure?

Yes, we use a few levels of security:

1. Basic Authentication

By registering an application in our portal you will be provided with Client ID and Secret. You should attach this to every API request in corresponding properties in the Request Header e.g:

X-IBM-Client-Secret: xxxxxxxxxxxxxxxxxxxxxxxx
X-IBM-Client-Id: xxxxxxxxxxxxxxxxxxxxx

 

Certificates

In production environment every TPP should have two pair of eIDAS certificates:

- QWAC (Qualified certificate for website authentication)

- QCert for ESeal (Qualified certificate for electronic seal)

Certificates should be sign by one of the Qualified Certificate Authority, according to list on https://webgate.ec.europa.eu/tl-browser .

In sandbox environment you can access our API:

- without any certificates

- with a test certificate from KIR (CA http://www.elektronicznypodpis.pl/certyfikaty/mkw2017test.crt )

- with other trust CA (after conntact with Bank and agree details - by contact form)

For more information please look on the page "Sandbox security modes"

In case your certificates are about to expire or you want to configure a new set of certificates for your application, please provide us with a new set of certificates in advance (at least 2-3 working days). Please make sure to specify the clientId and the kid of your new certificate.

Communication protocol

As the communication protocol, HTTP / 2 or HTTP 1.1 will be used, secured with TLS 1.2+ protocol with mutual authentication of the client and the server using X.509v3 (Mutual authentication) certificates - eIDAS QWAC (Qualified certificate for website authentication) certificate. Due to the requirement to ensure non-repudiation (signing requests and responses), only the POST method will be used in http communication.

JWS

At the message level, to ensure non-repudiation, a JSON Web Signature should be used, according to the RFC 7515 standard (https://tools.ietf.org/html/rfc7515). For JWS we use QCert for ESeal certificate type. The signature must be placed in every request in the header named X-JWS-SIGNATURE. Signature is in detached form and contens sign for whole body. Responses from ASPSP are also sign with Bank certificate.

For more information please look on the page "Sandbox security modes"

The header X-JWS-Signature response field is enriched with data in kid, x5u and x5t#S256 fields.

Example:

eyJhbGciOiJSUzI1NiIsImtpZCI6IkFMSU9SLVBMLVNCLVBTRDItSldTLVBVQkxJQy0yMDIwLTAxIiwieDV1IjoiaHR0cHM6Ly9BZGRyZXNzV2l0aFB1YmxpY0tleSIsIng1dCNTMjU2IjoiNDdERVFwajhIQlNhLV9USW1XKzVKQ2V1UWVSa201Tk1wSldaRzNoU3VGVSJ9..

Content:

{"alg":"RS256","kid":"ALIOR-PL-SB-PSD2-JWS-PUBLIC-2020-01","x5u":"https://AddressWithPublicKey","x5t#S256":"47DEQpj8HBSa-_TImW+5JCeuQeRkm5NMpJWZG3hSuFU"}..

The TPP can use certificate which was registered during onbording process.
The new is that the TPP can register more than one certificate and manage it by kid which is introducing in X-JWS-Signature.
This option is allowed by sending email form to our Administrators.
This functionality can be used when you want to change the certificate dynamically, for example if you know that your certificate will be expired in near future and do you want to use new one.

 

 

Refresh Token

This service doesn't have any token. At this point, API does not support Refresh Tokens.

Consent CAF rules

The CAF is available for you only if you know the account number of the PSU and the consent.
The consent is given by the PSU which is the owner of the account or have the attorney to the account.
 

CAF API example

Request:

--header 'Accept-Charset: UTF-8' \
--header 'Accept: application/json' \
--header 'Accept-Encoding: deflate' \
--header 'contentType: application/json' \
--header 'X-JWS-SIGNATURE: jws_signature' \
--header 'X-REQUEST-ID: UUID format (Variant 1, Version 1)' \
--header 'X-IBM-Client-Id: xxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
--header 'X-IBM-Client-Secret: xxxxxxxxxxxxxxxxxxxxxxxxx \

--data '{

{
"requestHeader":{
"requestId":"UUID format (Variant 1, Version 1) as in X-REQUEST-ID",
"userAgent":"browser user agent",
"ipAddress":"psu browser ip",
"sendDate":"2019-05-03T13:43:32.330Z",
"tppId":"tpp identifier"
},
"accountNumber":"PL82249000050000400053573605",
"amount":"100.00",
"currency":"PLN"
}

}

Response:

{
       fundsAvailable: true,
       responseHeader:{
              "requestId":"UUID format (Variant 1, Version 1) as in X-REQUEST-ID",
              "sendDate":"2019-05-03T13:43:32.330Z",
              "isCallback": false
       }
}

CAF test scenarios

The response from the CAF endpoint, containing a funds status, can be parametrized, by passing account number for the customer which is available on the Sandbox environment.

The response will be different:

• if the CAF amount will be less than available balance  - fundsAvailable will be set to true.
• if the CAF amount will be greater than or equals to available balance  - fundsAvailable will be set to false.

 

Before the using this API on the production environment you have to check the scenario as follows:

1. The CAF request with amount less than available balance.
2. The CAF request greater than or equals than available balance.
3. The CAF request with incorrect data, for example wrong account number.