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 manual process performed through the Developer Portal. There is also an automatic enrollment process for PSD2 APIs, explained in a separate section.

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/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)

 

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 Please 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. Initiate a Payment

Payments are initiated by a POST to “/v1/{payment-service}/{payment-product}”.

Please note:

The supported values at the time of this writing are:

  • payment-service: payments
  • payment-product: sepa-credit-transfers

Thus, your Url will be “/v1/payments/sepa-credit-transfers

Here is a sample, for credit transfer to another bank, same country.

Request:

  • POST https://api.rapidlink.piraeusbank.gr/piraeusbank/production/psd2/pis/v1/payments/sepa-credit-transfers
  • X-Request-ID: e89a9c5e-6b26-4597-b829-816c34952f4c
  • PSU-IP-Address: 127.0.0.1
  • Authorization: Bearer ABjNS00YTQ4LWEjBl7uKgGRqn0fBJFrsz
  • Accept: application/json
  • x-ibm-client-id: <myapp001.clientid>
  • Content-Type: application/json
  • BODY:

{
   "endToEndIdentification": "TEST001",
   "debtorAccount": {
          "iban": "GR2801718220007022123123123",
          "currency": "EUR"
   },
   "instructedAmount": {
          "currency": "EUR",
          "amount": "0.5"
   },
   "creditorAccount": {
          "iban": "GR9202600260000000000299650"
   },
   "creditorName": "George Papadopoulos",
   "remittanceInformationUnstructured": "{\r\n  \"comments\": \"invoice 12345\"\r\n}"
}

 

Response:

  • 201 (Created) with body:

{
   "transactionStatus": "RCVD",
   "paymentId": "3E48BADD-6945-49C9-A9F4-8B374A7F1655",
   "_links": {
          "startAuthorisation": {
                 "href": "https://api.rapidlink.piraeusbank.gr/piraeusbank/production/psd2/pis/v1/payments/sepa-credit-transfers/3E48BADD-6945-49C9-A9F4-8B374A7F1655/authorisations"
          }
   },
   "tppMessages": [{
         "category": "ERROR",
         "code": "PSU_CREDENTIALS_INVALID",
         "text": "Second factor authentication needed.  Please call POST /authorisations first."
   }]
}

 

3. Authorize the Payment (If Required)

The Payment initiation response will guide you on whether Authorization is required or not.

If the Links.execute has a value then you can go on and call this link executing the Payment without authorization. That would be the scenario when you make a credit transfer between accounts of the current PSU.

 If the Links.execute is empty, the Links.startAuthorisation will have a value. Please use this link to start the Authorization.

This is the POST to “/v1/{payment-service}/{payment-product}/{paymentId}/authorisations” that is documented in the PIS Service as “startPaymentAuthorisation”.

 

Start Authorization

Start Authorization using the “Links.startAuthorisation” link provided when Links.execute. This is the POST to “/v1/{payment-service}/{payment-product}/{paymentId}/authorisations” that is documented in the PIS Service as “startPaymentAuthorisation”.

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

Request:

  • POST https://api.rapidlink.piraeusbank.gr/piraeusbank/production/psd2/pis/v1/payments/sepa-credit-transfers/3E48BADD-6945-49C9-A9F4-8B374A7F1655/authorisations
  • X-Request-ID: cd427ada-042d-4e2b-ace0-98990fd37a48
  • PSU-IP-Address: 127.0.0.1
  • Authorization: Bearer ABjNS00YTQ4LWEjBl7uKgGRqn0fBJFrsz
  • Accept: application/json
  • x-ibm-client-id: <myapp001.clientid>
  • Content-Type: application/json
  • BODY: empty

 

Response:

  • 201 (Created) with body:

{
       "scaStatus": "started",
       "authorisationId": "7E7E1108-F2DE-47DA-9EA1-29204BCF65B8",
       "_links": {
              "authoriseTransaction": {
                     "href": "https://api.rapidlink.piraeusbank.gr/piraeusbank/production/psd2/pis/v1/payments/sepa-credit-transfers/3E48BADD-6945-49C9-A9F4-B374A7F1655/authorisations/7E7E1108-F2DE-47DA-9EA1-29204BCF65B8"
              },
              "execute": {
                     "href": "https://api.rapidlink.piraeusbank.gr/piraeusbank/production/psd2/pis/v1/payments/sepa-credit-transfers?paymentId=3E48BADD-6945-49C9-A9F4-8B374A7F1655&executionKey=zZoEaN0oVptKjvUypxeElDO66KTHjGz7h&scaAuthenticationData=REPLACE_WITH_PSU_SCA"
              }
                     },
       "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"
       }
}

 

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.

Request:

  • PUT https://api.rapidlink.piraeusbank.gr/piraeusbank/production/psd2/pis/v1/payments/sepa-credit-transfers/3E48BADD-6945-49C9-A9F4-8B374A7F1655/authorisations/7E7E1108-F2DE-47DA-9EA1-29204BCF65B8
  • X-Request-ID: baf8cbc3-2899-4b16-9d33-06b5306d7892
  • Authorization: Bearer ABjNS00YTQ4LWEjBl7uKgGRqn0fBJFrsz
  • Payment-ID (on URL): 3E48BADD-6945-49C9-A9F4-8B374A7F1655
  • AuthorisationID (on URL): 7E7E1108-F2DE-47DA-9EA1-29204BCF65B8
  • Accept: application/json
  • x-ibm-client-id: <myapp001.clientid>
  • Content-Type: application/json
  • BODY:

{
       authenticationMethodId":"2"
}

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/pis/v1/payments/sepa-credit-transfers/3E48BADD-6945-49C9-A9F4-8B374A7F1655/authorisations/7E7E1108-F2DE-47DA-9EA1-29204BCF65B8"
          }
   }
}

 

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 methods 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/pis/v1/payments/sepa-credit-transfers/3E48BADD-6945-49C9-A9F4-8B374A7F1655/authorisations/7E7E1108-F2DE-47DA-9EA1-29204BCF65B8
  • PSU-IP-Address: 127.0.0.1
  • Authorization: Bearer ABjNS00YTQ4LWEjBl7uKgGRqn0fBJFrsz
  • Payment-ID (on URL): 3E48BADD-6945-49C9-A9F4-8B374A7F1655
  • AuthorisationID (on URL): 7E7E1108-F2DE-47DA-9EA1-29204BCF65B8
  • Accept: application/json
  • x-ibm-client-id: <myapp001.clientid>
  • Content-Type: application/json
  • BODY:

{
      "scaAuthenticationData": "3288000"
}

 

Sample Response

200 (ok) with body:

{
       "scaStatus": "received",
}

 

Inform the PSU to do the SCA using the Bank’s Mobile App (applicable 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.

 

4. Execute the Payment

You may Execute the Payment using the Execute link.

The Execute link should be retrieved, from one of the following responses, in the order outlined:

  • From the Response of Initiate Payment, if the payment didn’t need to be authorized or
  • From the Response of Start Authorization, if the payment did request an authorization

If an Authorization was requested, and a SCA OTP had to be enter to the API the Execute method will also require the “same” SCA OTP. The Execute method URL will contain the placeholder “REPLACE_WITH_PSU_SCA” that you should replace with the PSU SCA OTP.

 

Sample Request:

  • POST https://dev.api.piraeusbank.gr/innovationcenter/development/psd2/pis/v1/payments/sepa-credit-transfers?paymentId=3E48BADD-6945-49C9-A9F4-8B374A7F1655&executionKey=zZoEaN0oVptKjvUypxeElDO66KTHjGz7h&scaAuthenticationData=3288000
  • Authorization: Bearer ABjNS00YTQ4LWEjBl7uKgGRqn0fBJFrsz
  • Accept: application/json
  • x-ibm-client-id: <myapp001.clientid>
  • Content-Type: application/json
  • BODY:

{
        "scaAuthenticationData": "3288000"
}

 

Sample Response

200 (ok) with body:

{
       "transactionStatus": "ACSP",
       "paymentId": "3E48BADD-6945-49C9-A9F4-8B374A7F1655",
       "_links": {},
       "transactionFeeIndicator": true,
       "psuMessage": "",
       "transactionFees": {
              "currency": "EUR",
              "amount": "0.30"
       }
}