Api documentation get started
Download OpenAPI specification:Download
On this page, you will find valuable content required for a successful self-onboarding process before utilizing our APIs. This information is intended for third-party providers seeking to understand the process.
This page provides a high-level summary of the system, and each linked page delves into specific stages of the onboarding process.
Our recommended approach is to follow this step-by-step guideline initially
This guide will walk you through the process of registering an account within our developer portal. Upon completion, you'll gain access to the resources necessary for developing innovative financial applications and services compliant within the European Economic Area (EEA).
To access the OpenBanking Developer Portal, you need to register for an account. Navigate to the registration page and provide the required information, such as your name, email address, and organization details.
Once you've registered, you'll receive an email to verify your account. Click on the verification link provided in the email to activate your account.
Once you are logged in, you will need to register your TPP from the dashboard. You'll be prompted to enter a Registered name, Email, Phone Number and country.
From the dashboard, create a new application. You'll be prompted to enter the application name, description, and other relevant details. This application will be associated with your API access and usage. By creating the application you will get ClientId and ClientSecret that will be used for the OAuth Flow described in the Strong Customer Authentication (SCA) section.
By using our developer portal, you can generate a new certificate or import an existing one. This certificate is used for mTLS authentication of the TPP with the Open Banking API.
Familiarize yourself with the API documentation available on the Developer Portal. The documentation provides comprehensive information about available endpoints, request parameters, response formats, and authentication methods. This knowledge is crucial for integrating the OpenBanking APIs effectively.
To ensure that your integration works seamlessly, use the provided sandbox environment to test the APIs. The sandbox environment mimics the live environment, allowing you to experiment with different API calls without affecting real data.
Now that you have verified your application and tested the APIs, you can begin implementing OpenBanking functionality into your financial application. You may choose to build services that access account information through AISPs or initiate payments through PISPs, depending on your use case.
As you develop your financial application, make sure to adhere to OpenBanking compliance and security standards. Ensure that your application follows Strong Customer Authentication (SCA) requirements and other relevant regulations to safeguard user data and enhance transaction security.
Once your application is live and operational, it's essential to continuously monitor its performance and usage. Use the Developer Portal's analytics tools to gather insights on API usage, response times, and user behavior. This data will help you optimize your application for better user experience.
Production Only StepBefore going live, you need to register your Third-Party Provider (TPP) credentials on the designated TPP Registration Endpoint. This is located in the Authentication API Documentation Section under the TPP Registration Menu. This step is required only for production environments and allows seamless operation in the live Open Banking ecosystem.
If you encounter any challenges or have questions during the development process, don't hesitate to reach out to the OpenBanking Developer Portal support team. They are there to assist you with any technical issues or inquiries you may have.
Before a detailed description is given for the use cases mentioned above, the following gives an overview of the involved parties:
The Payment Service User (PSU) wants to provide access to its account to one of the three different TPP types, the Payment Initiation Service Provider (PISP), the Account Information Service Provider (AISP), or the Payment Instrument Issuing Service Provider (PIISP) which in turn access the PSU’s bank account that is provided through the Account Servicing Payment Service Provider (ASPSP) - the bank.
Only those TPP that are licensed under the PSD2 will be authorized to access the PSU’s bank account and the available data.
For the Payment Initiation Service (PIS) and the Account Information Service (AIS), the user must confirm the access through a TPP-controlled pre-step, where a Strong Customer Authentication (SCA) is normally required. After successfully authenticating the PSU and authorizing the access through a certain SCA approach, the payment will be initiated / the access to account information will be granted.
For doing the Confirmation Of Funds Service (CoF), a different pre-step is required directly between the PSU and the bank. There, a consent will be granted for a TPP to access a specified bank account for a specific payment instrument (card) to get the information (true/false) if a certain instructed amount of funds is available on the PSU’s account.
As a TPP, you can access the APIs either for testing purposes (e.g. to build your integration in a sandbox environment) or to get access to the production systems.
The provided API is secured by a mutual TLS mechanism. In order to use the API, you as a TPP need to have a valid Qualified Website Authentication Certificate (QWAC) signed by a qualified trust service provider (QTSP).
To get access to the testing environment (sandbox), you can use your valid official QWAC (provided through a QTSP) that you should have as a regulated TPP under the PSD2. If you do not have a QWAC yet, but you already applied for becoming a regulated TPP with your national competent authority (NCA) then you can generate a new one using our developer portal.
For accessing the production environment, you need to always use your official QWAC.
To test the authentication / authorisation via the QWAC, you can do an example API call that could look like the following (given that the certificate files are in the current directory):
curl \
-i -H "X-Request-ID: $(uuidgen)" -H "Content-Type: application/json" -H "PSU-IP-Address: 172.217.18.163" \
-X POST -d '{"access":{"accounts":[{"iban":"MK07250120000058984"}]},"recurringIndicator":"false", \
"validUntil":"2023-09-30","frequencyPerDay":"1","combinedServiceIndicator":"false"}' \
{ Base-URL/v1/consents } \
--cert tpp_test.crt:1234 --key private_tpp_test.key
To test the PSD2 APIs you need to get authenticated as a TPP via your QWAC (see section before). Thus, you need to present it with every API request you send to the interface. Whenever a PSU-ID is required by the API please use one of the ones listed in the developer portal sandbox users page.
For the whole API there are general principles that will hold for any API request/response.
Data types are used as they are specified in the Implementation Guidelines of the NextGenPSD2 XS2A Framework from Berlin Group.
Whenever date or time is used, we assume it to be local time.
The allowed character set is restricted to the minimum set specified in the Implementation Guidelines of the NextGenPSD2 XS2A Framework from Berlin Group.
The API requires certain headers to be present in all requests:
| Attribute | Type | Description |
|---|---|---|
| X-Request-ID | UUID | Generate it for every request; must be unique |
| Whenever you can provide the following information about the PSU you should add it to the headers. This will help us to detect fraudulent transactions and will secure our common solution for account access: |
| Attribute | Type | Description |
|---|---|---|
| PSU-IP-Address | String | Forwarded IP address of the request between PSU and TPP |
| PSU-IP-Port | String | Forwarded port of the request between PSU and TPP |
| PSU-Accept | String | Forwarded accept header in communication between PSU and TPP |
| PSU-Accept-Charset | String | Forwarded accept charset in communication between PSU and TPP |
| PSU-Accept-Encoding | String | Forwarded accept encoding in communication between PSU and TPP |
| PSU-Accept-Language | String | Forwarded accept language in communication between PSU and TPP |
| PSU-User-Agent | String | Forwarded user agent of the PSU |
| PSU-Http-Method | String | HTTP method used by the PSU to call the TPP |
| PSU-Device-ID | String | UUID for a device used by PSU if available |
| PSU-Geo-Location | GeoLocation | Forwarded geo location if available; based on RFC2426, e.g. “GEO:37.386013;-122.082932” |
Before executing any PSD2 use case, the Strong Customer Authentication (SCA) process must first take place. During this process, the Payment Service User (PSU) must authenticate and authorize access to their bank account(s) for either of the two specific use cases:
Subsequently, the supported SCA approach(es) are described.
The authorization process of the SCA will always start explicitly, i.e., The Payment Initiation Request or Consent creation is followed by an explicit request of the TPP to start the authorization.
TPPs are required to set up the OAuth 2.0 protocol with the authentication server to initiate SCA processes.
grant_type: Authorization Code, incorporating Proof Key for Code Exchange (PKCE) to enhance security.client_id, client_secret, and redirect_uri (Callback URL) are located under Profile -> Applications, visible only to users who are authenticated in the developer portal./connect/authorize. The URL where TPPs send the user to log in and authorize consent./connect/token. The URL for exchanging an authorization code for an access token, usually found at AIS:{consentId} for account information access, where {consentId} is obtained from the POST /consent response.PIS:{paymentId} for payment initiation, with {paymentId} derived from the POST /{payment-service}/{payment-product} response.The key difference in establishing Account Information Service (AIS) Consent and initiating a Payment Initiation Service (PIS) transaction lies in the specific scope parameters used. For AIS consent, the required scope is formatted as AIS:{consentId}, where {consentId} is a unique identifier retrieved from the POST /consent endpoint. Conversely, for PIS transactions, the scope is designated as PIS:{paymentId}, with {paymentId} being the unique transaction identifier obtained from the POST /{payment-service}/{payment-product} endpoint.
Example flow for the successful consent establishment with a OAuth2 SCA:
The sequence diagram above illustrates how to obtain an information from the Account Information Service (AIS).
The process of establishing consent for the account is identical for the payment part; both approaches use the same Strong Customer Authentication (SCA) flow. It's worth mentioning that the Third-Party Provider (TPP) needs to configure the OAuth2 protocol with the authentication server. The OAuth2 flow used for authorization is always Authorization Code (with Proof Key for Code Exchange, PKCE). The clientId, clientSecret, and redirectUrl required for configuring OAuth2 can be found in the developer portal under Profile -> Applications section. The difference between establishing Account Information Service (AIS) and Payment Initiation Service (PIS) consent lies in the scope parameters. For AIS, when providing consent to read the accounts, the scope should be AIS:{consentId}, where consentId is returned from the POST /consent endpoint. For PIS, the scope should be PIS:{paymentId}, where paymentId is returned from the POST /{payment-service}/{payment-product} endpoint.
After successfully authorizing the consent or payment, the authentication server redirects the Payment Service User (PSU) to the redirectUrl defined in the application that is created in the developer portal.
As the redirect of the PSU won't give you more information than that the SCA process is finalised, you need to retrieve the outcome of the SCA in one of the next steps, e.g. by calling the endpoint to get the consent / payment status.
The decoupled SCA approach is very similar to the redirect approach. The main difference is that the PSU will not redirect to the ASPSP’s authentication website. This authentication needs to be done through an independent application or a device from the ASPSP's end (e.g. a mobile application). It means that the PSU should authenticate itself through a methodology that should be decoupled from the main authentication flow. Similar to the redirect approach it's easy to implement and an effective approach as the interaction is between ASPSP and PSU.
To retrieve the current status of a SCA the following endpoints can be used for the different contexts. The consentStatus will be used as described in [BG-ImplGL-1.3]
Context of a consent establishment request:
GET /v1/consents/{consentId}/authorisations/{authorisationId}
Context of a payment initiation request:
GET /v1/{payment-service}/{payment-product}/{paymentId}/authorisations/{authorisationId}
During Strong Customer Authentication (SCA), the Payment Service User (PSU) is typically prompted to confirm a transaction or consent using their second factor.
The SCA methods can be obtained from the response of the Consent Creation or Payment Initiation endpoint:
Consent establishment request:
POST /v1/consents/{consentId}
Payment initiation request:
POST /v1/{payment-service}/{payment-product}
Upon a successful request, the response will include scaMethods that are available. The SCA Method with authenticationType set to CHIP_OTP indicates the Redirect Approach, while PUSH_OTP indicates the Decoupled Approach.
You can specify which SCA method to use in the subsequent Start Authorisation endpoint by including one of the following headers, depending on the preferred SCA Method:
true for the Redirect Approachtrue for the Decoupled ApproachStart the Authorisation Process for a Consent:
POST /v1/consents/{consentId}/authorisations
Start the Authorisation Process for a Payment:
POST /v1/{payment-service}/{payment-product}/authorisations
Upon a successful request, the response will contain chosenScaMethod with a corresponding value based on the header sent in the same request.
The next sections contain the information about how the different use cases will be realized. This will be done on a coarse-grained level to show the overall context of the different steps. Details of the individual API endpoints and how they are used can be found in the on the api product page. Please check the AIS, PIS, and CoF api refference documentation for more details.
Account Information Service
Account Information Services Provider or ‘AISP’ refers to a person licensed by the Central Bank to provide account information services using an online portal, mobile or smartphone application, device or other electronic media which a consenting customer can use to obtain aggregate or consolidated information about his / her account balances with ASPSP.The role of an AISP is restricted to providing the technology or other means in order to provide account information to the customer and the handling of communication or electronic documents between the customer and the licensees should the terms of the offer include such services.AISPs must not receive or otherwise handle customer funds in the course of providing account information services.
An Application Programming Interface or ‘API’ is a set of routines, protocols, and tools for building software applications.An API specifies how software components should interact.
Account Servicing Payment Service Providers or ‘ASPSP’ refers to the Central Bank licensees who provide and maintain a payment account for a user / customer and, in the context of the Open Banking Ecosystem are entities that publish Read / Write APIs to permit, with customer consent, payments initiated by third party providers and / or make their customers’ account transaction data available to third party providers via their API endpoints.
Authentication is the process of verifying that an individual is who it claims to be.This authentication is later used to grant authorization to specific data and functions within a system.
Berlin Group
Consent is the agreement given by the PSU to the TPP to share data from the bank. Consent is stored by the bank and validated by the user according to PSD2.The consent may have a duration or just be used for a single API call.
European Telecommunications Standards Institute
Funds Confirmation Service
Identity and access management(IAM) is a framework of policies, processes, and technologies that enable the right individuals to access the right resources at the right times for the right reasons.
An IBAN, or international bank account number, is a standard international numbering system developed to identify an overseas bank account.
JavaScript Object Notation or ‘JSON’ is a lightweight data - interchange format.It is easy for humans to read and write.It is easy for machines to parse and generate.JSON is a text format that is completely language independent but uses conventions that are familiar to programmers of the C - family of languages, including C, C++, C#, Java, JavaScript, Perl, Python, and many others.
Functionality, endpoints and fields marked as Mandatory are required in all cases for regulatory compliance and / or for the API to function and deliver essential customer outcomes.
For functionalities and endpoints:
For fields:
Message encryption is implemented through JSON Web Encryption(JWE).
The approach differs from message signing in that:
The APIs require TLS 1.2 Mutual Authentication and this may be used as a means of non - repudiation.However, it would be difficult to maintain digital records and evidence of non - repudiation if the API only relied on TLS 1.2.A solution for non - repudiation that does not rely on TLS, would be achieved by providing a JWS with detached content(as defined in RFC 7515 - Appendix F) in the HTTP header of each API request.The HTTP body would form an un - encoded payload as defined in RFC 7797. The JWS would be signed using an algorithm that supports asymmetric keys.A request would be signed by an AISP / PISP's private key and a response would be signed by the ASPSP's private key.Not all API requests and responses are signed.Whether message signing is mandatory, supported or not supported is documented along with each API.
NCAs, or National Competent Authorities, are regulatory or governmental bodies responsible for the supervision, registering and authorisation of financial service providers.They also publish registers for use by: Qualified trust service providers, to make decisions on issuing certificates.
NextGenPSD2 Implementation Support Program or 'NISP' supports banks, associations, schemes and interbank processors in implementing the Berlin Group NextGenPSD2 Framework.
Functionality and endpoints marked as Optional are not necessarily required for regulatory compliance but may be implemented to enable desired customer outcomes.
For functionalities and endpoints:
For fields:
Open Banking is the secure way to give providers access to customer’s financial information.It opens the way to new products and services that could help customers and small to medium - sized businesses get a better deal.It could also give you a more detailed understanding of customer’s accounts, and help customers find new ways to make the most of their money.Open banking also refers to sharing and leveraging of data(for which customer has consented) by banks with third party developers and firms to build applications and services.For example, third party providers(TPPs) provide real - time payments, greater financial transparency options for account holders, marketing and cross - selling opportunities.
Payment Instrument Issuer Service
Payment Instrument Issuer Service Provider
Payment Initiation Service
Payment Initiation Service Provider or ‘PISP’ refers to a person licensed by the Central Bank to initiate payment or credit transfers for the customer from an account held with an ASPSP.The role of a PISP is restricted to providing the technology or other means in order to initiate a payment order and the handling of communication or electronic documents between the customer and the licensees should the terms of the offer include such services.PISPs must not receive or otherwise handle customer funds in the course of providing payment initiation services.
The Second Payment Services Directive, or 'PSD2', is a regulation for electronic payment services in Europe.It is the second Payment Services Directive designed by the countries of the European Union.The primary goals of PSD2 are to make payments in Europe more secure, enhance innovations in the payment sector, and help banking services employ new technologies1.PSD2 updates and enhances the EU rules put in place by the initial PSD adopted in 2007.
Account Information Service Provider
Account Servicing Payment Service Provider
Payment Service Provider issuing card - based payment instruments
Payment Initiation Service Provider
Payment Service User or ‘PSU’ is a natural or legal person(end - user) making use of a payment service as a payee, payer or both.A natural or legal person(end - user) making use of an account information service as part of a consent driven data sharing arrangement.
PSD2 Regulatory Technical Standards
Sandbox gives access to a small set of static data and it is used as an example to illustrate what would be returned when using the production API.
Strong Customer Authentication or ‘SCA’ is an authentication based on the use of three elements categorized as knowledge (something only the user knows[for example, a password]), possession(something only the user possesses[for example, particular cell phone and number]) and inherence(something the user is[or has, for example, a fingerprint or iris pattern]) that are independent, so the breach of one does not compromise the others, and is designed in such a way as to protect the confidentiality of the authentication data.
Single Euro Payments Area
Transport Layer Security
Third Party Providers or “TPP” are Central Bank licensees that use APIs developed to Standards to access customer’s accounts, in order to provide account information services and/or to initiate payments.
Third Party Providers are either Payment Initiation Service Providers(PISPs) or Account Information Service Providers(AISPs) or both Payment Initiation Service Providers(PISPs) and Account Information Service Providers(AISPs).
User Interface
Access to Account Interface
Ain’t Markup Language or ‘YAML’ is a human friendly, cross language, unicode based data serialization language designed around the common native structures of agile programming languages.It is broadly useful for programming needs ranging from configuration files to Internet messaging to object persistence to data auditing.