AIS API Quick Start Guide

The PSD2 AIS API provides information related to the PSU’s (i.e. a Bank Customer in PSD2 terminology) Accounts, Credit Cards and their respective transactions.
To make use of this API, you should follow the steps described below.

 

1. Enrollment

To use any API offered in Piraeus Bank’s rAPIdLink Developer Portal, a registered account and application are required.

The following steps refer to the enrollment process performed through the Developer Portal.

1)  Register or log into rAPIdLink Developer Portal

2)  Create an Application (or app), for instance “myapp001”. App definition requires the following information: 

Name

(Mandatory) The app name displayed to the PSUs in various cases, such as when granting the TPP access to their information

Description

(Optional) Informative field where the TPP can briefly describe the app

OAuth Redirect URI

(Mandatory) OAuth calls will redirect to this address. The response data is returned as a series of query parameters.

A dummy url, like https://127.0.0.1/this.is.the.redirect.url, would be enough to get started if you have not decided on the final address (you can change it later as many times as you wish) or if your application is not web-based (as long as you properly handle the response)

Please save the clientid and client secret provided upon application creation. This is the only chance you have to store the client secret, although a reset functionality is provided in case the client secret is lost.

3)  Navigate to the API Products page from the portal’s Main Menu, select the PSD2 AIS Product and scroll down in the product’s page. Click on the “Subscribe” button to allow your application (“myapp001”) to use the particular API product. 

Congratulations! Your application can now perform requests to the respective APIs of the PSD2 AIS Product.

 

Before You Start

All AIS Service calls require the following headers

    • X-Request-ID: a client generated guid to uniquely identify each call
    • X-IBM-Client-Id: myapp001.ClientId

 

2. OAuth Authorization

 

PSU Authorizes the Application

Use the OAuth “Authorization URL”. Open it on a browser so that PSU will authorize access to “myapp001”. Please note that the OAuth information (Links & Scopes) are different in sandbox and production. You should find the proper information in the AIS Service within each method’s security section. As of this writing the OAuth URLs for PSD2 APIs are:

Production OAuth

Authorization URL

https://openbank.piraeusbank.gr/identityserver/connect/authorize

Token URL

https://openbank.piraeusbank.gr/identityserver/connect/token

Refresh URL

https://openbank.piraeusbank.gr/identityserver/connect/token

Scopes

winbankAccess winbankAccess.info (access to respective resources)

offline_access (required for refresh tokens)

Sandbox OAuth

Authorization URL

https://api.rapidlink.piraeusbank.gr/piraeusbank/production/v3.1/oauth/oauth2/authorize

Token URL

https://api.rapidlink.piraeusbank.gr/piraeusbank/production/v3.1/oauth/oauth2/token

Refresh URL

https://api.rapidlink.piraeusbank.gr/piraeusbank/production/v3.1/oauth/oauth2/token

Scopes

sandboxapi (access to respective resources)

offline_access (required to refresh token)

The mandatory query parameters used in the Authorization URL are:  
response_type=code&client_id=<ClientId>&redirect_uri=<RedirectUrl>&scope=<Scope>

There is also an additional query parameter in the Production OAuth Authorization URL, which is optional and sets the language of returned bilingual response texts (until session expires): 
UI_Locales=el-GR

 

For sandbox please use:

https://api.rapidlink.piraeusbank.gr/piraeusbank/production/v3.1/oauth/oauth2/authorize?response_type=code&client_id=<myapp001.ClientId>&redirect_uri=<myapp001.RedirectUrl>&scope=sandboxapi+offline_access
Note that scope offline_access allows for refreshing the token without re-authenticating the PSU.

a)       On the web page the PSU will enter his credentials. For Sandbox, use one of our test PSUs:

Username

Password

UserA

123

UserB

123

UserC

123

b)      Upon completion, the browser will be redirected to the Redirect URL you have provided for the app “myapp001” registration. E.g. <myapp001.RedirectUrl>?code=ABCD

Extract the URL path parameter code and use it to get a OAuth token on the next step. Please note that each code expires after a few seconds.

 

Get an OAuth Token

Use the code from previous step (that is “ABCD”), to get an OAuth token. Call AIS Product / OAuth Service method POST /oauth/token and provide the following form-url-encoded parameters within the request body:

  • clientId: myapp001.clientId
  • clientSecret: myapp001.clientSecret
  • grant_type: authorization_code
  • redirect_uri: myapp001.redirect_uri
  • code (from previous step): "ABCD"

 

The Access_token_response returned contains:

  • token_type: always Bearer
  • access_token: to be used in all subsequent calls on the Authorization header.       (Authorization = “Bearer <access_token>”) .
  • expires_in: The Expiration of the short lived access_token in seconds since the time of it’s retrieval. As of this writing expires_in is 3600.
  • refresh_token: Use it to refresh your access_token when expired using the respective method in the OAuth Service. The refresh_token expires in 90 days.

The token will be used to create the Authorization header, Authorization = “Bearer <access_token>” that will authenticate all your calls from now on.

Response:

{
      "token_type": "Bearer",
      "access_token": "AAjNS00YTQ4LWEjBl7uKgGRqn0fBJFrsz",
      "expires_in": 3600,
      "scope": "sandboxapi",
      "refresh_token": "AAIMaHP-nRIjZyLowTLnKRfsy0ZLoRFv53RoOraXg37Fltme36WwND4"
}

 

On Access Token Expiration, Refresh It (Optional)

Your Access_token is short lived but can be refreshed using the following call:

POST OAuth <Token URL> with the following form url encoded parameters in body:

  • grant_type: refresh_token
  • client_Id:< myapp001.clientid>
  • client_secret:< myapp001.clientSecret>
  • refresh_token:<previousToken.refreshToken>

Please note, that token refresh is supported only in production.

Data retrieval will be available with the above Consent and Access Tokens, without re-authorization from the PSU for 90 days or until the API returns an error that says otherwise.

When the consent or access token expire or get rejected by the Service, please repeat the “Get User Consent” procedure to get a new consent and token for another 90 days.

 

2. Get the User Consent

The User Consent is for application “myapp001” to access his Account and Credit Cards information and requires string customer authentication (SCA)

 

Post an “allPsd2” consent

Use the AIS Service POST /v3.1/consents and post in the body an allAccounts consent flagged to provide account and card list for all accounts and card accounts (allAccounts) and valid until the next day (at a minimum).

 

Request:

  • GET https://api.rapidlink.piraeusbank.gr/piraeusbank/production/psd2/ais/v3.1/consents
  • X-Request-ID: 752107ca-719f-42e6-9378-57d12a70029b
  • Consent-ID: a56a9bc8-4a12-4dea-aa5f-83d7040d71c5
  • Authorization: Bearer AAjNS00YTQ4LWEjBl7uKgGRqn0fBJFrsz
  • Accept: application/json
  • x-ibm-client-id: <myapp001.clientid>
  • with body:

{
       "access": {
              "accounts": [],
              "balances": [],
              "allPsd2": "allAccounts"
       },
       "recurringIndicator": true,
       "validUntil": "2019-06-30",
       "frequencyPerDay": 255,
       "combinedServiceIndicator": false
}

 

Response:

201 (Created) with body:

{
       "consentStatus": "valid",
       "consentId": "a56a9bc8-4a12-4dea-aa5f-83d7040d71c5",
       "_links": {
              "status": {
                     "href": "https://api.rapidlink.piraeusbank.gr/piraeusbank/production/psd2/ais/v3.1/consents/a56a9bc8-4a12-4dea-aa5f-83d7040d71c5/status"
              },
              "self": {
                     "href": "https://api.rapidlink.piraeusbank.gr/piraeusbank/production/psd2/ais/v3.1/consents/a56a9bc8-4a12-4dea-aa5f-83d7040d71c5"
              }
       }
}

 

3. Retrieve All Accounts and Card Accounts

Use the “allPsd2” consent and the authorization from previous steps and retrieve the Account and Cards using methods:

  • get /v3.1/accounts
  • get /v3.1/card-accounts

Please note that “allPsd2” consent has particular constraints:

  • you may only call the above methods and the Balance will not be returned
  • you may only call them once

Request:

  • GET https://api.rapidlink.piraeusbank.gr/piraeusbank/production/psd2/ais/v3.1/accounts
  • X-Request-ID: 551e4ad4-2a87-4f5d-b05b-17a4a5bb77fd
  • Consent-ID: a56a9bc8-4a12-4dea-aa5f-83d7040d71c5
  • Authorization: Bearer AAjNS00YTQ4LWEjBl7uKgGRqn0fBJFrsz
  • Accept: application/json
  • x-ibm-client-id: <myapp001.clientid>

Response:

{
       "accounts": [{
                     "iban": "GR2801718220007022123123123",
                     "currency": "EUR",
                     "name": "ΤΑΜΙΕΥΤΗΡΙΟ 1",
                     "displayName": "ΤΑΜΙΕΥΤΗΡΙΟ 1",
                     "product": "SAVINGS ACC.-R-",
                     "status": "enabled"
           }, {

                     "iban": "GR9001718220007025111222333",
                     "currency": "EUR",
                     "name": "SAVINGS ACCOUNT 2",
                     "displayName": "SAVACC 2",
                     "product": "SAVINGS ACC.-R-",
                     "status": "enabled"
              }

       ]
}


Request:

  • GET https://api.rapidlink.piraeusbank.gr/piraeusbank/production/psd2/ais/v3.1/card-accounts
  • X-Request-ID: 551e4ad4-2a87-4f5d-b05b-17a4a5bb77fd
  • Consent-ID: a56a9bc8-4a12-4dea-aa5f-83d7040d71c5
  • Authorization: Bearer AAjNS00YTQ4LWEjBl7uKgGRqn0fBJFrsz
  • Accept: application/json
  • x-ibm-client-id: <myapp001.clientid>

Response:

{
       "card-accounts": [{
                     "caardAccountType": "prepaid",
                     "currency": "EUR",
                     "pan": "5311460299913003"
              }]

}

 

 

4. Create the Final Consent

The final consent will include the specific Accounts and Card Account that you want to have access, explicitly defined for their details, balances and transactions.

 

Request:

  • POST https://api.rapidlink.piraeusbank.gr/piraeusbank/production/psd2/ais/v3.1/consents
  • X-Request-ID: 5636e7cc-51ac-4a41-9a7b-d0b84565cc50
  • Consent-ID: a56a9bc8-4a12-4dea-aa5f-83d7040d71c5
  • Authorization: Bearer AAjNS00YTQ4LWEjBl7uKgGRqn0fBJFrsz
  • Accept: application/json
  • x-ibm-client-id: <myapp001.clientid>
  • Content-Type: application/json
  • Body:

{
       "access": {
              "accounts": [{
                           "iban": "GR2801718220007022123123123",
                           "currency": "EUR"
                     }, {
                           "iban": "GR9001718220007025111222333",
                           "currency": "EUR"
                     }
              ],
              "balances": [{
                           "iban": "GR2801718220007022123123123",
                           "currency": "EUR"
                     }, {
                           "iban": "GR9001718220007025111222333",
                           "currency": "EUR"
                     }
              ],
              "transactions": [{
                           "iban": "GR2801718220007022123123123",
                           "currency": "EUR"
                     }, {
                           "iban": "GR9001718220007025111222333",
                           "currency": "EUR"
                     }
              ]
       },
       "recurringIndicator": true,
       "validUntil": "2019-08-30",
       "frequencyPerDay": 255,
       "combinedServiceIndicator": false
}

 

Please note that the response will return:

  • Status = received
  • Guidelines on how to authorize it using SCA

Response:

  • 201 (Created) with body:

{
   "consentStatus": "received",
   "consentId": "a56a9bc8-4a12-4dea-aa5f-83d7040d71c5",
   "_links": {
          "startAuthorisation": {
                 "href": "https://api.rapidlink.piraeusbank.gr/piraeusbank/production/psd2/ais/v3.1/consents/a56a9bc8-4a12-4dea-aa5f-83d7040d71c5/authorisations",
                 "verb": "POST"
          },
          "self": {
                 "href": "https://api.rapidlink.piraeusbank.gr/piraeusbank/production/psd2/ais/v3.1/consents/a56a9bc8-4a12-4dea-aa5f-83d7040d71c5",
                 "verb": "GET"
          },
          "status": {
                 "href": "https://api.rapidlink.piraeusbank.gr/piraeusbank/production/psd2/ais/v3.1/consents/a56a9bc8-4a12-4dea-aa5f-83d7040d71c5/status",
                 "verb": "GET"
          }
   }
}

 

5. Start Authorization of the Final Consent with SCA 

Start Authorization using the “startAuthorisation” link provided on consent creation

The Start Authorization call will return the Authentication methods available and the chosen one.

Request:

  • POST: https://api.rapidlink.piraeusbank.gr/piraeusbank/production/psd2/ais/v3.1/consents/a56a9bc8-4a12-4dea-aa5f-83d7040d71c5/authorisations
  • X-Request-ID: 65a0f9c2-a106-4813-a998-3ec320b7396d
  • Consent-ID (on path): a56a9bc8-4a12-4dea-aa5f-83d7040d71c5
  • Authorization: Bearer AAjNS00YTQ4LWEjBl7uKgGRqn0fBJFrsz
  • Accept: application/json
  • x-ibm-client-id: <myapp001.clientid>
  • Content-Type: application/json
  • BODY: empty

 

Response:

  • 201 (Created) with body:

{
       "scaStatus": "scaMethodSelected",
       "authorisationId": "a469ff12-c90a-4700-89d4-bf1c7709dc5e",
       "_links": {
              "authoriseTransaction": {
                     "href": "https://api.rapidlink.piraeusbank.gr/piraeusbank/production/psd2/ais/v3.1/consents/a56a9bc8-4a12-4dea-aa5f-83d7040d71c5/authorisations/a469ff12-c90a-4700-89d4-bf1c7709dc5e"
              }
       },
       "scaMethods": [{
                     "authenticationType": "PUSH_OTP",
                     "authenticationMethodId": 4,
                     "name": "ExtraPin through Notification in winbank mobile app"
              }, {
                     "authenticationType": "SMS_OTP",
                     "authenticationMethodId": 2,
                     "name": "ExtraPin through SMS on the declared mobile phone number"
              }
       ],
       "chosenScaMethod": {
              "authenticationType": "PUSH_OTP",
              "authenticationMethodId": 4,
              "name": "ExtraPin through Notification in winbank mobile app"
       }
}

 

6. Select SCA Method (If Applicable)

If there are more than one SCA Methods available and the PSU wishes to change method, the following call is available. This step is optional.

e.g. PSU might prefer SMS instead of PUSH

Sample Request:

  • PUT: https://api.rapidlink.piraeusbank.gr/piraeusbank/production/psd2/ais/v3.1/consents/a56a9bc8-4a12-4dea-aa5f-83d7040d71c5/authorisations/a469ff12-c90a-4700-89d4-bf1c7709dc5e
  • X-Request-ID: 2ee7dd41-60e2-4b2e-8e9d-e54d948dbf58
  • Consent-ID (on URL): a56a9bc8-4a12-4dea-aa5f-83d7040d71c5
  • AuthorisationID (on URL): a469ff12-c90a-4700-89d4-bf1c7709dc5e
  • Authorization: Bearer AAjNS00YTQ4LWEjBl7uKgGRqn0fBJFrsz
  • Accept: application/json
  • x-ibm-client-id: <myapp001.clientid>
  • Content-Type: application/json
  • BODY:

{
       "authenticationMethodId": "2"
}

 

Sample Response:

  • 200 (ok) with body:

  {
       "scaStatus": "scaMethodSelected",
       "chosenScaMethod": {
              "authenticationType": "SMS_OTP",
              "authenticationMethodId": "2",
              "name": "ExtraPin through SMS on the declared mobile phone number"
       },
       "_links": {
              "authoriseTransaction": {
                     "href": "https://api.rapidlink.piraeusbank.gr/piraeusbank/production/psd2/ais/v3.1/consents/a56a9bc8-4a12-4dea-aa5f-83d7040d71c5/authorisations/a469ff12-c90a-4700-89d4-bf1c7709dc5e"
              }
       }
}

 

7. Complete the SCA

The SCA chosen methods will guide you on how to complete the SCA using one of the following options:

Enter the SCA OTP provided by the PSU (if applicable)

Please note that the following supported Authentication method require SCA.

  • CHIP_OTP
  • PUSH_OTP
  • SMS_OTP

If you have on the above methods selected please use the SCA for Sandbox (3288000).

 

Sample Request:

  • PUT: https://api.rapidlink.piraeusbank.gr/piraeusbank/production/psd2/ais/v3.1/consents/a56a9bc8-4a12-4dea-aa5f-83d7040d71c5/authorisations/fd29730f-3c6d-4655-841e-1e0f864039ad
  • X-Request-ID: d293b00d-4703-49b0-b83d-93950cddd9b2
  • Consent-ID (on URL): a56a9bc8-4a12-4dea-aa5f-83d7040d71c5
  • AuthorisationID (on URL): a469ff12-c90a-4700-89d4-bf1c7709dc5e
  • Authorization: Bearer AAjNS00YTQ4LWEjBl7uKgGRqn0fBJFrsz
  • Accept: application/json
  • x-ibm-client-id: <myapp001.clientid>
  • Content-Type: application/json
  • BODY:

{
       "scaAuthenticationData": "3288000"
}

 

Sample Response

200 (ok) with body:

{
       "scaStatus": "finalised",
}

Inform the PSU to Complete the SCA Using the Bank Mobile App (applicable only for TOUCH_OTP)

The SCA through the Bank Mobile App is not a concern of this document since it may (and will) change without causing any changes to the API. However, it will always be straightforward.

 

Verify that the Consent is Valid after SCA (optional, applicable only for TOUCH_OTP)

When the TOUCH_OTP is selected, the PSU completes the SCA using his Banking Mobile App outside the TPP – API interaction. Therefore, after he has completed the SCA, a check on the consent status will ensure that the consent is now valid.

 

Sample Request:

  • GET: https://api.rapidlink.piraeusbank.gr/piraeusbank/production/psd2/ais/v3.1/consents/a56a9bc8-4a12-4dea-aa5f-83d7040d71c5/status
  • X-Request-ID: 8916c9a2-f746-4eaf-a012-311139c59cbf
  • Consent-ID (on URL): a56a9bc8-4a12-4dea-aa5f-83d7040d71c5
  • AuthorisationID (on URL): a469ff12-c90a-4700-89d4-bf1c7709dc5e
  • Authorization: Bearer AAjNS00YTQ4LWEjBl7uKgGRqn0fBJFrsz
  • Accept: application/json
  • x-ibm-client-id: <myapp001.clientid>
  • Content-Type: application/json
  • BODY: empty

 

Sample Response:

  • 200 (ok) with body:

{
       " consentStatus": " valid"
}

 

8. Retrieve Full Account and Credit Cards Information

Use the consent id and the authorization from previous steps and call all methods available for Account and Card Account information.

 

Please note that:

  • Account_id and CardAccount_id (that is, their resource ids) change every time your consent changes. Upon consent change, you need to ask again for the full list of Accounts / Card Accounts and retrieve from there their new ids.
  • Dates are on Greece Athens Time (GMT+2 or +3 with daylight savings)