Account and Transaction API for UK

This document explains the flow of the Account Information and Transaction API by OBIE. The Account Information Service Provider (AISP) can use the API endpoints described here to do the following.

• Register a resource to retrieve account information by creating an account access consent. This registers data that the customer (PSU) has consented to provide to the AISP such as data permissions, expiration and historical period allowed for transactions/statements
• Subsequently, retrieve account and transaction data
  
  

Basic flow

See the below diagram describing the basic accounts information flow:

The PSU requests to access account information data using an AISP solution (A third-party provider). The AISP connects to the ASPSP that services the PSU's accounts and creates an account-access-consent resource. This informs the ASPSP that one of its PSUs is granting access to account and transaction information to an AISP. In this case, the AISP makes a POST request to ASPSP's /account-access-consents endpoint. The ASPSP responds with an identifier for the resource (the ConsentId). The account-access-consent resource will include the following fields which describe the data that the PSU has consented with the AISP:

• Permissions - a list of data clusters that have been consented for access

• Expiration Date - an optional expiration for when the AISP will no longer have access to the PSU's data

• Transaction Validity Period - the From/To date range which specifies a historical period for transactions and statements which may be accessed by the AISP

The AISP acts as a mediator for data to other parties, so it is valid for a PSU to have multiple account-access-consents for the same accounts, with different consent/authorisation parameters agreed. The AISP requests the PSU to authorise the consent. The ASPSP uses the redirection flow for this.

1. In a redirection flow, the AISP redirects the PSU to the ASPSP

2. The redirect includes the ConsentId generated in the previous step

3. This allows the ASPSP to correlate the account-access-consent that was setup

4. The ASPSP authenticates the PSU

5. The ASPSP updates the state of the account-access-consent resource internally to indicate that the account access consent has been authorised

6. Once the consent has been authorised, the PSU is redirected back to the AISP

Once the PSU authorises the consent for the TPP to access account information, the AISP makes an API call to the ASPSP to retrieve account information. When the ASPSP provides account information, the TPP can expose the information via the AISP solution.

Account Information Service in WSO2 Open Banking

The account information service flow includes 3 steps:

1. Account-access-consent initiation

Generate application access token

• The AISP requests the ASPSP for an application access token. This call targets the Gateway in API Management module.
• There, the APIM Gateway validates the AISP’s certificates using Mutual TLS authentication and forward the request to the IAM module.
• The OAuth2 Framework in the IAM module performs further validation and provides the AISP with an application access token in the Client Credentials grant type.

Initiate account-access consent

• The AISP communicates with the ASPSP using the Confirmation of Funds API Specification API available in the WSO2 Open Banking solution.
• AISP sends an account initiation request to ASPSP with the purpose of retrieving account information of a particular PSU. This request contains the application access token generated in the previous step. 
• This request targets the WSO2 API Management module in the WSO2 Open Banking solution. 
• The Request Schema Validation Handler inside the API Management module then validates the request against the respective(Account) Swagger file. For example, mandatory header, payload fields, pattern matching for fields.
• The back end call of the initiation request is redirected to the WSO2 Identity and Access Management module in the solution where a unique UUID for the consent (Consent Id) is generated.

2.Account-access-consent authorisation 

• AISP sends the authorisation request and this will be captured from the Authorisation endpoint in the API Management module.
• The request details are then passed to the IAM module. 
• The Request Object Validator in WSO2 OB IAM - Identity Framework validates the request object and its claims, and share the validation results.
• These details are stored in cache against a session data key. 
• The session data key is shared with the AISP in an authentication endpoint URL. 
• The AISP needs to redirect the PSU to this URL.
• The PSU uses authentication URL to log in to the authentication endpoint.
• Based on the authenticators that the ASPSP has configured (basic authentication or two-factor authentication), the PSU needs to provide the relevant values. Upon successful authentication, the PSU is redirected to the Consent Management page.
• When the Shareable Accounts API is invoked a list of bank accounts that belong to the PSU is retrieved. This list is displayed in the Consent Management page mentioned above. 
• Now the PSU selects the account(s) and authorise the consent.
• The Consent Management module updates the consent details and persists them in a database.
• The Authentication endpoint invokes the Response Type Handler inside the IAM module and it stores a custom scope against the access token with the Consent Id. This newly added scope provides necessary permissions to retrieve account information.
• Then the IAM module generates the authorization code and shares it with the AISP through the redirect URL. 

3. Retrieve account information

Generate user access token

• The AISP requests for a user access token using the generated authorisation code. This call targets the Gateway in API Management module.
• There, the APIM Gateway validates the AISP’s certificates using Mutual TLS authentication and forward the request to the IAM module.
• The OAuth2 Framework in the IAM module performs further validation and provides the AISP with the user access token.

Retrieve account information

• The AISP makes another API call to the published Accounts and Transaction API in the WSO2 API store to retrieve account information using the access token obtained from the step above.  
• The APIM Gateway module then validates the AISP’s certificates and the access token. The Consent Enforcement Handler in the API Management module validates the incoming request against the saved consent details. The Consent Enforcement Handler performs the following:
• When a retrieval request is made, this handler validates the Consent Id by calling Consent Validation module and checks if the access token associated with the request contains a scope with the Consent Id.
• This handler compares and validates the x-fapi-financial-id header in the incoming request against the one configured in the solution (open-banking.xml file).
• Then the request is forwarded to the IAM module for consent validation. The Consent Validation module inside IAM validates the following:
• Status of the consent is Authorised.
• Consent is valid/not expired.
• Permissions granted for the respective Consent Id and if they match with the accessing API resource. 
• Published API version against the requested API version, as the specification allows cross-version accessing.
• The Consent Management module validates the Consent Id in the request against the databases. 
• After successful validations, the Consent Validation module sends consent related information in a header as mentioned in Integrating with the Core Banking System for UK - Accounts API. 
• Then the bank backend is queried to retrieve account information and the response is shared with the AISP.

Endpoints

To access account information and transaction data, you can use the following available API endpoints: