API Docs

PSD2 Open API

You can download API Definition here

You can download API Specification here

Introduction

The revised Payment Services Directive (PSD2) is a data and technology-driven directive which aims to drive increased competition, innovation and transparency across the European payments market, while enhancing the security of Internet payments and account access.

Among others [PSD2] contains regulations on new services to be operated by so called Third Party Payment Service Providers (TPP) on behalf of a Payment Service  User (PSU). These new services are

  • Payment  Initiation  Service  (PIS)  to  be  operated  by  a  Payment  Initiation  Service Provider (PISP) TPP as defined by article 66 of [PSD2],

  • Account Information Service (AIS) to be operated by an Account Information Service Provider (AISP) TPP as defined by article 67 of [PSD2], and

  • Confirmation  on  the  Availability  of  Funds  Service  (FCS)  to  be  used  by  a  Payment Instrument Issuing Service Provider (PIISP) TPP as defined by article 65 of [PSD2].

To  implement  these  new  services  (subject  to  PSU  consent)  a  TPP  needs  to  access  the  account of the PSU. The account is usually managed by another PSP called the Account Servicing Payment Service Provider (ASPSP). To support the TPP in accessing the accounts managed by an ASPSP, each ASPSP has to provide an "access to account interface" (XS2A interface).

Responsibilities  and  rights  of  TPP  and  ASPSP  concerning  the  interaction  at  the  XS2A interface are defined and regulated by [PSD2]. In addition, more detailed requirements for the implementation and operation of the XS2A interface are defined by [EBA-RTS]. 

Key objectives:

  • Contribute to a more integrated and efficient European payments market

  • Improve the level playing field for payment service providers (including new entrants)

  • Make payments safer and more secure

  • Protect consumers

  • Encourage lower prices for payments

Basis of the regulatory requirements are the following documents:

  • Payment services (PSD2) - Directive (EU) 2015/2366

  • Regulatory Technical Standards (RTS) on strong customer authentication (SCA) and secure open standards of communication (CSC)

  • Local transposition law: “Zakon o platnom prometu” (ZPP), published in the official gazette 66/2018 on the 20th of July 2018.

 

Berlin Group NextGenPSD2

The NextGenPSD2 Initiative is a dedicated Task Force of the Berlin Group with the goal to create an open, common and harmonised European API (Application Programming Interface) standard to enable Third Party Providers (TPPs) to access banks accounts under the revised Payment Services Directive (PSD2). In a unique partnership, participants in NextGenPSD2 are working together with the common vision that open and harmonised PSD2 XS2A interface standards for processes, data and infrastructures are the necessary building blocks of an open, interoperable market. True interoperability is an essential component of competitive pan-European PSD2 XS2A services and will contribute to further progress towards the European Single Market and benefit the payments industry in general and European consumers and businesses in particular.

While  a  harmonised  XS2A  interface  is  essential  to  enable  XS2A  services  to  mature  at scale  and  at  relatively  low  cost,  the  full  PSD2  XS2A  ecosystem  covers  other  technical, functional, operational and governance domains with (sometimes optional) complementary services as well, as displayed in the following picture:

Key characteristics of the NextGenPSD2 Framework:

  • Modern  “RESTful”  API  set  using  HTTP/1.1  with  TLS  1.2  (or  higher)  as  transport protocol

  • Integrating public market consultation feedback on a first draft version

  • TPP identification by ETSI viii -defined eIDAS certificates: QWACS mandated (easy measure to protect e.g. against DDOS attacks), QSEALS optional for banks (TPP follows instruction by bank)

  • Supporting  all  PSD2  required  payment  initiation,  account  information  and confirmation  of  funds  use  cases,  with  future-dated,  multiple/bulk,  and  recurring payments  optional  (depending  on  support  in  online  banking  or  in  national legislation)

  • Full multicurrency support of accounts

  • Four  architecture  models  for  Strong  Customer  Authentication  (SCA):  redirect, OAuth2, decoupled  and  embedded,  with  influence  of  the  TPP  on  redirect preference

  • Multilevel SCA approach for corporates, e.g. to support a 4-eyes principle

  • Support of card transactions reconciliation accounts

  • Signing  baskets  as  signing  vehicles  for grouped  transactions  (instead  of  multiple payments functions)

  • Transparent  resource  structures  (allowing  TPPs  to  keep  an  overview  also  in complex business processes)

  • Dedicated consent API separating consent handling from account access, obeying both PSD2 and GDPR requirements

  • Optional  session  support  (set  of  consecutively  executed  transactions),  subject  to appropriate customer consent

  • Data structures either as (dependent on retail vs. corporate requirements)

    • JSON with data model based on ISO 20022, or

    • XML with pain.001 for PISPs and camt.05x for AISPs

  • Integrated formal and transparent change management process and versioning

  • Extensible with additional extensions that allow to build (non-core PSD2) value add services

For further details see NextGenPSD2 overview here.

Croatian Banking Association joined Berlin Group in September 2017. Even thou at that time in early stages, NextGenPSD2 has been seen as an initiative that could bring missing common API standard among credit institutions. Today, Berlin Group API standard is seen as dominant PSD2 API standard initiative backed by credit institutions throughout entire EU.

API Documentation

As a member of Berlin Group, fundamental documentation related to PSD2 API in Croatian is NextGenPSD2 documentation. CBA PSD2 documentation arises from NextGenPSD2 API documentation.

Structure

PSD2 API documentation for Croatian market can be divided into three hierarchical sections:

  1. NextGenPSD2 API documentation

  2. CBA PSD2 API documentation

  3. ASPSP’s documentation

Dependencies between each documentation group are described on following graphic:

 

NextGenPSD2 API Documentation

The NextGenPSD2 Framework itself is built of 4 artefacts, which are all published for free under Creative Commons (CC-BY-ND):

  1. An Introductions Paper

  2. An Operational Rules document that covers the service description, abstract (logical) data model and detailed process flow descriptions in a B2B interface

  3. Implementation Guidelines that specify the XS2A interface in technical detail, including XML/JSON schemas

  4. An OpenAPI file that helps implementers during development

The documents are used by banks and TPPs for implementing PSD2-required bank account access.

The most recent release of the NextGenPSD2 Framework can be downloaded here.

 

Documentation Lifecycle

According to RTS:

“…account  servicing  payment  service  providers  shall  ensure  that,  except  for emergency situations,  any change to the  technical  specification  of  their  interface  is  made available  to authorised  payment  initiation service  providers,  account  information  service providers  and  payment  service  providers  issuing  card-based  payment instruments, or payment service providers that have applied to their competent authorities for the relevant authorisation, in advance as soon as possible and not less than 3 months before the change is implemented.”

Linked Documents and References

 

[X2A-ImplG] NextGenPSD2 XS2A Framework, Implementation Guidelines, The Berlin Group Joint Initiative on a PSD2 Compliant XS2A Interface, version 0.99, published 02 October 2017.
[eIDAS] EU Regulation No 910/2014 of the European Parliament and of the Council of 23 July 2014 on electronic identification and trust services for electronic transactions in the internal market and repealing Directive 1999/93/EC
[PSD2] Directive (EU) 2015/2366 of the European Parliament and of the Council on payment services in the internal market, published 25.11.2015
Open API https://www.openapis.org/
EBA RTS Opinion of the European Banking Authority on the implementation of the RTS on SCA and CSC from 13 June 2018
EBA Guidelines Guidelines on the conditions to be met to benefit from an exemption from contingency measures under Article 33(6) of Regulation (EU) 2018/389 (RTS on SCA & CSC)
EBA eIDAS Opinion on the use of eIDAS certificates under the RTS on SCA and CSC

Abbreviations

Abbreviation Description
AIS Account Information Service according to article 4 (16) of [PSD2] and as regulated by article 67 of [PSD2].
AISP Account Information Service Provider offering an AIS to its customer. See article 4 (19) of [PSD2].
API Application Programming Interface.
ASPSP Account Servicing Payment Service Provider providing and maintain a payment account for a payer. See article 4 (17) of [PSD2].
CBA Croatian Banking Association
EBA European Banking Authority
eIDAS Electronic Identification, Authentication and Trust Services
IAM Global architectural component that Manage the Identity & Access
OAuth2 This protocol, which allows third-party applications to grant limited access to an HTTP service.
PIISP Payment Instrument Issuer Service Provider according to article 4 (14) and 45) of [PSD2]. A PIISP can use the service "Confirmation on the availability of funds" as regulated by article 65 of [PSD2].
PIS Payment Initiation Service according to article 4 (15) of [PSD2] and as regulated by article 66 of [PSD2].
PISP Payment Service Provider offering a PIS to its customer. See article 4 (18) of [PSD2].
PSP Payment Service Provider according to article 4 (11) of [PSD2].
PSU Payment Service User according to article 4 (10) of [PSD2].
RTS EBA Regulatory Technical Standards on strong customer authentication and common and secure communication.
SCA Strong Customer Authentication – authentication procedure based on two factors compliant with the requirements of [PSD2] and [EBA-RTS].
SCT SEPA Credit Transfer.
SDD SEPA Direct Debit.
TPP Third Party Provider – generic term for AISP/PIISP/PISP.
X2A Access to Account interface – interface provided by an ASPSP to TPP for accessing accounts. (= API / interface)