Getting Started

Welcome to Bank of Ireland's developer portal.

The revised Payment Services Directive (PSD2) mandates banks to provide access to account (XS2A) facilities to licensed Third Party Providers (TPPs). There are three types of Third Party Providers (TPPs):

  • Account Information Service Providers (AISP): AISP APIs are for access to a customer's online payment account data via a TPP.
  • Payment Initiation Service Provider (PISP): PISP APIs are for the initiation of payments from an online payment account via a TPP.
  • Payment Service Providers that are card-based payment Instrument Issuers (CBPII): CBPII APIs are to confirm availability of funds of an online payment account.

PSD2 also states that communications between the ASPSPs and the TPPs have to be secure and compliant with the Regulatory Technical Standards (RTS) on strong customer authentication and common and secure communication.

Bank of Ireland has adopted the Open Banking Implementation Entity (OBIE) standard for compliance with PSD2/CMA regulation. The Bank of Ireland API Platform is designed to provide a ready to use, complete infrastructure for Open Banking APIs.

This portal provides you with a detailed documentation of Bank of Ireland's implementation of the OBIE standard. You can also test our APIs using widely used standard tools for API access. Refer to the section "Steps to follow to test APIs" on this page for details on testing our APIs. For full access to test accounts and to receive important information, help, support and notifications, you must register.

A list of APIs supported by BOI can be viewed here.

How to test Bank of Ireland APIs
A. If you want to test using test eIDAS certificates

resources/image-79d436b4-615b-4f69-817f-b5c0f4b83e0b.png

Prerequisites for testing
  1. Test eIDAS certificates (QWAC & QSealC) that complies with the PSD2 ETSI Profile
Steps to follow to test APIs
  1. Create SSA using widely used online tools. SSA "alg" must be set to "NONE". Details and sample SSA are provided with Dynamic Client Registration API.
  2. Use the additional API to upload root of the test eIDAS certificates.
  3. Register and log in to the Bank of Ireland Developer hub to download the customer profiles/test accounts for testing APIs.
  4. Onboard your application using the Dynamic Client Registration API as per the OBIE specifications with additional claim "x5c" Āincluded in the JWT header. x5c must be set to public key certificate of QSealC.
  5. Call the sandbox POST APIs to set up an AISP/PISP/CBPII request with the bank
  6. Use the sandbox authorisation URL mentioned in the "Authorisation Flow & Redirection Services/URLs" section below to authorise the AISP/PISP/CBPII request. Refer to the test account sheet to choose the customer (PSU ID) profile for testing.
  7. You are now ready to test the Bank's API. Please refer to the section "Points to note when testing APIs" before commencing the testing.
B. If you are present on the Open Banking Directory Sandbox

resources/Image%20B-f0a0930a-71ff-43c5-8348-b1f947d068fa.png

Prerequisites for testing
  1. You will need to have a software statement (SSA) from OBIE Directory Sandbox
  2. If you wish to use production/live certificates, we support the following certificates

    • eIDAS certificates that comply with the PSD2 ETSI Profile
    • OBIE issued certificates compliant with PSD2 ETSI Profile
Steps to follow to test APIs
  1. Create a Software Statement in the Open Banking Directory Sandbox that corresponds to your application.
  2. Attach a set of certificates (transport and signing) for the Software Statement.
  3. Register and log in to the Bank of Ireland developer hub to download the customer profiles/test accounts for testing APIs.
  4. Onboard your application using the Dynamic Client Registration API as per the OBIE specifications.
  5. Call the sandbox POST APIs to set up an AISP/PISP/CBPII request with the bank.
  6. Use the sandbox authorisation URL mentioned in the "Authorisation Flow & Redirection Services/URLs" section below to authorise the AISP/PISP/CBPII request. Refer to the test account sheet to choose the customer (PSU ID) profile for testing.
  7. You are now ready to test the Bank's API. Please refer to the section "Points to note when testing APIs" before commencing the testing.
C. Points to note when testing APIs
  1. APIs can be tested by using tools like Postman, SOAP etc.
  2. Participants will need to present a full certificate chain to invoke APIs i.e. intermediate along with leaf.
  3. To invoke the APIs, you need to "Download test accounts" by registering and logging into the BOI Developer Hub.
  4. Please use the following ASPSP FAPI ID when invoking APIs "0015800000jfQ9aAAE".
  5. Clients/applications have to be created through "Dynamic Client Registration (DCR) API". Existing clients/applications created through Bank of Ireland's previous version of sandbox UI interface will not work.
  6. Protocols supported by the APIs:

    • The OAuth2/ OIDC token endpoint authentication method to follow MTLS (Mutual Transport Layer Security).
    • API payload signing following JWS (JSON Web Signature).
  7. The customer screens (login, account selection etc.) shown in the sandbox authorisation journey are not the actual screens visible to customers in production. Layout, text and supplementary information are indicative only.

Access our live APIs

resources/Access%20our%20live%20APIs%20%282%29-46133d56-93df-410a-b990-f252bc24062e.PNG

Steps to follow to access our live APIs
  1. Enrol as a TPP on the Open Banking Directory.
  2. Create a Software Statement in the Open Banking Directory that corresponds to your application.
  3. The following is supported for each jurisdiction ā€“

    • For Bank of Ireland (ROI), we accept only valid eIDAS certificates that comply with the PSD2 ETSI Profile for PSD2 APIs.
    • For Bank of Ireland UK, we accept both valid eIDAS and OBIE issued certificates that comply with the PSD2 ETSI Profile for PSD2 APIs.
    • Refer to the table ā€˜Certificates Supportedā€™ below for more details.
  4. Onboard your application with us using the Dynamic Client Registration API.
  5. TPP will need to present a full certificate chain to invoke APIs i.e. intermediate along with leaf.
  6. Refer to the .well-known endpoints in the OIDC .well-known endpoint URL section in this page to get details of the URLs and the claims supported by Bank of Ireland.
  7. Protocols supported by the APIs:

    • The OAuth2/ OIDC token endpoint authentication method to follow MTLS (Mutual Transport Layer Security).
    • API payload signing following JWS (JSON Web Signature).
  8. Current BOI implementation supports a key size of up to 2048-bit for client based authentication. Hence it is recommended that TPPs use client certificates with up to this key size in order to on-board with BOI.

Certificates Supported for the purposes of identification

ROI

UK

eIDAS QWAC

OBWAC, eIDAS QWAC

Bank of Ireland UK will no longer accept OB Legacy certificates for the purposes of identification from 30th June 2021. If you are onboarded with Bank of Ireland UK with an OB Legacy certificate, you must either re-register with a new client ID (which will invalidate existing consents), or migrate an existing client with OB legacy certificates to OBWAC/eIDAS QWAC certificates using DCR v3.3 PUT functionality. Further details are available on the BOI Transparency Calendar.

Certificate Rotation Process for TPPs:

  • During the process of Certificate rotation, TPPs should procure the new certificates with same subjectDN field value which should match the subjectDN field of the existing certificates used during DCR journey.
  • When the certificate rotation process is completed, TPPā€™s can directly access the APIā€™s with the existing client ID.

Error Scenarios for Certificate Rotation Process for TPPs:

  • Case 1: If the existing certificate expires before renewal:

       The TPP will encounter an SSL error while making a request with BOI until the certificate is renewed. The renewed certificate should contain the same subject DN value.
  • Case 2: If the renewed TPP certificates have a different subject DN than the certificate used during TPP registration:

       The TPP will receive an error stating, "Subject DN configured for the client ID does not match the subject DN of the client certificate in the request."

Note: For BOI UK, there is an option to update the certificate details (if the renewed certificate has a different subject DN) in the registration process. This can be done using the PUT endpoint, but only if the existing certificate used during registration has not already expired.

FAQs

We have compiled common, recurring questions from TPPs on registration in our FAQs. Please review these here before contacting us.

Fallback Solution

If our API Channel (or certain API functionality) is unavailable (for example, due to a systems breakdown), you may avail of a contingency mechanism (also known as a Fallback solution).

Click here for more detail & how to notify us of your intention in the event you need to use the contingency mechanism.

Channels

Bank of Ireland allows customers registered on the following bank channels to provide access to Third Parties. Please click the links below to find more information about the bank channels at Bank of Ireland:

OIDC .well-known endpoint URL

Please refer to the URLs specific to the channels below:

Sandbox URL

https://auth-sandbox.bankofireland.com/oauth/as/b365/.well-known/openid-configuration

Production URLs

Bank of Ireland (ROI)

365 Online:Ā https://auth.ob.bankofireland.com/oauth/as/b365/.well-known/openid-configuration

Business On Line (BOL):Ā https://auth.ob.bankofireland.com/oauth/as/bol/.well-known/openid-configuration

Bank of Ireland UK

365 Online:Ā https://auth.obapi.bankofireland.com/oauth/as/b365/.well-known/openid-configuration

Business On Line (BOL):Ā  https://auth.obapi.bankofireland.com/oauth/as/bol/.well-known/openid-configuration

Bank of Ireland (ROI) and Bank of Ireland UK are separate legal entities on the OBIE Directory, and TPPs will need to on-board separately, even if they have already on boarded for one entity.

Details required to access the respective environments are available with .well-known endpoints [RFC 8414] shared above.

Authorization Flow - Redirection Services/URLs

Sandbox URL

https://auth-sandbox.bankofireland.com/oauth/as/b365/authorization.oauth2

Production URLs

Bank of Ireland (ROI)

365 Online:Ā https://auth.ob.bankofireland.com/oauth/as/b365/authorization.oauth2

Business On Line (BOL):Ā https://auth.ob.bankofireland.com/oauth/as/bol/authorization.oauth2

Bank of Ireland UK

365 Online:Ā https://auth.obapi.bankofireland.com/oauth/as/b365/authorization.oauth2

Business On Line (BOL):Ā https://auth.obapi.bankofireland.com/oauth/as/bol/authorization.oauth2

For the parameters supported by the Bank, please refer to the API specification guides.

Note: The customer screens (login, account selection, File ID/OIN selection etc.) shown in the Sandbox are not the actual screens visible to customers in production. Layout, text and supplementary information are indicative only.

Open Data APIs

Open Data APIs are a category of APIs that offer bank-specific information, such as ATM locations, products, URLs and events. Open Data API support documentation can be found here.

News and Announcements

Keep up to date on API news and announcements here.

Documentation on previous versions

Documentation on previous API versions can be found here.