Account Information Services APIs

2.0.x
(0 reviews)

Introduction

This API specification provides details of the Account and Transaction API and a set of REST API endpoints for executing the accounts flow for the AISP.

This section describes the overall accounts journey, payloads and API endpoint details for the Account Access Consent setup and retrieval of account and Transaction data of the Account and Transaction API.

Once the Consent setup is created and is authorised by the customer/Payment Service User (PSU), the AISP can invoke the Account and Transaction API to fetch account and transaction information from Bank of Ireland.

Functional Overview

The diagram below depicts the overall journey defined by Open Banking, UK.

An AISP begins the Account Information journey by registering a request to access the account information of a PSU. The AISP must then obtain consent from the PSU in order to authorise the request, enabling it to request the information. Once the request is authorised, the AISP is able to invoke various account and transaction information APIs to retrieve the required data for the PSU’s account(s).

resources/Capture%202-bf59da84-1fbb-48a6-9b36-93bd47385363.PNG

The steps are as follows:

1. Request account information

The PSU requests the AISP to access account information.

2. Setup Client Credentials Token

To set-up an account request, the Access Token must be obtained by an AISP using a Client Credentials grant type within a secure, server side context between the AISP and BOI. The scope accounts must be used. When an Access Token expires, the AISP will need to re-request another Access Token using the same request.

An AISP connects with the API Platform to set up the account access consent request. On successful creation, the AISP receives a Consent ID.

Permissions accepted by Bank of Ireland UK PLC are given below, only permissions from the list below will be honoured by the API. Others outside of this will be rejected

  • ReadAccountsBasic:- Ability to read basic account information
  • ReadAccountsDetail:- Ability to read account identification details
  • ReadBalances:- Ability to read all balance information
  • ReadBeneficiariesBasic:- Ability to read basic beneficiary details
  • ReadBeneficiariesDetail:- Ability to read account identification details for the beneficiary
  • ReadProducts:- Ability to read all product information relating to the account
  • ReadStandingOrdersBasic:- Ability to read basic standing order information
  • ReadStandingOrdersDetail:- Ability to read account identification details for beneficiary of the standing order
  • ReadTransactionsBasic:- Ability to read basic transaction information
  • ReadTransactionsCredits:- Ability to read only credit transactions
  • ReadTransactionsDebits:- Ability to read only debit transactions
  • ReadTransactionsDetail:- Ability to read transaction data elements which may hold silent party details
  • ReadStatementsBasic:- Ability to read basic statement details
  • ReadStatementsDetail:- Ability to read statement data elements which may leak other information about the account
  • ReadScheduledPaymentsBasic:- Ability to read basic scheduled payments details
  • ReadScheduledPaymentsDetail:- Ability to read additional elements about the scheduled payments
  • ReadPAN:- Request to access PAN in the clear across the available endpoints. BOI will return a masked PAN.

The API Platform then prompts the PSU to choose the account(s) to be associated with the consent.

Once the account setup request is successful, the AISP can then request the PSU to authorise the consent with Bank of Ireland.

The AISP will redirect the PSU to the Bank of Ireland API Platform to initiate the consent authorisation flow. The redirect includes the Account Request ID generated in the previous step, which allows the API Platform to correlate the account request to the incoming request.

The Bank of Ireland API Platform requests the PSU to select the relevant channel and then authenticates the PSU. The API platform then prompts the PSU to choose the account(s) to be associated with the consent. Once the PSU has chosen the account(s), the PSU is displayed the consent details agreed with the TPP along with the account(s) chosen for the consent. Based on the PSU’s action, the consent is marked as authorised or rejected on the API Platform.

Once the consent is authorised, the TPP will receive an Auth Code which the AISP can use to get the Access Token and Refresh Token. The Access Token is short lived (5 minutes) and is to be used while accessing the APIs.

For UK AISP, 90 days re-authentication of Refresh Token has been removed and the Refresh Token is long lived. For ROI AISP, 90 days re-authentication of Refresh Token has been updated to 180 days.

These refresh Tokens are used to get a new Access Token Example of the Auth Code(code) sent on the redirect URL can be seen below:

https://{redirect_url}#code=VHAdx9ztWJtR-qd318PZS0xxZ3mY8fQnQIAjMNLc=eyJhbGciOiJSUzI1NiIsImtpZCI6InhsMTZCRHh3NTdKTi0zUHR2cm15QS16V1RnTSJ9.eyJzdWIiOiI0ODMxZTg4NC0zMzk3LTQ3MzQtODkwMS0yYzNkM2RkZWU5ZjkiLCJhdWQiOiJjNTI4OTgyYi01MjQ2LTQ2MzQtODczYi03OWU3NGYxNzk2YWIiLCJqdGkiOiJ6Y1lqV3JPMklIUTUxSjdjUnRmUE1ZIiwiaXNzIjoiaHR0cHM6Ly9hdXRoLXNhbmRib3guYm9pY2xvdWR0ZXN0Lm5ldCIsImlhdCI6MTU0NzIyMDk3MiwiZXhwIjoxNTQ3MjU2OTcyLCJhY3IiOiJ1cm46b3BlbmJhbmtpbmc6cHNkMjpzY2EiLCJvcGVuYmFua2luZ19pbnRlbnRfaWQiOiI0ODMxZTg4NC0zMzk3LTQ3MzQtODkwMS0yYzNkM2RkZWU5ZjkiLCJub25jZSI6Im4tMFM2X1d6QTJNaiIsImF1dGhfdGltZSI6MTU0NzIyMDg2OSwiY19oYXNoIjoieC05Umt1VHp1cjRBRnhoVmZiZ3lXZyIsInNfaGFzaCI6ImJPaHRYOEY3M0lNalNQZVZBcXh5VFEifQ.eQdeiowGPsJNq0M_1qbd5u3duX-u-kkdigdWxLkmYtwhCadWu2qXSzq3O2R-mt0IfPyaSf-fgUoZ-euAH8J1btQYJ9rvOidfVSr25uhSRGUG3Fe4ngrePJ32AeGgcn-6iLozTKm5XVEeGbBlulGMvZN2oSfov2FB-Up-dWp5KPyfIZrpi4ISqtHDKx-fbNuW7GdebRuOY8TQQo_L7yyo72P4941oJONoGzt4EGmVXmmoUmAXeTrK-acwgkWFcX5VodUSxaKwVg-gZiMEF10Owu94BFU8uEEB5BKncjbSzt6GgCxM3rvdYp-1J-jVdhkZajG6uu1xGILkz7NKJrz2Kw=af0ifjsldkj
5. Get Access Token to invoke AISP APIs

For accessing the Accounts APIs, the Access Token must be obtained by the AISP using an Authorization Code grant type within a secure, server side context between the AISP and the ASPSP.

6. Request Data (API Invocation)

Once the TPP has the required Access Token, it can invoke the specific Account Information Request API to get the required details.

AISP APIs currently supported by the Bank can be viewed here.

Before making specific Account Information API calls, the TPP would also need to invoke the GET/accounts API to get the unique Account Id(s) that are valid for the account-access-consents request.

For more details on Open Banking initiative's and API specifications: https://www.openbanking.org.uk

Examples

This section provides examples to execute the account and transaction using the AISP APIs as defined by Open Banking UK.

Prerequisite for API invocation

  • For the API endpoints we are using Open Banking Directory Sandbox certificates. You need to trust Open Banking Directory Sandbox certificates while calling our APIs.
1. Setup Client Credentials Token

POST request: client credentials grant type token endpoint

curl -k -X POST \
--key ./{Transport.key} \
--cert ./{Transport.pem} \
 https://api-sandbox.bankofireland.com/oauth/as/token.oauth2 \
-H 'accept: application/json' \
-H 'cache-control: no-cache' \
-H 'content-type: application/x-www-form-urlencoded' \
-d 'grant_type=client_credentials=accounts=1OEwYAKIgMtefvOKfSEdAS'

Request parameters:

Parameter Example value Description
grant_type client_credentials The grant type being requested.
client_id 1OEwYAKIgMtefvOKfSEdAS The client ID of the application registered through DCR.
scope accounts Ability to read Accounts information

Response: Client Credentials

{
    "access_token": "WcqgqCU9CaovjLQDgjopFbvpNnEO",
    "token_type": "Bearer",
    "expires_in": 299
}

This is the first API that an AISP invokes in order to set up an Account request. This resource is a copy of the consent that a PSU authorises in order for the AISP to access information on the PSU’s accounts.

POST: account-access-consents

POST /account-access-consents HTTP/1.1

curl -X POST \
curl -X POST \
  https://api-sandbox.bankofireland.com/1/api/open-banking/v3.1.8/aisp/account-access-consents
  -H 'Authorization: Bearer WcqgqCU9CaovjLQDgjopFbvpNnEO' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
  "Data": {
     "Permissions": [
        "ReadAccountsBasic",
        "ReadAccountsDetail",
        "ReadBalances",
        "ReadBeneficiariesBasic",
        "ReadBeneficiariesDetail",
        "ReadProducts",
        "ReadScheduledPaymentsBasic",
        "ReadScheduledPaymentsDetail",
        "ReadStandingOrdersBasic",
        "ReadStandingOrdersDetail",
        "ReadStatementsBasic",
        "ReadStatementsDetail",
        "ReadTransactionsBasic",
        "ReadTransactionsCredits",
        "ReadTransactionsDebits",
        "ReadTransactionsDetail"
       ],
      "ExpirationDateTime":"2021-01-19T00:00:00+05:30",
      "TransactionFromDateTime":"2014-01-19T00:00:00+05:30",
      "TransactionToDateTime":"2019-01-19T00:00:00+05:30"
 },
  "Risk": {}
}'

Request parameters:

Parameter Example value Description
authorization Bearer WcqgqCU9CaovjLQDgjopFbvpNnEO Standard HTTP Header, The access token obtained in Step 1 (CCG).
data { "Data": { "Permissions": [ "ReadAccountsBasic", "ReadAccountsDetail", "ReadBalances", "ReadBeneficiariesBasic", "ReadBeneficiariesDetail", "ReadProducts", "ReadScheduledPaymentsBasic", "ReadScheduledPaymentsDetail", "ReadStandingOrdersBasic", "ReadStandingOrdersDetail", "ReadStatementsBasic", "ReadStatementsDetail", "ReadTransactionsBasic", "ReadTransactionsCredits", "ReadTransactionsDebits", "ReadTransactionsDetail" ], "ExpirationDateTime": "2019-03-08T05:55:00+00:00", "TransactionFromDateTime": "2011-05-03T00:00:00+05:30", "TransactionToDateTime": "2017-05-03T00:00:00+05:30" }, "Risk": {} } The permissions being requested.

POST response: account access consents

HTTP/1.1 201 Created
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json

{
    "Data": {
        "ConsentId": "200705fd-68b0-41d9-b12e-e016b643bc3c",
        "CreationDateTime": "2019-02-04T09:48:44+00:00",
        "Status": "AwaitingAuthorisation",
        "StatusUpdateDateTime": "2019-02-04T09:48:44+00:00",
        "Permissions": [
            "ReadAccountsBasic",
            "ReadAccountsDetail",
            "ReadBalances",
            "ReadBeneficiariesBasic",
            "ReadBeneficiariesDetail",
            "ReadProducts",
            "ReadScheduledPaymentsBasic",
            "ReadScheduledPaymentsDetail",
            "ReadStandingOrdersBasic",
            "ReadStandingOrdersDetail",
            "ReadStatementsBasic",
            "ReadStatementsDetail",
            "ReadTransactionsBasic",
            "ReadTransactionsCredits",
            "ReadTransactionsDebits",
            "ReadTransactionsDetail"
        ],
        "ExpirationDateTime": "2021-01-19T00:00:00+05:30",
        "TransactionFromDateTime": "2014-01-19T00:00:00+05:30",
        "TransactionToDateTime": "2019-01-19T00:00:00+05:30"
    },
    "Risk": {},
    "Links": {
        "Self": "https://api-sandbox.bankofireland.com/1/api/open-banking/v3.1.8/aisp/account-access-consents/200705fd-68b0-41d9-b12e-e016b643bc3c"
    },
    "Meta": {
        "TotalPages": 1
    }
}

The AISP receives an AccountRequestId from the ASPSP. The AISP then creates an authorization request (using a signed JWT request containing the AccountRequestId as a claim) for the PSU to consent to the account request directly with their ASPSP. The request is an OIDC Hybrid Flow (requesting for a code and ID token).

Invoke the below url from your web browser.

https://auth-sandbox.bankofireland.com/oauth/as/b365/authorization.oauth2?client_id=1OEwYAKIgMtefvOKfSEdAS=code id_token=openid accounts=af0ifjsldkj=n-0S6_WzA2Mj=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjZwSXp3bDBILWF6X2g5Y0VPejQ4UXdfT0tuOCJ9.eyJpc3MiOiIxT0V3WUFLSWdNdGVmdk9LZlNFZEFTIiwiYXVkIjoiaHR0cHM6Ly9hdXRoLXNhbmRib3guYXBpYm9pdGVzdC5jb20iLCJyZXNwb25zZV90eXBlIjoiY29kZSBpZF90b2tlbiIsImNsaWVudF9pZCI6IjFPRXdZQUtJZ010ZWZ2T0tmU0VkQVMiLCJyZWRpcmVjdF91cmkiOiJodHRwczovL3d3dy5nZXRwb3N0bWFuLmNvbS9vYXV0aDIvY2FsbGJhY2siLCJzY29wZSI6Im9wZW5pZCBhY2NvdW50cyIsInN0YXRlIjoiYWYwaWZqc2xka2oiLCJub25jZSI6Im4tMFM2X1d6QTJNaiIsIm1heF9hZ2UiOjg2NDAwLCJjbGFpbXMiOnsiaWRfdG9rZW4iOnsib3BlbmJhbmtpbmdfaW50ZW50X2lkIjp7InZhbHVlIjoiMjAwNzA1ZmQtNjhiMC00MWQ5LWIxMmUtZTAxNmI2NDNiYzNjIiwiZXNzZW50aWFsICI6dHJ1ZX19fX0.H910Gqr6lVgUOt-v_pXh6qOhd7I2zgV9Upbu4oYQpKwq4LbnQ2oNw7eDWQAW6i_OYU75NK00q6WyxjRap7rUUZz7jrC1dAl5JlG-JMyIqg6iOtqdkxO7El_DIaSf1cdFaY4Eito4JU1VUofpcNvfX7x6Ni1Vmns4PWfG2m26xbcXatnXnZusPCBFub2GCTiS2b3HZP9cDTkwJDp_JndLxyphox3NU4D-avMKzbKw9xveoC0oWgZbtyXcSMipJoPX_Fc1eYAGoDNOkvqz6fm-pYzdJkgyQklsst9PF8JkMmH9SGkJXbTzoTn7pETt81F-D5DEZZamsbFKA1nBqvz_Aw=https://www.getpostman.com/oauth2/callback

URL parameters:

Parameter Example value Description
response_type id_tokenid The OAuth flow type
client_id 1OEwYAKIgMtefvOKfSEdAS The client ID of the application registered in the TPP portal
state af0ifjsldkj The state as specified by the TPP
scope openid accounts The scope being requested.
redirect_uri https://www.getpostman.com/oauth2/callback The redirect URL of the application registered in the TPP portal
nonce n-0S6_WzA2Mj The nonce as specified by the TPP
request payload { "iss": "1OEwYAKIgMtefvOKfSEdAS", "aud": "https://auth-sandbox.bankofireland.com", "response_type": "code id_token", "client_id": "1OEwYAKIgMtefvOKfSEdAS", "redirect_uri": "https://www.getpostman.com/oauth2/callback", "scope": "openid accounts", "state": "af0ifjsldkj", "nonce": "n-0S6_WzA2Mj", "max_age": 86400, "claims": { "id_token": { "openbanking_intent_id": { "value": "200705fd-68b0-41d9-b12e-e016b643bc3c", "essential ": true } } } } Refer to sample JWT payload structure provided in example value column and create a signed jwt. For KID and signing private key details refer to test data file available in Developer Portal. Parameters of payload are:
  • "iss" is issuer of the token i.e. same as clientid.
  • "aud" is audience that the ID token intended and it should be the same as issuer value from /.well-known endpoint configuration URL.
  • "redirect_uri" is any valid https URL.
  • "value" is ConsentId (in response of Step 2).

For more details on request object creation follow below link:
https://openbanking.atlassian.net/wiki/spaces/DZ/pages/83919096/Open+Banking+Security+Profile+-+Implementer+s+Draft+v1.1.2

4. Get Access Token to invoke APIs

AISPs must use an authorization code grant to obtain a token to access all other resources.

POST request: get access token endpoint

curl -X POST \
--key transport.key \
--cert transport.cer \
--url https://api-sandbox.bankofireland.com/oauth/as/token.oauth2 \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data 'grant_type=authorization_code=mXkFTakb6fadgbbe0YmmFUeHil4VjgeayzMSuPXF=https://www.getpostman.com/oauth2/callback=1OEwYAKIgMtefvOKfSEdAS'

Request Parameters:

Parameter Example value Description
grant_type authorization_code The grant type being requested.
redirect_uri https://www.getpostman.com/oauth2/callback The redirect URL must be the same as the redirect url of the application registered in the TPP portal.
code mXkFTakb6fadgbbe0YmmFUeHil4VjgeayzMSuPXF The authorization code obtained in step 3 (Consent Autorization).

Response: Access Token

{
    "access_token": "1UqG12JG2uiIBDYy8VTxiyQvfVJ9",
    "refresh_token": "m1iovPbveSrXVDve6xfwybjlrZvw2pqVeDPbH35Sf8",
    "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6InhsMTZCRHh3NTdKTi0zUHR2cm15QS16V1RnTSJ9.eyJzdWIiOiIyMDA3MDVmZC02OGIwLTQxZDktYjEyZS1lMDE2YjY0M2JjM2MiLCJhY3IiOiJ1cm46b3BlbmJhbmtpbmc6cHNkMjpzY2EiLCJvcGVuYmFua2luZ19pbnRlbnRfaWQiOiIyMDA3MDVmZC02OGIwLTQxZDktYjEyZS1lMDE2YjY0M2JjM2MiLCJhdWQiOiIxT0V3WUFLSWdNdGVmdk9LZlNFZEFTIiwianRpIjoiWldGaXM3MktEWFYydnRvNjRmYmxkciIsImlzcyI6Imh0dHBzOlwvXC9hdXRoLXNhbmRib3guYXBpYm9pdGVzdC5jb20iLCJpYXQiOjE1NDkyNzQ5MTgsImV4cCI6MTU0OTMxMDkxOCwibm9uY2UiOiJuLTBTNl9XekEyTWoiLCJhdXRoX3RpbWUiOjE1NDkyNzQyMTUsImNfaGFzaCI6ImhSRUNGYUdJUjZ0WkxHZ1VSektRYmciLCJzX2hhc2giOiJiT2h0WDhGNzNJTWpTUGVWQXF4eVRRIn0.nEJKPIP6-jTbI_x7uT-YJpNSEpMdUsGBcx4tbgEixUnZoS99tcW8I-nf306QwBN0sjudLOaem7tfxRDbN9KL204ALl5SHhJUwSe1wG9M2BqBAN-aEqoMneVei7STFPg1EUr0aEw02Di0H_KjbrCH4hyBjAwYcpYG51WYBF2mz3YN-c4vIzJL35HuCdCRgqdz73blllcEwCxPRZEoI7DwvcoO7X1mmoL8a5LRdAcxPAh8yANut69aJOPntmitYDycGANTYTAbwKL6OvwAYrMW-ekD-U-t1-bz6jWCYZmHUFIeQbMrFfBur6WIi-4R74jj6HpnAZPRID4rN4awjif30Q",
    "token_type": "Bearer",
    "expires_in": 299
}
5. Account and Transaction Information API Invocation

Once the TPP has the required Access Token, it can invoke the specific Account Information request API to get the required details.

Account information service providers shall be able to access information from designated payment accounts and associated payment transactions held by BOI for the purposes of performing the account information service in either of the following circumstances:

  • whenever the payment service user is actively requesting such information i.e. when x-fapi-customer-ip-address is passed in the request headers
  • whenever the payment service user does not actively request such information, no more than four times in a 24-hour period

Examples of the different account details endpoints can be viewed here.

6. Retrieve Account Access Consents resource

This API allows an AISP to retrieve the Account Setup request resource with status information.

GET account-access-consents

GET /account-access-consents/200705fd-68b0-41d9-b12e-e016b643bc3c HTTP/1.1

curl -X GET \
--url https://api-sandbox.bankofireland.com/1/api/open-banking/v3.1.8/aisp/account-access-consents/200705fd-68b0-41d9-b12e-e016b643bc3c \
-H 'Authorization: Bearer WcqgqCU9CaovjLQDgjopFbvpNnEO' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \

Header parameters:

Parameter Example value Description
authorization Bearer WcqgqCU9CaovjLQDgjopFbvpNnEO The token obtained in step 1(Get client credentials token).

GET account-access-consents response

HTTP/1.1 200 OK
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
x-jws-signature: V2hhdCB3ZSBnb3QgaGVyZQ0K..aXMgZmFpbHVyZSB0byBjb21tdW5pY2F0ZQ0K
x-fapi-auth-date: Sun, 10 Sep 2017 19:43:31 UTC
x-fapi-customer-ip-address: 234.213.211.123
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json

{
    "Data": {
        "ConsentId": "200705fd-68b0-41d9-b12e-e016b643bc3c",
        "CreationDateTime": "2019-02-04T09:48:44+00:00",
        "Status": "Authorised",
        "StatusUpdateDateTime": "2019-02-04T09:58:00+00:00",
        "Permissions": [
            "ReadAccountsBasic",
            "ReadAccountsDetail",
            "ReadBalances",
            "ReadBeneficiariesBasic",
            "ReadBeneficiariesDetail",
            "ReadProducts",
            "ReadScheduledPaymentsBasic",
            "ReadScheduledPaymentsDetail",
            "ReadStandingOrdersBasic",
            "ReadStandingOrdersDetail",
            "ReadStatementsBasic",
            "ReadStatementsDetail",
            "ReadTransactionsBasic",
            "ReadTransactionsCredits",
            "ReadTransactionsDebits",
            "ReadTransactionsDetail"
        ],
        "ExpirationDateTime": "2021-01-19T00:00:00+05:30",
        "TransactionFromDateTime": "2014-01-19T00:00:00+05:30",
        "TransactionToDateTime": "2019-01-19T00:00:00+05:30"
    },
    "Risk": {},
    "Links": {
        "Self": "https://api-sandbox.bankofireland.com/1/api/open-banking/v3.1.8/aisp/account-access-consents/200705fd-68b0-41d9-b12e-e016b643bc3c"
    },
    "Meta": {
        "TotalPages": 1
    }
}
7. Delete Account Access Consents resource

This API allows an AISP to revoke the PSU’s consent.

DELETE account-access-consents resource

DELETE /account-access-consents/200705fd-68b0-41d9-b12e-e016b643bc3c HTTP/1.1

Authorization: Bearer WcqgqCU9CaovjLQDgjopFbvpNnEO
x-fapi-auth-date: Sun, 10 Sep 2017 19:43:31 UTC
x-fapi-customer-ip-address: 234.213.211.123
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Accept: application/json

Header parameters:

Parameter Example value Description
authorization Bearer WcqgqCU9CaovjLQDgjopFbvpNnEO The token obtained in step 1(Get client credentials token).

DELETE account-access-consents response

HTTP/1.1 204 No Content

x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Versioning

This API specification conforms to the Open Banking UK Account and Transaction API Specification – v3.1.8

Reviews