Common API Elements

The following common elements apply to all Open Banking APIs, so please keep it in mind while implementing any of the endpoints.

Timezones and Time Formats

The ISODateTime standard is used in the Open Banking v3 API.

  • Datetime fields sent towards the Open Banking Service should have a timezone (for example: YYYY-MM-DDThh:mm:ssZ or YYYY-MM-DDThh:mm:ss+02)

  • Date fields sent towards the Open Banking Service are always interpreted as being in UTC.

API Compatibility Policy

All APIs follow the robustness principle: "be conservative in what you do, be liberal in what you accept from others". This means the following cases MUST NOT cause an error on client or server side:

  • unrecognized query parameters

  • unrecognized headers

  • unrecognized fields in body

Links Section

In the responses to API calls, usually a section called Links is included. This section contains endpoints that might be or even have to be called by the Initiating Party for the next steps. As described in section Authorization Flow, the ASPSP decides on the authorization approach. The next steps for authorization of a consent or payment depend on this decision. Additionally some ASPSPs have implemented a standard protocol with some deviations which may result in slightly different flows as well.

In order to inform the Initiating Party on the next request required for an authorization the links section provides the corresponding links. If a redirection of the PSU is required for example, the corresponding URL for that redirection is given in the link called RedirectUrl. In case of Decoupled Approach the PSU needs to be identified to the ASPSP for enabling him to send out a Push Notification to a mobile device for example. In this case the PostIdentificationForDecoupled is given in the response.

In the description of the response to the different API requests all possible links that may appear in the links section for that API are listed. Depending on the actual situation one or more links might be included in the response.

The URLs given in the links section are provided as complete ones including the domain name and query parameters if required. An example for links with query parameters are paginated responses where the query parameter allows to address the first, next, previous or last page.

Error Response

If a request cannot be executed successfully an error response is given. The structure of error responses is the same for all APIs. Additional to the standard HTTP Status a body is provided giving more detailed information on the error. The link is provided in the error response for future use and is currently not filled for any error response.

Mult.

Name

Comments

Type

[1..1]

Code

The Error code

String

[1..1]

Message

The description of the error. In a human readable form.

String

[0..1]

Details

Details of the error which could be useful for a developer

String

[0..1]

Link

 

Group

[1..1]

+ Href

URL

String

 

Retries

  • Transaction initiation: In case of receipt of a non-deterministic failure (timeout or 5xx), parties SHOULD retry the POST /payments API once.

    • When after this retry a second non-deterministic failure (timeout or 5xx) is received, this SHOULD be considered and communicated as a deterministic failure.

  • Transaction callback: The Open Banking Service will attempt to perform incremental retries of a callback up to 24 hours if it does not receive a response within 8 seconds and/or receives a different response code than 200 OK, 202 ACCEPTED or 204 NO CONTENT to the initial callback. The retries follow a fixed schedule that are defined in the API specifications.

Enable "on this page" menu on doc section
On