1. API Flows

1.1 Step 1: Agree Account Access Consent

The flow MUST begin with a User who provides consent to a TPP to access their account information from a LFI that they already have a relationship.

1.2 Step 2: Authorize Account Access Consent

The TPP MUST now request the User to authorize the consent. Please refer to the Authentication and Authorization page to review the supported Authorization Flows.

The TPP MUST construct a Rich Authorization Request (RFC 9396: OAuth 2.0 Rich Authorization Requests) with the authorization_details populated with the User’s consent

The TPP MUST include in an account access consent, all REQUIRED data permissions that the User intends to provide to the TPP

The TPP MUST include a UUID v4 as the ConsentId as a unique identifier for the account access consent

A TPP MAY be a broker for data to other parties, so it is valid for a User to have multiple consents for the same resource(s), with different consent or authorization parameters agreed upon.

1.2.1 Security and Access Control

Authorization Code Grant

The TPP MUST use an authorization code grant to obtain a token to access all other API resources.

1.3 Step 3: Access Data

1.3.1 Request Data

The TPP MUST have a valid access token (with scope) from the OFP authorization server.

The TPP MUST use the valid access token to retrieve User data from the OFP resource server.

The LFI MUST return an API response when provided with a valid request from the OFP.

The OFP MUST return an API response when provided with a valid access token request from the TPP.

2. Sequence Diagram

All sequence diagrams relating to Bank Data Sharing are now available in the API Hub Documentation.

3. Examples

The following are non-normative examples of API access and usage of the Account Information API.

3.1 The TPP Redirects the User to Authorize Account Access Consent

3.1.1 Request: TPP Uses RAR (Rich Authorization Request) via a PAR (Pushed Authorization Request) Endpoint with the OFP to Obtain a Request URI

Create a RAR Request JWT with these values:

• kid is a valid signing key ID for the TPP on the Open Finance Directory

• iss is client id (UUID v4)

• state is a UUID v4 value

• response_type MUST be code

• redirect_uri is the TPP’s redirect URI

The authorization_details contain the User’s account access consent details, and a UUID v4 which is a unique identifier for the account access consent.

Create the RAR Request using the signed JWT, and authenticated using private_key_jwt.

The request parameter JWT includes the ConsentId, a UUID v4 that was originally generated by the TPP.

3.1.2 Response: The OFP Provides the Request URI for the TPP

3.2 The TPP Redirects the User to Their LFI with the Request URI to Authorize the Consent

3.3 The User Logs into Their LFI, Reviews and Authorizes the Consent Request, and Confirms the Accounts They Want to Share with the TPP

The LFI confirms account access consent in the OFP.

3.4 The LFI Returns an Authorization Code to the TPP

3.5 The TPP Exchanges the Authorization Code for an Account API Access Token with the OFP

3.6 The OFP Returns an Access Token, Refresh Token, and ID Token to the TPP

The TPP can now request account resources using the access token.

3.7 Get a List of Accounts

3.7.1 Request: Accounts Resource

3.7.2 Response: Accounts Resource

3.8 Get Balances for an Account

3.8.1 Request: accounts/{AccountId}/balances resource

3.8.2 Response: accounts/{AccountId}/balances resource

3.9 Get Transactions for an Account

3.9.1 Request: accounts/{AccountId}/transactions resource

3.9.2 Response: accounts/{AccountId}/transactions resource

4. Further Examples

4.1 The TPP Queries the Account Access Consent Resource for the Status after a User has Authorized the Consent

4.1.1 Request: account-access-consents/{ConsentId} resource

4.1.2 Response: account-access-consents/{ConsentId} resource

4.2 The TPP Requests a List of Accounts Using an Expired Access Token

4.2.1 Request: accounts resource

4.2.2 Response: 403 Forbidden

4.3 Webhooks

4.3.1 The TPP Creates an Account Access Consent Request with a Webhook Subscription

4.3.1.1 Request: Account Access Consent and Webhook Subscription

4.3.2 The TPP updates a Webhook Subscription preference with the OFP

4.3.2.1 Request: Activate Webhook events

4.3.2.2 Response: Webhook events activated

4.3.3 The TPP unsubscribes their Webhook Subscription with the OFP

4.3.3.1 Request: De-Activate Webhook events

4.3.3.2 Response: Webhook events de-activated

4.3.4 The TPP receives data from the OFP (specific to the consent and permissions) via its Webhook

4.3.4.1 The OFP generates a Self Signed JWT Authorization Token for Client Authentication with the TPP.

This JWT Authorization Token MUST be set in the Authorization Header.

4.3.4.2 Request: OFP publishes signed/encrypted data to the registered Webhook Url provided by the TPP

The example below shows a signed and encrypted payload with the JWT Authorization Token set in the Authorization Header.

Here, <<jwe>> is a signed and encrypted payload. The inner JWS has the structure below:

4.3.4.3 Response: TPP validates the Self Signed JWT Authorization Token from LFI, stores data, and acknowledges a successful response to the OFP

4.3.5 Webhook Payload for a single resource collection associated with a single event type

The following non-normative example illustrates a OFP webhook payload for a collection of account ID transactions of the same event type: Resource.Created

5. OpenAPI Specification

See the Bank Data API - Swagger page

Bank Data OpenAPI

6. Notes

• IBAN

  • Where Data.Account.AccountIdentifiers[].SchemeName is IBAN, the Identification field SHOULD contain the full IBAN

• Passport, Driving Permit, IDCard, Residence Permit

  • Where Data.Party.VerifiedClaims.[].Verification.Evidence[DocumentDetails.Type] is set to any one of these enumerated values, then the DocumentNumber field SHOULD contain the actual number of the document type specified.

• ProprietaryBankTransactionCodes

  • This code is mandatory when the BenefeciaryCode with code specifying the Domain, Family, and SubFamily as per External Codes ISO20022 is absent. This code is a proprietary code from the LFI and does not have a defined code list.

7. Security

A accounts scope is used for accessing the account information endpoints.