TMS - Polish API (3.0)

Interface specification for services provided by ASPSP based on access to payment accounts. Documentation was created on the basis of the PolishApi specification Version 3.0 from 12 December 2019.

Overview

Glossary of Terms

  • API (Application Programming Interface) - Is a set of commands, functions, and procedures that programmers use when building software for a certain operating system. Through an API, one application can make a request with standardised input towards another application and get the second application to take the input, perform an operation and deliver a standardised output back to the first application

  • AIS (Account Information Service) - as defined in Art. 66 of PSD2.

  • ASPSP (Account Servicing Payment Service Provider - All financial institutions that offer payment accounts (e.g. current accounts, credit cards) with online access (internet banking) are considered ASPSPs.

  • Authentication – a process in result of which the ASPSP verifies the PSU's identity.

  • CAF (Confirmation of the Availability of Funds) - a service defined in Art. 65 of PSD2.

  • Granting Consent – a process in result of which the PSU grants TPP consent to access his/her account held by the ASPSP in order to effect a service, including the AIS, PIS and CAF services.

  • OAuth2 - Is an open authorisation standard. It allows users to share their private resources stored at a given site with another party without a necessity to fathom the complexities of authorisation, usually providing the user name and a token (one-time passwords).

  • PIS (Payment Initiation Services) - as defined in Art. 67 of PSD2.

  • Polish API - It's a Polish standard of Open Banking API which is compatible with PSD2 European Union directive.

  • PSD2 (Payment Services Directive 2) - European Union directive 2015/2366 on payment services in the internal market. It is intended to remove the barriers to entry for companies that want to offer payment services, and obliges banks to provide standardised access to a customer’s bank account information and initiate payments on their request.

  • PSU (Payment Service User) - The end-user of payment services.

  • TPP (Third Party Payment Service Providers) - It's an external company authorized by the service user to make payments, check funds availability and access account information on his behalf.

    TPP may perform the following roles:

    • AISP (Account Information Service Provider) - Provides Account Information Service (AIS) to PSU.
    • PISP (Payment Initiation Service Provider) - Provides Payment Initiation Services (PIS) to PSU.
    • PIISP (Payment Instrument Issuer Service Provider) - Provides Confirmation of the Availability of Funds (CAF) to PSU.
  • TS 119 495 – a technical specification of the standard concerning the qualified certificate profile for the needs of the Payment Services Directive (Electronic Signatures and Infrastructures (ESI); Sector Specific Requirements; Qualified Certificate Profiles and TSP Policy Requirements under the Payment Services Directive 2015/2366/EU), updated as at the date of publication of this standard.

  • XS2A (Access to Account) – access to payment accounts used to perform AIS, PIS, CAF and other services effected as part of the PolishAPI.

API

We have modelled our API structure accoriding to Polish API 3.0.

Out APIs follow PSD2 regulations and in order to use them, you have to be an authorised TPP. You must be registered as either a Payment Initiation Service Provider (PISP), an Account Information Service Provider (AISP) or a Card Based Payment Instrument Issuer (CBPII), authorised by the competent authority in your country.

Request ID

Each request sent by the TPP to the ASPSP -side XS2A interface must contain a unique identifier (a parameter called requestId in the header structure sent within the body of each request as well as in the HTTP header X-REQUEST-ID). The identifier's uniqueness must be ensured for all the requests sent by all the TPPs to the selected ASPSP.

Signing requests

At the message level, in order to ensure the non-repudiation, it is necessary to apply the JSON Web Signature as per the RFC 7515 standard (https://tools.ietf.org/html/rfc7515). The signature should be included in each request in the X-JWS-SIGNATURE header.

TPP Registration

The PolishAPI specification, meeting the requirements of the PSD2 directive, defines a dedicated AS (Authorization Services) service method called /register, which enables automatic registration of TPP client applications that are to gain access to the XS2A interface. The registration of the client application is using the RFC 7591 standard (https://tools.ietf.org/html/rfc7591), extended with additional information. For more details check AS /register method description.

In the PSD2 regulatory scenarios, the required and sufficient condition for registration is the transfer of an eIDAS certificate in accordance with ETSI TS 119 495, indicating the given regulatory authorization (TPP identifier assigned by the regulator, AISP / PISP / ASPSP roles etc.) and cryptographic proof of its ownership (proof of possession of a private key). The method of proving of a possesion a private key seal is that the TPP signs the software_statement token with that key, and the corresponding certificate must be on the jwks list.

Authentication

Diagram of authentication mechanism (Figure 19 from PolishAPI 3.0 specification)

as-diagram

Diagram of session establishment (Figure 23 from Polish API 3.0 specification)

session-establishment

  1. The PSU initiates the use of the selected XS2A interface service at the TPP's application side
  2. The TPP presents a form with data required to identify the ASPSP, call an XS2A interface service and obtain access to that interface
  3. The PSU inserts and confirms the data required in the TPP’s form
  4. The TPP requests authorisation of access to the XS2A interface by calling the following authorization service method: /v3_0.1/auth/v3_0.1/authorize. One of the parameters of this method is an url address (tpp_redirect_url) redirecting to the TPP’s interface after the completion of the procedure of the PSU’s authentication and authorization of the TPP’s access to the PSU’s resources with the ASPSP.
  5. The ASPSP validates the correctness of the authorization request received in terms of various aspects, including the correctness of signature, TPP’s identity, compliance of the consents granted with the TPP’s authorization
  6. The ASPSP, in case of a positive outcome of the authorization request validation, returns a response containing an URL address to its own interface (auth_redirect_url) used for the PSU’s authentication and authorization in the context of the request sent by the TPP
  7. The TPP interprets the response from the ASPSP and returns a response to the PSU's browser in the form of a redirection to the interface of the ASPSP that obtained a response to the authorization request
  8. The PSU's browser automatically redirects to the ASPSP's interface using the auth_redirect_url received
  9. The ASPSP returns to the browser a page containing the PSU’s authentication form
  10. The PSU inserts authentication data to the form and the data, after confirmation by the PSU, are sent to the ASPSP
  11. The ASPSP validates the correctness of the authentication data received as part of the SCA procedure
  12. After the confirmation of the PSU’s identity, the ASPSP returns to the browser a page containing a description of the scope of consents the TPP requested in order to perform the XS2A interface services, together with a form used to confirm the TPP’s request, e.g. it presents a form with a list of PSU’s account to be selected or with data of the transaction initiated.
  13. The PSU accepts the TPP-requested consents by confirming the form presented, which is preceded by a potential selection of a subset of accounts (possible in case of selected XS2A interface services) and by provision of this information to the ASPSP
  14. Having obtained the consent acceptances, the ASPSP generates and retains a one-time authorization code
  15. The ASPSP returns to the browser a response in the form of redirection to the TPP’s interface, i.e. to the url address of return to the TPP received in the authorization request (tpp_redirect_url), and sends the value of the one-time authorization code generated as the parameter of this response
  16. The PSU’s browser automatically redirects to the TPP’s interface by means of the return url address received (tpp_redirect_url), together with the one-time authorization code
  17. On the basis of the request received with the one-time authorization code, the TPP requests the ASPSP to start a session with the XS2A interface in the context of the authorization received from the PSU. To this end, the following authorization service method is called and one of the required elements of this method is a one-time authorization code (authorization_code): /v3_0.1/auth/v3_0.1/token
  18. The ASPSP validates the XS2A session establishment request received by verification of the authorization code received (authorization_code) and the data concerning the PSU’s consents granted. After a positive verification, the ASPSP establishes a new session of the XS2A interface in result of which a unique access token (access_token) is generated.
  19. The ASPSP returns a response to the session establishment request to the TPP, which contains, without limitation, the value of the access token generated, confirming thus the establishment of a session with the XS2A interface.

Authorization

xs2a_auth_aspsp

Security Scheme Type OAuth2
authorizationCode OAuth Flow
Authorization URL: https://apiHost/v3_0.1/auth/v3_0.1/authorize
Token URL: https://apiHost/v3_0.1/auth/v3_0.1/token
Scopes:
  • ais-accounts -

    Permission to retrieve the list of accounts through Account Information Service

  • ais -

    Permission to execute methods of Account Information Service in context of particular account

  • pis -

    Permission to initiate payments and check their statuses through Payment Initiation Service

AS - Authorization Service

The aim of the AS is to authorize TPP and Payment Service User.

/register - Client application registration request

Client application registration request

header Parameters
Accept-Encoding
required
string
Enum: "gzip" "deflate"

Gzip, deflate

Accept-Language
required
string

Prefered language of response

Accept-Charset
required
string
Value: "utf-8"

UTF-8

X-REQUEST-ID
required
string

Request identifier using UUID format (Variant 1, Version 1), described in RFC 4122 standard, set by TPP. Value of this header must be the same as for the requestId param passed inside request payload.

Request Body schema: application/json

Client application registration request data

software_statement
required
string

software_statement (see RFC 7591) is a SignedJWT in a format of:

Base64(JwtHeader).Base64(JwtClaims).Base64(JwtSignature)

JwtHeader

{
  "alg": "HS256",
  "typ": "JWT"
}

JwtClaims

Fact Id Description Required Comment
iat software_statement creation time No Epoch seconds
iss software_statement issuer id Yes It is a TPP identifier issued by the regulator and coded in accordance with the requirements of ETSI TS 119 495
iss_name software_statement issuer name No
sub Organization id No Not supported
sub_name Organization name No Not supported
sub_descr Orgaznization description No
sub_logo Organization logo URL No Max size 1MB, max width 200px max height 200px
Sub_contact_name name and surname of the contact person No
Sub_contact_email email of the contact person No
Sub_org_number Organization European NIP No
Sub_country Organization registration country No
client_name Client application name
redirect_uris URLs used to redirect PSU after authorization Yes Array of URLs
jwks A collection of keys (certificates - for asymmetric cryptography) that can be used by the TPP to sign requests Yes if jwks_uri not defined must contain only one certificate of the seal in accordance with ETSI TS 119 495, which can be used to sign the requests sent to the XS2A interface. See RFC 7591 and RFC 7517.
jwks_uri URL to JSON object with keys array (certificates - for asymmetric cryptography) that can be used by the TPP to sign requests Yes if jwks not defined It must contain only one certificate of the seal in accordance with ETSI TS 119 495, which can be used to sign the requests sent to the XS2A interface. See RFC 7591 and RFC 7517.
scope Requested application scopes separated by space No Available scopes: ais, ais-accounts, pis
JWKS key field
Field Id Description Required Comment
kty Key type (cryptographic algorithm family) Yes must be: RSA
alg Algorithm Yes must be: RS256
kid Key ID Yes
x5u X.509 URL Yes URL to X.509 public key certificate compliant with ETSI TS 119 495
x5t#256 X.509 certificate SHA-256 thumbprint Yes base64url-encoded SHA-256 thumbprint of the DER encoding of the X.509 certificate
Example
{
  "iat": 1614556800,
  "iss": "SoftwareStatement Issuer ID",
  "iss_name": "SoftwareStatement Issuer Name",
  "sub": "Organization ID"
  "sub_name": "Organization Name"
  "sub_descr": "Organization Description"
  "sub_logo": "https://domain.com/logo.png"
  "Sub_contact_name": "FirstName LastName"
  "Sub_contact_email": "email@domain.com"
  "Sub_org_number": "PL0000000000"
  "Sub_country": "PL"
  "client_name": "Application name"
  "redirect_uris": [
    "https://domain1.com",
    "https://domain2.com"
  ],
  "jwks": {
    "keys": [
      {
        "kty": "RSA",
        "alg": "RS256",
        "kid": "key-id",
        "x5u": "https://domain.com/cert.pem",
        "x5t#S256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
      }
    ]
  },
  "scope": "ais ais-accounts pis"
}

JwtSignature

To create the signature part you have to take the encoded header, the encoded claims, a secret, the algorithm specified in the header, and sign that.

Responses

Response Headers
Content-Encoding
string

Gzip, deflate

Response Schema: application/json
required
object (ResponseHeader)

Metadata Class

client_id
string

The unique identifier of the TTP application

client_secret
string

A secret value used to authenticate the client application to the authorization server

api_key
string

A secret value to identify the client application relative to the API

object (RegisterJWKS)

A collection of keys (certificates - for asymmetric cryptography) that can be used by ASPSP for API response signature. RFC 7591 and RFC 7517 compliant. Required conditionally unless jwks_uri is specified.

jwks_uri
string

A collection of keys contained in the URI (certificates - for asymmetric cryptography) that can be used by ASPSP for the signature of the API response. According to RFC 7591 and RFC 7517. Condition required unless jwks are given.

Request samples

Content type
application/json
{
  • "software_statement": "string"
}

Response samples

Content type
application/json
{
  • "responseHeader": {
    },
  • "client_id": "string",
  • "client_secret": "string",
  • "api_key": "string",
  • "jwks": {
    },
  • "jwks_uri": "string"
}

/authorize - Requests OAuth2 authorization code

Requests OAuth2 authorization code

header Parameters
Accept-Encoding
required
string
Enum: "gzip" "deflate"

Gzip, deflate

Accept-Language
required
string

Prefered language of response

Accept-Charset
required
string
Value: "utf-8"

UTF-8

X-JWS-SIGNATURE
required
string

Detached JWS signature of the body of the payload

X-REQUEST-ID
required
string

Request identifier using UUID format (Variant 1, Version 1), described in RFC 4122 standard, set by TPP. Value of this header must be the same as for the requestId param passed inside request payload.

Request Body schema: application/json

Data for OAuth2 Authorization Code Request

required
object (RequestHeaderWithoutTokenAS)

PSU Information Class dedicated for authorization services

response_type
required
string

Type of response. Fixed value: code

client_id
required
string

TPP ID

redirect_uri
required
string

The Address of the TPP service to which the redirection will be performed after ASPSP client authentication

scope
required
string
Enum: "ais" "ais-accounts" "pis"

Type of consent requested by the TPP.