Payments (PIS) RO
Specification of the API provided by Alior Bank
What is it?
How to make it work?
How is my app performing?
What do all acronyms mean?
Is this secure?
Refresh token
Consent rules
Exchange Token
API request rules
What is it?
Payment Initiation Services is a set of services that offers the possibility to initiate, complete and check the status of transfers from a customer's payment account. These APIs are mostly directed to merchants and payment service providers.
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. It can be something like: 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 your applications.
The analytics functionality is accessed from My APPS and then after clicking on a particular application's profile. It is on 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 authorisation 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 on the payment account
PSP (PISP) -Payment Service Provider 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: pC2vH1hG3qX6sE6eG0lC2pA4xW5oU4hQ0jP5dJ6dH7rR2cG0lC X-IBM-Client-Id: 52d781f6-54e6-43e8-a93e-456943e89fa5
2. OAUTH 2.0
We use the OAuth standard to allow clients to grant permission to account and payment resources for other websites. To call the desired API you will have to make a few steps:
Step 1 - authorize request - POST to our API endpoint:
POST https://gateway.developer.aliorbank.pl/openapipl/sb/RO/v2_1_1.1/auth/v2_1_1.1/authorize
--header 'X-JWS-SIGNATURE: ' \
--header 'X-REQUEST-ID: UUID format (Variant 1, Version 1)' \
--header 'X-IBM-Client-Id: pC2vH1hG3qX6sE6eG0lC2pA4xW5oU4hQ0jP5dJ6dH7rR2cG0lC' \
--header 'X-IBM-Client-Secret: 52d781f6-54e6-43e8-a93e-456943e89fa5 \
--header 'contentType: application/json' \
--data '{
{
"requestHeader": {
"requestId": UUID format (Variant 1, Version 1) the same value as in X-REQUEST-ID,
"userAgent": "Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:57.0) Gecko/20100101 Firefox/57.0",
"ipAddress": "000.000.0.0",
"sendDate": "2017-11-24T14:13:05.424Z",
"tppId": "myId",
"isCompanyContext": false,
"psuIdentifierType": "string",
"psuIdentifierValue": "string"
},
"response_type": "code",
"client_id": "1b3456d3-bc33-4190-80c8-623bb9a0b12d",
"scope": "ais-accounts",
"scope_details": {
"privilegeList":[
{"accountNumber":"",
"ais-accounts:getAccounts":{"scopeUsageLimit":"multiple"}
}
],
"scopeGroupType":"ais-accounts",
"consentId":"MYTPP-b3ae3d34",
"scopeTimeLimit":"2019-09-01T04:45:48",
"throttlingPolicy":"psd2Regulatory"
},
"redirect_uri": "http://tppapp:3000/auth/oauth2/callback",
"state": "your state"
}
}'
*The meaning of these parameters can be found in the API definition.
In response, the API will send the AuthorizeResponse object (HTTP_CODE 200). In this object you will find the aspspRedirectUri parameter with address to our Internet Banking Application Simulator, where the PSU can review and authenticate grants for your application. You have to redirect the PSU to this URL address.
The redirection call will send the PSU browser on the following form:
The username and password are as follows:
| username | password | account number(s) | brand | |
| 1 | 10007423 | 12345678 | RO56ALBP0RON421000045875 | Alior Bank Services Romania |
| 2 | 10023617 | 12345678 | RO25ALBP2EUR426000044627 | Alior Bank Exchange Currency Romania |
We will send the result of PSU authentication via the PSU browser. You can go to the next step after you receive access_code
access_code=AAJSLgy-OMo9DlDpYINxTB-Njawqz0bfmuoPRUG5yJea0zkgcURr_W3sCADKH3oWzLum-jiRuwGpn0AS9_SJcJGBa7Nkf_evHUm7zz119yyqw3DxdZIrUc6lHI0g-fjCV8hTP7zt....
Step 2 - get access Token - POST to our API gateway with basic authentication and your access code from step 1:
curl --request POST \
--url https://gateway.developer.aliorbank.pl/openapipl/sb/RO/v2_1_1.1/auth/v2_1_1.1/token \
--header 'X-JWS-SIGNATURE: ' \
--header 'X-REQUEST-ID: UUID format (Variant 1, Version 1)' \
--header 'X-IBM-Client-Id: pC2vH1hG3qX6sE6eG0lC2pA4xW5oU4hQ0jP5dJ6dH7rR2cG0lC' \
--header 'X-IBM-Client-Secret: 52d781f6-54e6-43e8-a93e-456943e89fa5 \
--header 'contentType: application/json' \
--data '{
{ "requestHeader":
{
"requestId": UUID format (Variant 1, Version 1) the same value as in X-REQUEST-ID ,
"userAgent": "Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:57.0) Gecko/20100101 Firefox/57.0",
"ipAddress": "000.000.0.0",
"sendDate": "2017-11-24T14:13:05.424Z",
"tppId": "your id",
"isDirectPsu": false
},
"Code": "7rXMHbKUVIf…..",
"grant_type": "authorization_code",
"redirect_uri": "http://tppapp:3000/auth/oauth2/callback",
"client_id": "52d781f6-54e6-43e8-a93e-456943e89fa5",
"client_secret": "pC2vH1hG3qX6sE6eG0lC2pA4xW5oU4hQ0jP5dJ6dH7rR2cG0lC"
}
}'
Please take note that the field with name "Code" where you put the access code from step 1 starts with a capital letter.
In response, you will get your access Token with the basic information about the user accepted scope, token valid time and so on:
{
"token_type": "bearer",
"access_token": "kYzZlNTFiN2UtMj……",
"expires_in": 1560241352000,
"scope": "ais-accounts",
"scopeDetails": {
"consentId": "MYTPP-b3ae3d34",
"scopeTimeLimit": "2019-09-01T04:45:48",
"throttlingPolicy": "psd2Regulatory",
"scopeGroupType": "ais-accounts",
"privilegeList": [ {
"ais-accounts:getAccounts": {"scopeUsageLimit": "multiple"},
"accountNumber": ""
}]
},
"responseHeader": {
"requestId": "UUID format (Variant 1, Version 1)",
"sendDate": "2019-03-13T08:22:32.522Z",
"isCallback": false
}
}
This token will give you access to the information about the PSU accounts.
STEP 3 - API call - now you can use your accessToken to call API like for example:
curl --request POST \
--url https://gateway.developer.aliorbank.pl/openapipl/sb/RO/v2_1_1.1/auth/v2_1_1.1/getAccounts \
--header 'AUTHORIZATION: Bearer kYzZlNTFiN2UtMj……' \
--header 'X-JWS-SIGNATURE: ' \
--header 'X-REQUEST-ID: UUID format (Variant 1, Version 1)' \
--header 'X-IBM-Client-Id: pC2vH1hG3qX6sE6eG0lC2pA4xW5oU4hQ0jP5dJ6dH7rR2cG0lC' \
--header 'X-IBM-Client-Secret: 52d781f6-54e6-43e8-a93e-456943e89fa5 \
--header 'contentType: application/json' \
--data '{
{"requestHeader":
{"requestId":"d2da0db0-4570-11e9-81cb-53957d7bb4d1",
"userAgent":"Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:57.0) Gecko/20100101 Firefox/57.0",
"ipAddress":"000.000.0.0",
"sendDate":"2019-03-13T09:17:13Z"
,"tppId":"your id",
"token":"Bearer kYzZlNTFiN2UtMj……",
"isDirectPsu":false,
"directPsu":false
}
}
}'
In response, you will get the PSU data. In this example data are as follows:
{
"accounts": [
{
"accountNumber": "RO26ALBP0RON421000168344",
"accountType": {
"code": "RCA00",
"description": "Current Account"
},
"accountTypeName": "Current account"
}
],
"responseHeader": {
"requestId": "61833c2c-38a2-11eb-b5de-2f9e1c0329ed",
"sendDate": "2020-12-07T15:39:25.560Z",
"isCallback": false
}
}
Please take note that the field AUTHORIZATION in request header and the requestHeader : Object.token have the same value.
3. Certificates
In a production environment every TPP should have a pair of eIDAS certificates:
- QWAC (Qualified certificate for website authentication)
- QCert for ESeal (Qualified certificate for electronic seal)
Certificates should be signed by one of the qualified Certificate Authority, according to list on https://webgate.ec.europa.eu/tl-browser .
In a sandbox environment you can access our API:
- without any certificates
- with test certificate from KIR (CA http://www.elektronicznypodpis.pl/certyfikaty/mkw2017test.crt )
- with another trust CA (after contact with the Bank and agree on details - by contact form)
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.
4. 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.
5. 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 contents sign for the whole body. Responses from ASPSP are also signed with Bank certificate.
Refresh Token
At this point, API does not support Refresh Tokens.
Consent rules
You should take careful note of what you are setting in authorize request. We set a few rules to this step, which allow us to present your consent in our confirmation form. These rules are:
- We present a homogeneous, consistent scope of consents for all privileges received from TPP.
- The PSU gives the uniform consent, so you have to set the same consent privileges for all accounts listed in scope_details
Please take into account the following logic:
- scopeTimeLimit value in /authorize service should not be greater than 180 days (starting from May 28, 2023 in Sandbox and from July 25, 2023 on Production)
- scopeUsageLimit attribute can be set to single mode only
- the fields scopeGroupType have to be set with value pis
- you can not set privileges from other scopes
- the only one privilige is allowed
Exchange Token
After payment initiation you can exchange your token that was used for payment initiation to new one with the privilege to read payment status. You can do this using /v2_1_1.1/auth/v2_1_1.1/token. Example below:
1. Payment Initiation
Request:
POST https://......................./v2_1_1.1/payments/v2_1_1.1/domestic
X-IBM-Client-Secret: …………
X-IBM-Client-Id: …………..
X-JWS-SIGNATURE: …………….
Authorization: Bearer AAA
X-REQUEST-ID: …………………………..
SENT
{
"requestHeader":{
"requestId":"…………………",
"userAgent":"Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:57.0) Gecko/20100101 Firefox/57.0",
"ipAddress":"xxx.xxx.x.x",
"sendDate":"2020-12-07T16:32:51.613Z",
"tppId":"xxxxxxxxxxxxxx",
"token":"Bearer ………………………….."
},
"recipient":{
"accountNumber":"RO60XKGC0371026225864533",
"nameAddress":{"value":["Jan","Kowalski","Recipient Address 1","Recipient Address 2"]}
},
"sender":{
"accountNumber":"RO26ALBP0RON421000168344"},
"transferData":{"amount":"3.86",
"description":"OPENAPI domestic SENT",
"currency":"RON"
},
"tppTransactionId":"…………………….",
"deliveryMode":
"StandardD1",
"system":"SENT",
"executionMode":"Immediate"
}
Response:
{
"paymentId":"OA-BV1cujDtSJW49sOGbcf00g",
"generalStatus":"submitted",
"detailedStatus":"unknown.",
"responseHeader":{ "requestId":"77d2dcea-38a1-11eb-b5de-553f0b259249", "sendDate":"2020-12-07T15:32:54.246Z", "isCallback":false } }
REGIS
{
"requestHeader":{
"requestId":"830d9e71-38a1-11eb-b5de-d190be7cad8d",
"userAgent":"Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:57.0) Gecko/20100101 Firefox/57.0",
"ipAddress":"xxx.xxx.xxx.x",
"sendDate":"2020-12-07T16:33:10.453Z",
"tppId":"xxxxxxxx",
"token":"Bearer ……………………….."
},
"recipient":{
"accountNumber":"RO60XKGC0371026225864533",
"nameAddress":{"value":["Jan","Kowalski","Recipient Address 1","Recipient Address 2"]}
},
"sender":{
"accountNumber":"RO26ALBP0RON421000168344"},
"transferData":{"amount":"54.68",
"description":"OPENAPI domestic REGIS",
"currency":"RON"
},
"tppTransactionId":"……………………………………",
"deliveryMode":
"StandardD0",
"system":"REGIS",
"executionMode":"Immediate"
}
2. ExchangeToken
Request:
POST https://................./v2_1_1.1/auth/v2_1_1.1/token
X-REQUEST-ID: …………………….
X-JWS-SIGNATURE: …………….
X-IBM-Client-Id: …………..
X-IBM-Client-Secret: ………………………
{
"requestHeader": {
"requestId": "………………………..",
"userAgent": "Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:57.0) Gecko/20100101 Firefox/57.0",
"ipAddress": "1.1.1.1", "sendDate": "2019-04-12T11:55:12Z",
"tppId": "………………………."
},
"grant_type": "exchange_token",
"exchange_token": "Bearer AAA",
"scope": "pis",
"scope_details": {
"privilegeList": [
{
"pis:getPayment": {
"scopeUsageLimit": "single",
"paymentId": "OA-RrMZasEtmVtddLCCi",
"tppTransactionId": "TPPe65c775a-d2d6-4b3a-a5e9-906375156b3f"
}
}
],
"scopeGroupType": "pis",
"consentId": "MYTPP-6a0498dc",
"scopeTimeLimit": "2019-05-20T04:45:48",
"throttlingPolicy": "psd2Regulatory"
}
}
Response:
{
"token_type": "bearer",
"access_token": "BBB",
"expires_in": 1557658554000,
"scope": "pis",
"scopeDetails": {
"consentId": "MYTPP-6a0498dc",
"scopeTimeLimit": "2019-05-20T04:45:48",
"throttlingPolicy": "psd2Regulatory",
"scopeGroupType": "pis",
"privilegeList": [{"pis:getPayment": {
"tppTransactionId": "TPPe65c775a-d2d6-4b3a-a5e9-906375156b3f",
"paymentId": "OA-RrMZasEtmVtddLCCi",
"scopeUsageLimit": "single"
}}]
},
"responseHeader": {
"requestId": "…………………….",
"sendDate": "2019-04-12T10:55:54.293Z",
"isCallback": false
}
}
3. getPayment
Request:
POST https://........./v2_1_1.1/payments/v2_1_1.1/getPayment
X-IBM-Client-Secret: ………..
X-IBM-Client-Id: ………………
X-JWS-SIGNATURE: …………….
Authorization: Bearer BBB
X-REQUEST-ID: ……………………
{
"requestHeader": {
"requestId": "………………………",
"userAgent": "Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:57.0) Gecko/20100101 Firefox/57.0",
"ipAddress": "1.1.1.1",
"sendDate": "2017-11-24T14:13:05.424Z",
"tppId": "MYTPP-918eb5",
"token": "Bearer BBB"
},
"paymentId": "OA-RrMZasEtmVtddLCCi",
"tppTransactionId": "TPPe65c775a-d2d6-4b3a-a5e9-906375156b3f"
}
Response:
{
"paymentId": "OA-RrMZasEtmVtddLCCi",
"generalStatus": "done",
"detailedStatus": "brak dodatkowych informacji",
"executionMode": "Immediate",
"responseHeader": {
"requestId": "………………………….",
"sendDate": "2019-04-12T10:55:55.289Z",
"isCallback": false
}
}
API request rules
Having the consent for PIS the TPP can send payment initialisation request. This request has to fulfil the rules as follows:
- the field tppTransactionId has to be set by TPP
- the TPP has to copy sender account number from token response
- all of the request data have to be compliance with consent
- please be aware that for split payment transactions, the description field will not be presented to the user and transferred to the tax office (despite it being obligatory on production environment). That is the value of the spDescription field, which will be transferred to the tax office and visible in the transaction history.