TMS
API docs by Redocly

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) - an online service to provide consolidated information on one or more payment accounts held by a PSU with either another payment service provider or with more than one payment service provider,

  • ASPSP (Account Servicing Payment Service Provider - a payment service provider providing and maintaining a payment account for a payer, Authentication – a process in result of which an ASPSP verifies a PSU's identity,

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

  • CAF (Confirmation of the Availability of Funds) - an online service to confirm whether an amount necessary for the execution of a card-based payment transaction is available on the payment account of the payer, as described in art. 65 of PSD2,

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

  • OAuth2 - is the industry-standard protocol for authorization, 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) - a service to initiate a payment order at the request of a PSU with respect to a payment account held at another payment service provider,

  • Polish API - Polish standard of open banking API which is in compliance with PSD2,

  • PSD2 (Payment Services Directive 2) - Directive (EU) 2015/2366 of the European Parliament and of the Council of 25 November 2015 on payment services in the internal market, amending Directives 2002/65/EC, 2009/110/EC and 2013/36/EU and Regulation (EU) No 1093/2010, and repealing Directive 2007/64/EC (Text with EEA relevance),

  • PSU (Payment Service User) - a natural or legal person making use of a payment service in the capacity of payer, payee, or both,

  • TPP (Third Party Payment Service Providers) - an external company authorized by a PSU to make payments, check funds availability or access account information on his/her 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 PSD2,

  • 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 according to Polish API 3.0.

Our APIs are based on PSD2 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 a competent authority or a payment service provider that have applied to your competent authorities for the relevant authorisation (according to art. 30 sec 3 of PSD2).

Request ID

Each request sent by a TPP to an 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 defines a dedicated AS (Authorization Services) method called “/register”, which enables automatic registration of a TPP’s client applications that are intended to gain access to the XS2A interface. The registration of a client application is using the RFC 7591 standard (https://tools.ietf.org/html/rfc7591), extended with additional information. For more details, please check AS /register method description.

According to PSD2, the required and sufficient condition for registration is the transfer of an eIDAS certificate in accordance with TS 119 495, indicating the given regulatory authorization (TPP’s authorisation number, the role of the payment service provider etc.) and cryptographic proof of its ownership (proof of possession of a private key). The method of proving possession of 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
Flow type: authorizationCode
Authorization URL: https://komfort.tmskantor.pl/api/polish/v3_0.1/auth/v3_0.1/authorize
Token URL: https://komfort.tmskantor.pl/api/polish/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": "RS256",
  "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.

required
object (ScopeDetailsInput)

Scope, limits, parameters and expiration time of consents requested by TPP

state
required
string

Random, unique value within TPP - protection against Cross-Site Request Forgery attack

Responses

Response Headers
Content-Encoding
string

Gzip, deflate

X-JWS-SIGNATURE
string

Detached JWS signature of the body of the response

Response Schema: application/json
required
object (ResponseHeader)

Metadata Class

aspspRedirectUri
required
string

The address on the ASPSP side to which the TPP should redirect the PSU browser in order to authenticate PSU

Request samples

Content type
application/json
{
  • "requestHeader": {
    },
  • "response_type": "string",
  • "client_id": "string",
  • "redirect_uri": "string",
  • "scope": "ais",
  • "scope_details": {
    },
  • "state": "string"
}

Response samples

Content type
application/json
{
  • "responseHeader": {
    },
  • "aspspRedirectUri": "string"
}

/token - Requests OAuth2 access token value

Requests OAuth2 access token value

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 Access Token Request

object (RequestHeaderToken)

PSU Information Class dedicated for an access token

grant_type
required
string

Type of authorization used. One of the following values: authorization_code, refresh_token, exchange_token (extension of OAuth2 standard)

Code
string

An authorization code obtained when requesting the /authorize OAuth2 service. Required for grant_type=authorization_code.

redirect_uri
string

The address of the TPP service to which the redirection will be performed after the ASPSP generates the access token. Required for grant_type=authorization_code.

client_id
string

TPP ID. Required for grant_type=authorization_code.

refresh_token
string

Value of the token used to obtain a new access token for the same scope of consents (scope, scope_details) - in case the original token expires or for a narrower scope of consents. Required for grant_type=refresh_token.

exchange_token
string

Value of the token, which is used to obtain a new access token for a different scope of consents (scope, scope_details). The value of this parameter should be the access token of a valid communication session with the XS2A interface. Required for grant_type=exchange_token.

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

Type of consent requested by the TPP.

object (ScopeDetailsInput)

Scope, limits, parameters and expiration time of consents requested by TPP

is_user_session
boolean

Defines whether the session is related to the PSU interaction - true/false values. Extension of the OAuth2 standard.

user_ip
string

User's browser IP (information for fraud detection). Extension of the OAuth2 standard. Required for is_user_session = true.

user_agent
string

Information about the version of the user's browser (information for fraud detection). Extension of the OAuth2 standard. Required for is_user_session = true.

Responses

Response Headers
Content-Encoding
string

Gzip, deflate

X-JWS-SIGNATURE
string

Detached JWS signature of the body of the response

Response Schema: application/json
required
object (ResponseHeader)

Metadata Class

access_token
required
string

Value of the generated access token

token_type
required
string

Access token type. Allowed value is Bearer.

expires_in
required
string

The validity period of an access token, after which it will be invalidated. Value expressed in seconds, calculated from the moment of generating the response.

refresh_token
string

Value of the generated token used to obtain a new access token without the need for re-authorisation

scope
string

The types of consents that the TPP has obtained. List of identifiers compatible with the specification of the Polish API standard.

required
object (ScopeDetailsOutput)

Scope, limits, parameters and expiration time of consents that are confimed by ASPSP

Request samples

Content type
application/json
{
  • "requestHeader": {
    },
  • "grant_type": "string",
  • "Code": "string",
  • "redirect_uri": "string",
  • "client_id": "string",
  • "refresh_token": "string",
  • "exchange_token": "string",
  • "scope": "ais",
  • "scope_details": {
    },
  • "is_user_session": true,
  • "user_ip": "string",
  • "user_agent": "string"
}

Response samples

Content type
application/json
{
  • "responseHeader": {
    },
  • "access_token": "string",
  • "token_type": "string",
  • "expires_in": "string",
  • "refresh_token": "string",
  • "scope": "string",
  • "scope_details": {
    }
}

AIS - Account Information Service

The aim of the AIS is to give customers relevant and up-to-date information about TMS payment accounts including the balances and the transactions of those accounts.

Diagram of Activity of the AIS Service (Figure 21 from PolishAPI 3.0 specification)

ais-diagram

Diagram of Activity of the AIS Service (Figure 21 from PolishAPI 3.0 specification)

ais-diagram

/deleteConsent - Removes consent

Removes consent

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 delete Consent Request

required
object (RequestHeaderWithoutToken)

PSU Information Class

consentId
required
string

Consent ID

Responses

Request samples

Content type
application/json
{
  • "requestHeader": {
    },
  • "consentId": "string"
}

Response samples

Content type
application/json
{
  • "responseHeader": {
    },
  • "code": "string",
  • "message": "string"
}

/getAccounts - Get information about all user's payment account

User identification based on access token

Authorizations:
xs2a_auth_aspsp
header Parameters
Authorization
required
string

The value of the Authorization header should consist of 'type' + 'credentials', where for the approach using the 'type' token should be 'Bearer'.

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 Accounts Request

required
object (RequestHeaderAISCallback)

PSU and callback URL Information Class

typeOfPsuRelation
string
Enum: "Owner" "Borrower" "Guarantor" "ProxyOwner" "Beneficiary" "Trustee"

Used for filtering the results - type of relation between PSU and an Account

pageId
string

Used for paging the results. Identifier of the page to be returned in the response.

perPage
integer <int32> >= 1

Page size (paging info)

Responses

Response Headers
Content-Encoding
string

Gzip, deflate

X-JWS-SIGNATURE
string

Detached JWS signature of the body of the response

Response Schema: application/json
required
object (ResponseHeader)

Metadata Class

Array of objects (AccountBaseInfo)
object (PageInfo)

Paging Information Class

Request samples

Content type
application/json
{
  • "requestHeader": {
    },
  • "typeOfPsuRelation": "Owner",
  • "pageId": "string",
  • "perPage": 1
}

Response samples

Content type
application/json
{
  • "responseHeader": {
    },
  • "accounts": [
    ],
  • "pageInfo": {
    }
}

/getAccount - Get detailed information about user payment account

User identification based on access token

Authorizations:
xs2a_auth_aspsp
header Parameters
Authorization
required
string

The value of the Authorization header should consist of 'type' + 'credentials', where for the approach using the 'type' token should be 'Bearer'.

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 Account Request

required
object (RequestHeaderAIS)

PSU Information Class

accountNumber
required
string

Account number

Responses

Response Headers
Content-Encoding
string

Gzip, deflate

X-JWS-SIGNATURE
string

Detached JWS signature of the body of the response

Response Schema: application/json
required
object (ResponseHeader)

Metadata Class

object (AccountInfo)

Account Information Class

Request samples

Content type
application/json
{
  • "requestHeader": {
    },
  • "accountNumber": "string"
}

Response samples

Content type
application/json
{
  • "responseHeader": {
    },
  • "account": {
    }
}

/getTransactionsDone - Get list of user done transactions

Authorizations:
xs2a_auth_aspsp
header Parameters
Authorization
required
string

The value of the Authorization header should consist of 'type' + 'credentials', where for the approach using the 'type' token should be 'Bearer'.

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 Transactions Done Request

required
object (RequestHeaderAISCallback)

PSU and callback URL Information Class

accountNumber
required
string

Account number

itemIdFrom
string <= 128 characters

Filter element - id of transaction or hold to start from

transactionDateFrom
string <date> <= 10 characters

Filter element

transactionDateTo
string <date> <= 10 characters

Filter element

bookingDateFrom
string <date> <= 10 characters

Filter element. Ignored during list of holds retrieval.

bookingDateTo
string <date> <= 10 characters

Filter element. Ignored during list of holds retrieval.

minAmount
string^(0|([1-9][0-9]{0,}))\.\d{2}$

Filter element

maxAmount
string^(0|([1-9][0-9]{0,}))\.\d{2}$

Filter element

pageId
string

Used for paging the results. Identifier of the page to be returned in the response.

perPage
integer <int32> >= 1

Page size (paging info)

type
string
Enum: "CREDIT" "DEBIT"

Filter element

Responses

Response Headers
Content-Encoding
string

Gzip, deflate

X-JWS-SIGNATURE
string

Detached JWS signature of the body of the response

Response Schema: application/json
required
object (ResponseHeader)

Metadata Class

Array of objects (TransactionInfo)
object (PageInfo)

Paging Information Class

Request samples

Content type
application/json
{
  • "requestHeader": {
    },
  • "accountNumber": "string",
  • "itemIdFrom": "string",
  • "transactionDateFrom": "2019-08-24",
  • "transactionDateTo": "2019-08-24",
  • "bookingDateFrom": "2019-08-24",
  • "bookingDateTo": "2019-08-24",
  • "minAmount": "string",
  • "maxAmount": "string",
  • "pageId": "string",
  • "perPage": 1,
  • "type": "CREDIT"
}

Response samples

Content type
application/json
{
  • "responseHeader": {
    },
  • "transactions": [
    ],
  • "pageInfo": {
    }
}

/getTransactionsPending - Get list of user's pending transactions

Authorizations:
xs2a_auth_aspsp
header Parameters
Authorization
required
string

The value of the Authorization header should consist of 'type' + 'credentials', where for the approach using the 'type' token should be 'Bearer'.

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 Transactions Pending Request

required
object (RequestHeaderAISCallback)

PSU and callback URL Information Class

accountNumber
required
string

Account number

itemIdFrom
string <= 128 characters

Filter element - id of transaction or hold to start from

transactionDateFrom
string <date> <= 10 characters

Filter element

transactionDateTo
string <date> <= 10 characters

Filter element

bookingDateFrom
string <date> <= 10 characters

Filter element. Ignored during list of holds retrieval.

bookingDateTo
string <date> <= 10 characters

Filter element. Ignored during list of holds retrieval.

minAmount
string^(0|([1-9][0-9]{0,}))\.\d{2}$

Filter element

maxAmount
string^(0|([1-9][0-9]{0,}))\.\d{2}$

Filter element

pageId
string

Used for paging the results. Identifier of the page to be returned in the response.

perPage
integer <int32> >= 1

Page size (paging info)

type
string
Enum: "CREDIT" "DEBIT"

Filter element

Responses

Response Headers
Content-Encoding
string

Gzip, deflate

X-JWS-SIGNATURE
string

Detached JWS signature of the body of the response

Response Schema: application/json
required
object (ResponseHeader)

Metadata Class

Array of objects (TransactionPendingInfo)
object (PageInfo)

Paging Information Class

Request samples

Content type
application/json
{
  • "requestHeader": {
    },
  • "accountNumber": "string",
  • "itemIdFrom": "string",
  • "transactionDateFrom": "2019-08-24",
  • "transactionDateTo": "2019-08-24",
  • "bookingDateFrom": "2019-08-24",
  • "bookingDateTo": "2019-08-24",
  • "minAmount": "string",
  • "maxAmount": "string",
  • "pageId": "string",
  • "perPage": 1,
  • "type": "CREDIT"
}

Response samples

Content type
application/json
{
  • "responseHeader": {
    },
  • "transactions": [
    ],
  • "pageInfo": {
    }
}

/getTransactionsRejected - Get list of user's rejected transactions

Authorizations:
xs2a_auth_aspsp
header Parameters
Authorization
required
string

The value of the Authorization header should consist of 'type' + 'credentials', where for the approach using the 'type' token should be 'Bearer'.

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 Transactions Rejected Request

required
object (RequestHeaderAISCallback)

PSU and callback URL Information Class

accountNumber
required
string

Account number

itemIdFrom
string <= 128 characters

Filter element - id of transaction or hold to start from

transactionDateFrom
string <date> <= 10 characters

Filter element

transactionDateTo
string <date> <= 10 characters

Filter element

bookingDateFrom
string <date> <= 10 characters

Filter element. Ignored during list of holds retrieval.

bookingDateTo
string <date> <= 10 characters

Filter element. Ignored during list of holds retrieval.

minAmount
string^(0|([1-9][0-9]{0,}))\.\d{2}$

Filter element

maxAmount
string^(0|([1-9][0-9]{0,}))\.\d{2}$

Filter element

pageId
string

Used for paging the results. Identifier of the page to be returned in the response.

perPage
integer <int32> >= 1

Page size (paging info)

type
string
Enum: "CREDIT" "DEBIT"

Filter element

Responses

Response Headers
Content-Encoding
string

Gzip, deflate

X-JWS-SIGNATURE
string

Detached JWS signature of the body of the response

Response Schema: application/json
required
object (ResponseHeader)

Metadata Class

Array of objects (TransactionRejectedInfo)
object (PageInfo)

Paging Information Class

Request samples

Content type
application/json
{
  • "requestHeader": {
    },
  • "accountNumber": "string",
  • "itemIdFrom": "string",
  • "transactionDateFrom": "2019-08-24",
  • "transactionDateTo": "2019-08-24",
  • "bookingDateFrom": "2019-08-24",
  • "bookingDateTo": "2019-08-24",
  • "minAmount": "string",
  • "maxAmount": "string",
  • "pageId": "string",
  • "perPage": 1,
  • "type": "CREDIT"
}

Response samples

Content type
application/json
{
  • "responseHeader": {
    },
  • "transactions": [
    ],
  • "pageInfo": {
    }
}

/getTransactionsCancelled - Get list of user cancelled transactions

Authorizations:
xs2a_auth_aspsp
header Parameters
Authorization
required
string

The value of the Authorization header should consist of 'type' + 'credentials', where for the approach using the 'type' token should be 'Bearer'.

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 Transactions Cancelled Request

required
object (RequestHeaderAISCallback)

PSU and callback URL Information Class

accountNumber
required
string

Account number

itemIdFrom
string <= 128 characters

Filter element - id of transaction or hold to start from

transactionDateFrom
string <date> <= 10 characters

Filter element

transactionDateTo
string <date> <= 10 characters

Filter element

bookingDateFrom
string <date> <= 10 characters

Filter element. Ignored during list of holds retrieval.

bookingDateTo
string <date> <= 10 characters

Filter element. Ignored during list of holds retrieval.

minAmount
string^(0|([1-9][0-9]{0,}))\.\d{2}$

Filter element

maxAmount
string^(0|([1-9][0-9]{0,}))\.\d{2}$

Filter element

pageId
string

Used for paging the results. Identifier of the page to be returned in the response.

perPage
integer <int32> >= 1

Page size (paging info)

type
string
Enum: "CREDIT" "DEBIT"

Filter element

Responses

Response Headers
Content-Encoding
string

Gzip, deflate

X-JWS-SIGNATURE
string

Detached JWS signature of the body of the response

Response Schema: application/json
required
object (ResponseHeader)

Metadata Class

Array of objects (TransactionCancelledInfo)
object (PageInfo)

Paging Information Class

Request samples

Content type
application/json
{
  • "requestHeader": {
    },
  • "accountNumber": "string",
  • "itemIdFrom": "string",
  • "transactionDateFrom": "2019-08-24",
  • "transactionDateTo": "2019-08-24",
  • "bookingDateFrom": "2019-08-24",
  • "bookingDateTo": "2019-08-24",
  • "minAmount": "string",
  • "maxAmount": "string",
  • "pageId": "string",
  • "perPage": 1,
  • "type": "CREDIT"
}

Response samples

Content type
application/json
{
  • "responseHeader": {
    },
  • "transactions": [
    ],
  • "pageInfo": {
    }
}

/getTransactionDetail - Get detailed information about user's single transaction

Get detailed information about user's single transaction

Authorizations:
xs2a_auth_aspsp
header Parameters
Authorization
required
string

The value of the Authorization header should consist of 'type' + 'credentials', where for the approach using the 'type' token should be 'Bearer'.

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 transation detail Request

required
object (RequestHeaderAIS)

PSU Information Class

itemId
required
string <= 128 characters

Element (transaction or hold) ID (ASPSP)

accountNumber
required
string <= 34 characters

Sender account number

bookingDate
string <date-time>

Transaction booking date

Responses

Response Headers
Content-Encoding
string

Gzip, deflate

X-JWS-SIGNATURE
string

Detached JWS signature of the body of the response

Response Schema: application/json
required
object (ResponseHeader)

Metadata Class

required
object (TransactionInfo)

Class describing the payment transaction

object (TransactionInfoZUS)

ZUS Transfer Information Class

object (TransactionInfoCard)

Transaction Card Information Class

currencyDate
string <date-time>

Date of the currency exchange rate

Array of objects (CurrencyRate)
baseCurrency
string <= 3 characters

Currency of the transaction, ISO code

amountBaseCurrency
string^(0|([1-9][0-9]{0,}))\.\d{2}$

Amount of the transaction

usedPaymentInstrumentId
string <= 32 characters

Payment Instrument ID

tppTransactionId
string <= 128 characters

Transaction ID (TPP)

tppName
string <= 32 characters

TPP name

rejectionReason
string <= 140 characters

Reason for rejection

holdExpirationDate
string <date-time>

Hold expiration date

splitPayment
boolean
Default: false

true/ false

object (TransactionInfoSp)

Split Payment transaction info class

Request samples

Content type
application/json
{
  • "requestHeader": {
    },
  • "itemId": "string",
  • "accountNumber": "string",
  • "bookingDate": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "responseHeader": {
    },
  • "baseInfo": {
    },
  • "zusInfo": {
    },
  • "cardInfo": {
    },
  • "currencyDate": "2019-08-24T14:15:22Z",
  • "transactionRate": [
    ],
  • "baseCurrency": "str",
  • "amountBaseCurrency": "string",
  • "usedPaymentInstrumentId": "string",
  • "tppTransactionId": "string",
  • "tppName": "string",
  • "rejectionReason": "string",
  • "holdExpirationDate": "2019-08-24T14:15:22Z",
  • "splitPayment": false,
  • "transactionInfoSp": {
    }
}

PIS - Payment Initiation Services

The aim of the PIS is to give customers ability to initiate domestic or cross-border payments.

Diagram of Activity of the PIS Service (Figure 20 from PolishAPI 3.0 specification)

pis-diagram

Diagram of Activity of the PIS Service (Figure 20 from PolishAPI 3.0 specification)

pis-diagram

/domestic - Initiate domestic transfer

Initiate domestic transfer

Authorizations:
xs2a_auth_aspsp
header Parameters
Authorization
required
string

The value of the Authorization header should consist of 'type' + 'credentials', where for the approach using the 'type' token should be 'Bearer'.

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 domestic transfer

required
object (RequestHeaderCallback)

PSU and callback URL Information Class

required
object (RecipientPIS)

PIS Recipient Data Class

required
object (SenderPIS)

Domestic and Foreign PIS services Sender Data Class

required
object (TransferData)

Transfer Data Class

tppTransactionId
required
string <= 128 characters

Transaction ID (TPP)

deliveryMode
required
string
Enum: "ExpressD0" "StandardD1"

Urgency mode

system
required
string
Enum: "Elixir" "ExpressElixir" "Sorbnet" "BlueCash" "Internal"

The way the transfer should be settled

hold
boolean

Indicates if payment should be held

executionMode
string
Enum: "Immediate" "FutureDated"

Payment execution mode. The superior information deciding which mode is to be used to execute payment.

splitPayment
boolean
Default: false

true / false

object (TransactionInfoSp)

Split Payment transaction info class

Responses

Response Headers
Content-Encoding
string

Gzip, deflate

X-JWS-SIGNATURE
string

Detached JWS signature of the body of the response

Response Schema: application/json
required
object (ResponseHeader)

Metadata Class

paymentId
required
string

Payment ID

generalStatus
required
string (PaymentStatus)
Enum: "submitted" "cancelled" "pending" "done" "rejected"

Dictionary of payment statuses

detailedStatus
required
string

Detailed payment status

Request samples

Content type
application/json
{
  • "requestHeader": {
    },
  • "recipient": {
    },
  • "sender": {
    },
  • "transferData": {
    },
  • "tppTransactionId": "string",
  • "deliveryMode": "ExpressD0",
  • "system": "Elixir",
  • "hold": true,
  • "executionMode": "Immediate",
  • "splitPayment": false,
  • "transactionInfoSp": {
    }
}

Response samples

Content type
application/json
{
  • "responseHeader": {
    },
  • "paymentId": "string",
  • "generalStatus": "submitted",
  • "detailedStatus": "string"
}

/nonEEA - Initiate non SEPA foreign transfers

Initiate non SEPA foreign transfers

Authorizations:
xs2a_auth_aspsp
header Parameters
Authorization
required
string

The value of the Authorization header should consist of 'type' + 'credentials', where for the approach using the 'type' token should be 'Bearer'.

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 non SEPA foreign transfer

required
object (RequestHeaderCallback)

PSU and callback URL Information Class

required
object (RecipientPISForeign)

PIS foreign Recipient Data Class

required
object (Bank)

AIS Bank Data Class

required
object (SenderPIS)

Domestic and Foreign PIS services Sender Data Class

required
object (TransferDataCurrencyRequired)

Transfer Data Class

transferCharges
string <= 3 characters

The cost clause

tppTransactionId
required
string <= 128 characters

Transaction ID (TPP)

deliveryMode
required
string
Enum: "ExpressD0" "UrgentD1" "StandardD2"

Urgency mode

system
required
string
Value: "Swift"

The way the transfer should be settled

hold
boolean

Indicates if payment should be held

executionMode
string
Enum: "Immediate" "FutureDated"

Payment execution mode. The superior information deciding which mode is to be used to execute payment.

Responses

Response Headers
Content-Encoding
string

Gzip, deflate

X-JWS-SIGNATURE
string

Detached JWS signature of the body of the response

Response Schema: application/json
required
object (ResponseHeader)

Metadata Class

paymentId
required
string

Payment ID

generalStatus
required
string (PaymentStatus)
Enum: "submitted" "cancelled" "pending" "done" "rejected"

Dictionary of payment statuses

detailedStatus
required
string

Detailed payment status

Request samples

Content type
application/json
{
  • "requestHeader": {
    },
  • "recipient": {
    },
  • "recipientBank": {
    },
  • "sender": {
    },
  • "transferData": {
    },
  • "transferCharges": "str",
  • "tppTransactionId": "string",
  • "deliveryMode": "ExpressD0",
  • "system": "Swift",
  • "hold": true,
  • "executionMode": "Immediate"
}

Response samples

Content type
application/json
{
  • "responseHeader": {
    },
  • "paymentId": "string",
  • "generalStatus": "submitted",
  • "detailedStatus": "string"
}

/getPayment - Get the status of payment

Authorizations:
xs2a_auth_aspsp
header Parameters
Authorization
required
string

The value of the Authorization header should consist of 'type' + 'credentials', where for the approach using the 'type' token should be 'Bearer'.

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

Payment ID

required
object (RequestHeader)

PSU Information Class

paymentId
string <= 128 characters

Identifier of the payment. Conditionally required - in case TPP has received this identifier from ASPSP.

tppTransactionId
string <= 128 characters

Identifier of transaction established by TPP. Conditionally required - in case TPP has not received paymentId from ASPSP.

Responses

Response Headers
Content-Encoding
string

Gzip, deflate

X-JWS-SIGNATURE
string

Detached JWS signature of the body of the response

Response Schema: application/json
paymentId
required
string

Payment ID

tppTransactionId
required
string

Transaction ID (TPP)

generalStatus
required
string (PaymentStatus)
Enum: "submitted" "cancelled" "pending" "done" "rejected"

Dictionary of payment statuses

detailedStatus
required
string

Detailed payment status

executionMode
required
string
Enum: "Immediate" "FutureDated"

Payment execution mode. The superior information deciding which mode is to be used to execute payment.

required
object (ResponseHeader)

Metadata Class

Request samples

Content type
application/json
{
  • "requestHeader": {
    },
  • "paymentId": "string",
  • "tppTransactionId": "string"
}

Response samples

Content type
application/json
{
  • "paymentId": "string",
  • "tppTransactionId": "string",
  • "generalStatus": "submitted",
  • "detailedStatus": "string",
  • "executionMode": "Immediate",
  • "responseHeader": {
    }
}

/getMultiplePayments - Get the status of multiple payments

Get the status of multiple payments

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

Payments ID list

required
object (RequestHeaderWithoutToken)

PSU Information Class

required
Array of objects (PaymentTokenEntry)

Responses

Response Headers
Content-Encoding
string

Gzip, deflate

X-JWS-SIGNATURE
string

Detached JWS signature of the body of the response

Response Schema: application/json
required
object (ResponseHeader)

Metadata Class

Array of objects (PaymentInfo)

Request samples

Content type
application/json
{
  • "requestHeader": {
    },
  • "payments": [
    ]
}

Response samples

Content type
application/json
{
  • "responseHeader": {
    },
  • "payments": [
    ]
}

CAF - Confirmation of the Availability of Funds Service

The aim of the CAF is to check whether a specific amount is available on a payment account before initiating a transaction.

Diagram of Activity of the CAF Service (Figure 22 from PolishAPI 3.0 specification)

caf-diagram

Diagram of Activity of the CAF Service (Figure 22 from PolishAPI 3.0 specification)

caf-diagram

/getConfirmationOfFunds - Confirmation of the availability of funds

Confirming the availability on the payers account of the amount necessary to execute the payment transaction, as defined in Art. 65 PSD2.

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

Object with amount to check

required
object (RequestHeaderWithoutToken)

PSU Information Class

accountNumber
required
string <= 34 characters

Account number

amount
required
string^(0|([1-9][0-9]{0,}))\.\d{2}$

Amount of the transaction

currency
required
string <= 3 characters

Currency of transaction (ISO)

Responses

Response Headers
Content-Encoding
string

Gzip, deflate

X-JWS-SIGNATURE
string

Detached JWS signature of the body of the response

Response Schema: application/json
required
object (ResponseHeader)

Metadata Class

fundsAvailable
required
boolean
Enum: true false

Status - are funds available

Request samples

Content type
application/json
{
  • "requestHeader": {
    },
  • "accountNumber": "string",
  • "amount": "string",
  • "currency": "str"
}

Response samples

Content type
application/json
{
  • "responseHeader": {
    },
  • "fundsAvailable": true
}