PSD2 Authorization API v2

Important update: Please, update your business id so that it equals to string parameter OID.2.5.4.97 in your PSD2 certificate prior to your application registration.

We recommend creating new application and subscribe new version of APIs there.

Application registration

Access to the OpenBanking API is protected by client certificates and OAuth protocol-compliant tokens. Therefore, before you can register your certificate and start obtaining OAuth you must create an "application record" to register your Client ID and client secret (for more details see description of OAuth protocol).

You can perform this action in this portal in the Dashboard/Applications section. There you can create a new Application using the following steps.

  1. Click "Add Application" and fill the form.
    1. Application name - is the visible name of your application 
    2. Platform - currently select "ServerApplication". In future the system will support also mobile applications.
    3. In the Description box write a description of your application. This field is for your own use.
    4. Click "Next step".
  2. On the second screen (API  Management) choose from the "Choose an API"  dropdown box  a combination of the following items.
    1. PSD2 - this is the production version of the PSD2 (OpenBanking API) - select this if you want to use the APIs for production
    2. For each of the selected API group you will be asked to read and accept conditions of use.
    3. Once you add all required API groups and accept their Terms and Conditions, click "Next step"
  3. Third screen "Auth" is used to define OAuth parameters. During application setup you can only specify the following items
    1. Callback URL - a URL in your application where the bank will send OAuth authorization code and other responses. The  URL must be filled-in, must point to your system and must use https:// scheme (SSL).
    2. Click "Save"

Your application will get into “Pending approval” and must be approved by bank administrator. Upon approval you will receive confirmation e-mail.Then you can open the dashboard/Application again and on application record click the cog and select “Edit”. On Auth tab you will find the client_id and client_secret.

  • Key - is the client_id as referred to in OAuth and in the API documentation.
  • Secret - is the client_secret, i.e. application password, as referred to in OAuth and this API documentation. Keep this value secret and do not share it.

After completing this procedure your application is registered for OAuth and ready to enrol a client certificate.

On the API Management you can view the APIs assigned to the application and their associated API plan. By default, the plan is set to Sandbox (this will enforce sandbox behaviour of all calls). To change behaviour to production, request change to “production plan” for all APIs (one-by-one).

If you mix various plans for the APIs in the PSD2 group, your application calls will be denied access and plans must be setup properly.

API Documentation

General information on calling the external APIs

Typical sequence of API calls is as follows

  1. Register the organisation and application on the API portal for use of PSD2 API to obtain valid API key.
  2. Register the client authentication certificate https://apiauth.moneta.cz/api/v2/oauth/register
  3. Request consent of the bank customer https://api.moneta.cz/api/v2/oauth/auth
  4. Obtain the initial token https://apiauth.moneta.cz/api/v2/oauth/token
  5. Refresh the token if needed https://apiauth.moneta.cz/api/v2/oauth/token

API key handling

All API calls require a valid API key, i.e. the developer must register an application on the API developer portal and assign PSD2 APIs to the application (see above). If any of the external APIs is called without a valid API key or with API key that is not assigned to PSD2 APIs, the system denies access with the error message “API Key is not valid for the service”.

API gateway also monitors usage and if the call quota is exceeded, it also denies access. The detailed error message then informs that plan limits were exceeded.

API key can be submitted in several ways as described below

  • In OAuth calls (/api/v2/oauth/auth and /api/v2/oauth/token) it is submitted in the http parameter client_id as specified in OAuth specification.  In case of refresh token call to /api/v2/oauth/token the API key is derived from the valid OAuth token
  • While calling the Open Banking API (/api/*) the API key is extracted from the valid OAuth token in case of AISP and PISP calls or must be provided explicitly as HTTP header named “apikey” in case of CISP

Below is a precedence list of identifying the API key in the request, first successful match is used. In case where OAuth protocol requires client_id parameter the API key submitted in HTTP header or OAuth token must match the value of the explicitly submitted client_id otherwise access is denied. API key is determined from the following options (first successful attempt is considered) included in the HTTP request

  • HTTP parameter client_id
  • HTTP parameter apikey
  • HTTP header apikey
  • Valid OAuth 2 token (access token)

Sandbox calls

All APIs can be called in “sandbox” mode. This mode provides simplified dummy data responses and is intended for TPP integration testing. When calling sandbox mode all APIs in the call cycle (i.e. OAuth, PSD2) must be called in sandbox  - mixing sandbox and non-sandbox is not supported.

If the application registration has “Sandbox” API plan assigned to the specific API endpoint, APIGW enforces sandbox mode. Note that API plan is assigned to individual APIs added to the application record. All APIs shall have the same API plan.

Use of sandbox mode is indicated by HTTP header if Sandbox is set to true in the response.

The following special behaviours apply in sandbox mode

  • OAuth authorization (/api/v2/oauth/auth) does not call the federated login, but issues the authorisation code immediately without a need to enter SMS authentication code (it does not therefore require real bank account);
  • All OAuth scopes (for authorisation code and tokens) are prefixed with “Sandbox” (“SandboxAISP” instead of “AISP”) and may be used only for sandbox PSD2 API calls
  • PSD2 API calls return dummy, fixed data. The backend does not check any input parameters and returns the dummy data instead. All security checks apply as usual;
  • Certificate registration does not differ in sandbox calls. Sandbox certificate registrations can be used for non-sandbox calls and vice-versa.

/api/v2/oauth/register – TPP authentication certificate registration

This API is used to register the client certificate with the application API key (client_id). The certificate must be issued by an accepted CA (trust anchor and listed in PSD2 CA list), must contain the registered business ID in its subject and must contain embedded PSD2 licences.

Currently supported PSD2 licence formats are European ETSI document (ETSI TS 119 495 V1.1.1 (2018-05)), section 5. In addition to this format, two encoding formats used by I.CA since beginning of 2018 are also supported.

Calling the API

The API is called using POST HTTP method with client certificate authentication. Other methods are not supported.

The client makes a request to the token endpoint by sending the following parameters using the "application/x-www-form-urlencoded" format with a character encoding of UTF-8 in the HTTP request entity-body:

Parameter name

Description

Notes, restrictions

client_id

A valid application client_id (API key) registered in the API portal.

The value must be present and must be registered in the API portal.

client_secret

A valid application client_secret registered in the API portal

The value must be present and must match the value registered in the portal.

action

The requested registration action

  • ·         register (or empty value) – the default value of action. Attempts registration of the new certificate. Fails if there is already certificate registered for the client_id;
  • ·         update – update the existing registration, i.e. replace the values for the client_id with values retrieved from the new certificate. Note: previously used update_appid value for update may be used, but it will be deprecated in future version.
  • remove – delete the existing certificate registration from the database for the given client_id. Note: previously used remove_appid value for update may be used, but it will be deprecated in future version.

The parameter must be one of , register, update, delete.

Please note that due to caching of data, uto registered certificate may take up to 5 minutes to become active.

 

Notes

  • Certificate management allows the bank to set certificate status to “DISABLED” – this status blocks all registration actions, i.e. update or remove actions will fail if the certificate registration is administratively disabled. The error message provides this detail to the TPP.
  • If the certificate does not contain any valid PSD2 licence, registration fails. The error message provides this detail to the TPP.
  • After changes, the previous certificate will not be active anymore, and it is necessary to wait 5 minutes before new one becomes active.
  • With update no remove is needed as it will be executed automatically with the update.

Response from API

The response from the API is a JSON structure containing information about the action and its result. In case of failure, the message contains an error message and error details instead of registration data.

Sample success message

{
       "registrationStatus": "SUCCESS",
       "resultCode": "200",
       "registrationAPI": "v2",
       "result": {
             "responseCode": "200",
             "responseDesc": "Certificate update successful",
             "registeredCN": "www.testorg1.cz",
             "assignedPSD2group": "PISP,CISP,AISP"
       }

}

Sample error message

{
       "registrationStatus": "FAILED",
       "resultCode": "409",
       "registrationAPI": "v2",
       "error": {
             "errorMessage": "Certificate registration failed - certificate is already registered",
             "errorType": "Client certificate registration error",
             "errorDetail": "Requested certificate DN was: ST=Hlavní město Praha, OID.1.3.6.1.4.1.311.60.2.1.3=CZ, OID.2.5.4.15=Private Organization, SERIALNUMBER=111456121, OID.2.5.4.17=13000, L=Praha 3, STREET=Roháčova 188/37, O=TestOrg1 s.r.o., CN=www.testorg1.cz, C=CZ",
             "errorCode": "409"
       }
}

Register error messages

The following error messages are provided back to the TPP system.

HTTP response code

error

400

This error code indicates that access was denied. This is happening in the following situations

  • Missing mandatory parameter or invalid value thereof.
  • Application was not able to load registration data associated with the API key.

Additional information is always provided in the error_description element.

403

This error code is issued in the following cases

  •  when the API key is not authorised to call the service. This is typically caused by invalid or not provided API key or in cases when API call quota has been exceeded. The issued error is Access denied.
  • When invalid client_secret is provided. Error message is “Unauthorized client”
  • Client certificate cannot be validated to trusted CA list or the certificate does not contain PSD2 licences. Error message is “Client certificate validation errors”
  • Certificate is already registered, but is set to “disabled” state – registration changes are not permitted. Error message is “Certificate is registered, but is administratively blocked”.

Additional information is always provided in the error_description element.

409

This error code is issued when update or delete of the certificate cannot be performed due to technical reasons (certificate already registered, update or delete fails) or when the bank has blocked the certificate it is in “disabled” state.

500

 The check does not respond with 500 HTTP code, except for serious infrastructure related failures.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

/api/v2/oauth/auth – OAuth authorization

The /api/v2/oauth/auth endpoint handles initial phase of the Authorization code type grant as specified in RFC6749 OAuth 2.0. TPP Application redirects the bank customer (resource owner) to this endpoint via HTTP redirect with parameters specified below. The API endpoint manages subsequent redirects of the bank customer, again via HTTP redirects, to the login page. After successful login and authorisation in Federated login app, the API redirects the customer back to the callback URL specified by the TPP with the issued authorization code value.

In case of failure API tries to redirect the customer back to callback URL to notify the TPP about the failure. Only in case where the callback URL cannot be determined (typically invalid API key or missing callback URL), it displays an error message to the customer.

Errors are signalled back to the TPP system using error parameter in the return call as described in OAuth protocol.

Calling the API

The API is called with the following parameters provided in the query string of the URL.

Parameter name

Description

Notes, restrictions

client_id

A valid application client_id (api key) registered in the API portal.

The value must be present and must be registered in the API portal.

See also the API key section above

client_secret A valid application client_secret registered in the API portal The value must be present and must be registered in the API portal.

response_type

A fixed string with a value “code” indicating the OAuth 2.0 grant type.

The value must be present and must be “code”. Other values result in unsupported grant type error.

scope

Set of requested scopes for token issuance. The resulting scopes are an intersection of the following sets

  • The scopes requested by TPP in initial call
  • The PSD2 licences granted in the TPP authentication certificate

Scope must be one of the following values¨

  • Any combination of PISP and AISP strings (case sensitive) separated by space. The set must match the PSD2 licences embedded in the registered client certificate. Requesting scope that is missing in the certificate results in invalid scope error;
  • Deprecated: ALL for compatibility with previous versions scope may be set to “ALL”. This is transparently converted to AISP+PISP. If TPP is missing any of these scopes in the licence, invalid scope error is issued.

state

An opaque value used by the client to maintain state between the request and callback. The authorization server includes this value when redirecting the user-agent back to the client.

The parameter is optional but SHOULD be used for preventing cross-site request forgery.

 

OAuth parameter redirect_url (or commonly referenced here as callback URL) is not read from the HTTP request, but instead the API uses the URL registered in the application record on the API Portal. The callback URL must use https:// scheme (i.e. must start with https://) otherwise the system rejects it and fails without notifying TPP system.

Response from API

If the resource owner grants the access request, the authorization server issues an authorization code and delivers it to the TPP system by adding the following parameters to the query component of the redirection URI.

Parameter name

Description

Notes, restrictions

code

The authorization code generated by the authorization server. The authorization code expires 10 minutes after it is issued to mitigate the risk of leaks.

Code is a UUID type string and is always present

state

The exact value received from the client in initial call

If the "state" parameter was present in the client authorization request, this response is mandatory. Otherwise empty value is returned.

 

Failures

If the request fails due to a missing or invalid redirection URI, or if the API key (client_id) is missing or invalid, the authorization server informs the resource owner of the error and does not automatically redirect the user-agent to the redirection URI. Text failure message is displayed instead with HTTP code 400

If the resource owner denies the access request or if the request fails for reasons other than a missing or invalid redirection URI, the authorization server informs the client by adding the following parameters to the query component of the redirection URI. The error parameter is used to signal problem cause instead of HTTP codes (as specified by OAuth protocol).

Parameter name

Description

Notes, restrictions

error

Error type ass specified in RFC.

  • invalid_request - The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed.
  • unauthorized_client - The client is not authorized to request an authorization code using this method.
  •  access_denied - The resource owner or authorization server denied the request.
  •  unsupported_response_type - The authorization server does not support obtaining an authorization code using this method.
  •  invalid_scope - The requested scope is invalid, unknown, or malformed or the requested scopes exceed the licences embedded in the registered PSD2 certificate.
  •  server_error - The authorization server encountered an unexpected condition that prevented it from fulfilling the request.
  •  temporarily_unavailable - The authorization server is currently unable to handle the request due to a temporary overloading or maintenance of the server.

Standard error codes are provided using 302 HTTP redirect to callback URL

In cases where the callback URL cannot be determined, 400 HTTP codes with a simple text message are returned to customer browser.

error_description

 

OPTIONAL. Human-readable ASCII text providing additional information, used to assist the client developer in understanding the error that occurred.

The error description does not have to be present in every case, but normally it provides additional information about the cause of the error.

 

For more details on Authorization code grant see https://tools.ietf.org/html/rfc6749#section-4.1.1 (request) and https://tools.ietf.org/html/rfc6749#section-4.1.2 (response)

In rare situations caused by system malfunction the application may respond using HTTP code 500 with additional information provided in the text body of the message. This indicates a temporary technical problem in the bank system.

/api/v2/oauth/token – OAuth token management

This API endpoint handles the issuance of the access and refresh tokens as described in OAuth 2.0 RFC. It supports authorization code type grant and refresh grant only.

In order to call the API the TPP must authenticate using a client certificate that has been already registered for the given client_id (API key).

The API checks the scopes granted to the code and PSD2 licences present in the certificate and issues the initial token with an intersection of these two sets.

While refreshing the access token the API allows refresh of only AISP scope token. All other scopes are removed from the refreshed token even if the validity of the original access token for PISP has not yet expired. Refreshability of scopes can be configured in the main configuration policy.

Token issue

This call type issues the access and refresh token based on the authorization code obtained in call to /api/v2/oauth/auth. Each authorization code may be used only once, i.e. it is invalidated by the first call.

Refresh token is issued only if the client is granted AISP scope or AISP+PISP scopes as only AISP scope permits refresh of the token.

Calling the API

The API must be called using POST HTTP method with client certificate authentication. Other methods are not supported.

The client makes a request to the token endpoint by sending the following parameters using the "application/x-www-form-urlencoded" format with a character encoding of UTF-8 in the HTTP request entity-body:

Parameter name

Description

Notes, restrictions

client_id

A valid application client_id (API key) registered in the API portal.

The value must be present and must be registered in the API portal.

It must be the same client_id as used to obtain the code.

client_secret A valid application client_secret registered in the API portal The value must be present and must be registered in the API portal.

grant_type

A fixed string with a value “authorization_code” indicating the OAuth 2.0 grant type.

This parameter is required.

code

The value of authorization code obtained in previous call to /api/v2/oauth/auth

The paremeter is required.

Note: it is not possible to use code obtained in sandbox mode to request non-sandbox token

This call type is used to obtain a new access token by presenting a valid refresh token. Note that only selected scopes – currently AISP – allow token refresh. All other scopes are configured not to refresh the access token.

Note: If the refresh is called before the validity of the original non-refreshable token expires, the token in invalidated and new token is not issued. Calling refresh will therefore invalidate the PISP scope for the token.

Response from API

The response from the API is a JSON structure containing the issued tokens (access and refresh) and also additional information. Sample token is below :

{
 "access_token":"2YotnFZFEjr1zCsicMWpAA",
 "token_type":"Bearer",
 "expires_in":1200,
 "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
 "scope":"AISP PISP"
}

In case the client requested only PISP scope, the response would be without refresh token, i.e.

{
 "access_token":"2YotnFZFEjr1zCsicMWpAA",
 "token_type":"Bearer",
 "expires_in":1200,
 "scope":" PISP"
}

 

Failures

In case of failure or denied access, the API responds back to TPP system with an error message. 

Token refresh

This call type is used to obtain a new access token by presenting a valid refresh token. Note that only selected scopes – currently AISP – allow token refresh. All other scopes are configured not to refresh the access token.

Note: If the refresh is called before the validity of the original non-refreshable token expires, the token in invalidated and new token is not issued. Calling refresh will therefore invalidate the PISP scope for the token.

Calling the API

The API is called using POST HTTP method with client certificate authentication. Other methods are not supported.

If the authorization server issued a refresh token to the client, the client makes a refresh request to the token endpoint by adding the following parameters using the "application/x-www-form-urlencoded" format with a character encoding of UTF-8 in the HTTP request entity-body:

Parameter name

Description

Notes, restrictions

refresh_token

The refresh token issued to the client.

The value is mandatory

grant_type

A fixed string with a value “refresh_token” indicating the OAuth 2.0 grant type.

The value is mandatory

  • scope– this parameter specified in OAuth 2.0 is not requested and if present will be ignored.

Response from API

The response from the API is a JSON structure containing the issued tokens – the refresh token is not replaced, access token is the new value and also additional information. Sample token is below

{
 "access_token":"2YotnFZFEjr1zCsicMWpAA",
 "token_type":"Bearer",
 "expires_in":1200,
 "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
 "scope":"AISP"
 }

Failures

In case of failure or denied access the API responds back to TPP system with an error message. 

Token error messages

Token API endpoint responds with the following error messages (both issue and refresh calls) and codes as specified by the OAuth 2.0 standard. The error response is a JSON object containing the error element, bearing error code defined in OAuth and also error_description element where more detailed message is provided.

Sample error response body is as follows

{
 "error":"invalid_client",
 "error_description":"Invalid API key/secret combination"
}

The HTTP response codes and relevant OAuth error values are listed below.

HTTP response code

error

400

This error code indicates that access was denied. OAuth specifically mandates use of 400 error code instead of more specific HTTP error codes. The detailed reason is signalled in the error element that may have the following values:

  • unsupported_grant_type – this is issued when the grant_type parameter is not supported by the server
  • invalid_request – content type security not passed or missing required parameter;
  • invalid_grant – the authorization code is not valid, refresh token is not valid;
  • invalid_client – the client authentication has failed. This is typically caused by invalid client_id/client_secret combination, invalid or unregistered PSD2 certificate mismatching licences or mismatch between the registered and used client certificate
  • server_error – this error code indicates other temporary technical problem on the OAuth server side

Additional information is always provided in the error_description element.

403

This error code is issued only in case when the API key is not authorised to call the service. This is typically caused by invalid or not provided API key or in cases when API call quota has been exceeded. The issued error is invalid_client.

Detailed information is in error_description.

500

 The check does not respond with 500 HTTP code, except for serious infrastructure related failures