PIS API Quick Start Guide

The PIS Product provides support for Monetary Transfers from a PSU’s account towards:

  • an Account of the same PSU within the same bank (Piraeus Bank)
  • an Account of another PSU within the same bank  (Piraeus Bank)
  • an Account in another bank within the same country or abroad

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 PIS 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 PIS Product.

 

Before You Start

All PIS Service calls require the following headers

    • X-IBM-Client-Id: myapp001.ClientId
    • X-Request-ID: a client generated guid to uniquely identify each call
    • X-Client-Certificate: the content of the QWAC pem (for more information read the detailed guidelines on Certificates)

 

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 winbankAccess.monetaryTransactions (access to respective resources)

offline_access (required for refresh tokens)

Sandbox OAuth

Authorization URL

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

Token URL

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

Refresh URL

https://api.rapidlink.piraeusbank.gr/piraeusbank/production/v2.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/v2.1/oauth/oauth2/authorize?response_type=code&client_id=<myapp001.ClientId>&redirect_uri=<myapp001.RedirectUrl>&scope=sandboxapi+offline_access 

Note that the scope offline_access allows for refreshing the token without re-authenticating the PSU.

a) In the login screen, the PSU will enter their credentials. For Sandbox, use one of our test PSU accouns:

Username

Password

UserA

123

UserB

123

UserC

123

b) Upon completion, the browser will be redirected to the RedirectURL 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 in 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 PIS 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>

 

2. Payment Initiation - Authorisation - Execution

For extensive guidelines with detailed examples in section "PIS Examples".