1. Version Control

2. Overview

The Account and Transaction API Profile describes the flows and common functionalities for the Accounts and Transaction API, which allows an Account Information Service Provider ('AISP') to:

• Register an intent to retrieve account information by creating an "account access consent". This registers the data "permissions" and historical period allowed for transactions/statements - that the user/customer has consented to provide to the AISP

• Subsequently, retrieve account and transaction data

• Retrieve product specific information from ASPSP

2.1 Chapter Overview

This chapter (Account Information Services) consists of the following parts:

Overview: Provides an overview of the profile

Basics: Identifies the flows, release management and permission model

Security & Access Control: Specifies the means for AISPs to authenticate themselves and provide consent

Data Model: Mappings and enumerations that apply to all the end-points

Alternative Flows: Rules for alternative flows

2.2 Resources

Each of the Account and Transaction API resources are documented in the Resources and Data Models / AISP area of the specification. Each resource is documented with:

• Endpoints

  • The API endpoints available for the resource

• Data Model

  • Resource definition

  • UML diagram

  • Permissions as they relate to accessing the resource

  • Data dictionary - which defines fields, re-usable classes, mandatory (1..1) or conditional (0..1)

• Usage Examples

3. Basics

3.1 Overview

The figure below provides a general outline of an account information request and flow using the Account Info APIs.

Open

3.1.1 Steps

Step 1: Request Account Information

• This flow begins with a user/customer consenting to allow an AISP to access account information data

Step 2: Setup Account-Access-Consents

• The AISP connects to the ASPSP that services the user’s/customer’s account(s) and creates an account-access-consents resource. This informs the ASPSP that one of its users/customers is granting access to account and transaction information to an AISP. The ASPSP responds with an identifier for the resource (the ConsentId - which is the intent identifier). This step is carried out by making a POST request to / account-access-consents endpoint

• The account-access-consent sresource will include these fields below - which describe the data that the user/customer has consented with the AISP:

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

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

Step 3: Authorise Consent

• The AISP requests the user/customer to authorise the consent. The ASPSP may carry this out by using a redirection flow or a decoupled flow

  • In a redirection flow, the AISP redirects the user/customer to the ASPSP

    • The redirect includes the ConsentId generated in the previous step

    • This allows the ASPSP to correlate the account-access-consents that was setup

    • The ASPSP authenticates the user/customer

    • The ASPSP updates the state of the account-access-consents resource internally to indicate that the account-access-consents has been authorised

    • Once the consent has been authorised, the user/customer is redirected back to the AISP

  • In a decoupled flow, the ASPSP requests the user/customer to authorise consent on an authentication device that is separate from the consumption device on which the user/customer is interacting with the AISP

    • The decoupled flow is initiated by the AISP calling a back-channel authorisation request

    • The request contains a 'hint' that identifies the user/customer, paired with the consent to be authorised

    • The ASPSP authenticates the user/customer and updates the state of the account-access-consents resource internally to indicate that the account-access-consents has been authorised

    • Once the consent has been authorised, the ASPSP can make a callback to the AISP to provide an access token

• The consent is managed between the user/customer and the AISP - so the account-access-consents details must not be changed (with the ASPSP) in this step. The user/customer will only be able to authorise or reject the account-access-consents details in its entirety

• During authorisation, the user/customer selects accounts that are authorised for the AISP request (in the ASPSP’s banking interface)

Step 4: Request Data

• This is carried out by making a GET request the relevant resource

• The unique AccountId(s) that are valid for the account-access-consents will be returned with a call to GET /accounts. This will always be the first call once an AISP has a valid access token

3.1.2 Sequence Diagram

Open

*CIBA - Client Initiated Backchannel Authentication

3.2 Idempotency

The API endpoints for creating account-access-consents resources are not idempotent.

If a time-out error occurs - then an AISP can create a new account-access-consents resource - rather than try with the same resource.

3.3 Release Management

This section overviews the release management and versioning strategy for the Account and Transaction API.

3.3.1 Account Access Consent

3.3.1.1 POST

• An AISP must not create a Consent on a newer version, and use it on a previous version

  • E.g., A ConsentId for an account-access-consents created in v3, must not be used to access v2 endpoints

3.3.1.2  GET

• An AISP must not access a Consent on an older version, via the Id for a Consent created in a newer version:

  • E.g., An account-access-consents created in v3 accessed via v2 account-request

• An ASPSP must allow a Consent to be accessed in a newer version

• An ASPSP must ensure Permissions set associated with a Consent are unchanged when accessed in a different version:

  • E.g., An account-request created in v2 will have the same details when accessed via v2 and v3 (as an account-access-consents)

• An ASPSP must ensure a Consent's fields are unchanged when accessed in a different version

• An ASPSP may allow expired Consents to be accessed in a newer version

• An ASPSP may choose to populate new fields introduced in a resource from previous version sensible defaults (if mandatory) or not populate at all (if not mandatory):

  • E.g., OBAccountAccessConsentResponse /Data/StatusUpdateDateTime introduced in v2 accessed with v1 AccountRequestId can be populated with Last accessed date time, if not already available in the system of records

3.3.1.3 PATCH

• An AISP must not patch a Consent on an older version, via an Id for a Consent created in a newer version:

  • E.g., An account-access-consents is created in v3, and request PATCH on v2

• An ASPSP must support patching a Consent from a previous version via a newer version:

  • E.g., An account-request is created in v2, and request PATCH on v3

3.3.2 Account Information Resources

3.3.2.1  GET

• An AISP may use a token that is bound to a Consent in a previous version, to access an endpoint of a newer version

• An AISP may use an Id for a Consent created in a previous version to retrieve Account Information resources in a newer version:

  • E.g., AccountRequestId from v2 can be used as ConsentId in v3, to GET /accounts

• An AISP must not use an Id for a Consent from a newer version to access Account Information resources in a previous version:

  • E.g., ConsentId for an account-access-consents created in v3, must not be used to access v2 Account Information endpoints

• An ASPSP must allow an AISP to use an Id for a Consent from a previous version to access Account Information resource endpoints in a newer version:

  • E.g., AccountRequestId created in v2 must be allowed to access Account Information resource endpoints in v3

• An ASPSP must reject the request to access a resource, for which a Consent's Permissions set does not permit

• An ASPSP may choose to populate new fields introduced in a resource from previous version sensible defaults (if mandatory) or not populate at all:

  • E.g., OBAccountAccessConsentResponse /Data/StatusUpdateDateTime introduced in Version2 accessed with V1 AccountRequestId can be populated with Last accessed date time, if not already available in the system of records

4. Security & Access Control

4.1 Scopes

The access tokens required for accessing the Account Info APIs must have the following scope:

accounts: Ability to read Accounts information

4.2 Grants Types

AISPs must use a client credentials grant to obtain a token to access the account-access-consents resource. In the specification, this grant type is referred to as "Client Credentials".

AISPs must use an authorisation code grant using a redirect or decoupled flow to obtain a token to access all other resources. In the specification, this grant type is referred to as "Authorisation Code").

4.3  Consent Authorisation

The AISP must create an account-access-consents resource through a POST operation. This resource indicates the consent that the AISP claims it has been given by the user/customer to retrieve account and transaction information. At this stage, the consent is not yet authorised as the ASPSP has not yet verified this claim with the user/customer.

The ASPSP responds with a ConsentId. This is the intent-id that is used when initiating the authorisation code grant.

As part of the consent authorisation flow:

• The ASPSP authenticates the user/customer

• The ASPSP plays back the consent (registered by the AISP) back to the user/customer - to get consent authorisation. The user/customer may accept or reject the consent in its entirety (but not selectively)

• The ASPSP presents the user/customer with a list of accounts to which the consent will apply

Once these steps are complete, the consent is considered to have been authorised by the user/customer.

4.3.1 Consent Elements

The Account-access-consents resource consists of the following fields, which together form the elements of the consent provided by the user/customer to the AISP:

• Permissions: The set of data clusters that the user/customer has consented to allow the AISP to access

• TransactionFromDateTime: The earliest point of the transaction/statement historical period that the user/customer has consented to provide access to the AISP

• TransactionToDateTime: The last point of the transaction/statement historical period that the user/customer has consented to provide access to the AISP

4.3.1.1  Permissions

Permissions codes will be used to limit the data that is returned in response to a resource request.

When permission is granted for a "Detail" permission code (e.g., ReadAccountsDetail) it implies that access is also granted to the corresponding "Basic" permission code (e.g., ReadAccountsBasic).

While it is duplication for an AISP to request a "Basic" permission code and the corresponding "Detail" permission code, it is not a malformed request, and the ASPSP must not reject solely on the basis of duplication.

The permissions array must contain at least ReadAccountsBasic or ReadAccountsDetail.

The following combinations of permissions are not allowed, and the ASPSP must reject these account-access-consents with a 400 response code:

• Account Access Consents with an empty permissions array

• Account Access Consents with a permission code that is not supported by the ASPSP (APSPSs are expected to publish which API endpoints are supported)

• Account Access Consents with a Permissions array that contains ReadTransactionsBasic but does not contain at least one of ReadTransactionsCredits and ReadTransactionsDebits

• Account Access Consents with a Permissions array that contains ReadTransactionsDetail but does not contain at least one of ReadTransactionsCredits and ReadTransactionsDebits

• Account Access Consents with a Permissions array that contains ReadTransactionsCredits but does not contain at least one of ReadTransactionsBasic and ReadTransactionsDetail

• Account Access Consents with a Permissions array that contains ReadTransactionsDebits but does not contain at least one of ReadTransactionsBasic and ReadTransactionsDetail

4.3.1.1.a  Detail Permissions

The additional elements that are granted for "Detail" permissions are listed in this section.

All other fields (other than these fields listed) are available with the "Basic" Permission access.

In addition the ReadStatementsDetail is required to access the statement file download via: /accounts/{AccountId}/statements/{StatementId}/file.

Example behaviour of the Permissions for the ReadAccountsBasic and ReadAccountsDetail codes is as follows:

4.3.1.1.b  Reversing Entries

It is expected that transactions will be returned in the payload irrespective of whether they are reversing entries, as long as the user/customer has provided consent for that type of transaction.

If the user/customer has provided permission for ReadTransactionsCredits, the ASPSP must include all credits, including debit reversals.

If the user/customer has provided permission for ReadTransactionsDebits, the ASPSP must include all debits, including credit reversals.

4.3.1.2  Transaction To/From Date Time

The TransactionToDateTime and the TransactionFromDateTime specify the period for consented transaction and/or statement history. Both the fields are optional and one may be specified without the other.

The AISP must be restricted to accessing transactions within this period when accessing the transactions resource.

The AISP must be restricted to accessing statements which are completely within this period when accessing the statements resource.

4.3.2 Account Access Consent Status

The Account Access Consent resource may have one of the following status codes after authorisation has taken place:

4.3.3 Consent Re-authentication

Account Access Consents are long-lived consents.

A user/customer can re-authenticate an account-access-consents if:

• The account-access-consent has a status of Authorised 

Where there is no change in the consent parameters required, AISPs should perform a re-authentication / refresh upon the original consent using the same intent-id as before, instead of issuing a new, duplicate consent.

An AISP and the user/customer may have multiple consents at any point in time.

4.4  Consent Revocation

A user/customer may revoke consent for accessing account information at any point in time.

The user/customer may request the AISP to revoke consent that it has authorised. If consent is revoked with the AISP:

• The AISP must cease to access the APIs at that point

• The AISP must call the PATCH operation on the account-access-consents resource (before confirming consent revocation with the user/customer) as soon as is practically possible, to indicate to the ASPSP that the user/customer has revoked consent

4.5  Access Revocation

A user/customer may revoke AISP's access directly with the ASPSP, via the access dashboard. In such a situation:

• The ASPSPs must revoke the access token provided to the AISP

• The status of the account-access-consents must remain unchanged and the AISP must be allowed to request user/customer to re-authenticate the same account-access-consents resource

• Upon successful re-authentication by user/customer, an ASPSP may issue new authorisation code and subsequently new access token to the AISP

4.6 Changes to Selected Account(s)

The user/customer must select the accounts to which the consent should be applied at the point of consent authorisation.

Subsequent changes to the set of accounts to which the consent authorisation applies may be carried out directly with the ASPSP. The method for doing this lies in the competitive space and is not part of this specification.

Additionally, the set of selected accounts may also change due to external factors. This includes (but is not limited to):

• The account being closed

• The account is barred or frozen

• The beneficial owner of the account revokes the user’s/customer's mandate or power of attorney to operate the account

In these scenarios, only the affected account is removed from the list of selected accounts. The ASPSP must not revoke authorisation to other accounts.

5. Data Model

5.1 Using Meta to identify Available Transaction Period

For Accounts & Transaction APIs, the Meta section in API responses may contain two additional fields to indicate the date range for which data has been returned.

The transactions or statements for a particular range of dates may be excluded from the response because:

• The ASPSP does not provide historical transactions/statements for that date range

• The user/customer has not consented to transactions/statements for that date range

The absence of transactions/statements in the payload does not indicate that there were no transactions/statements during that period.

To ensure that the data is interpreted correctly, the ASPSP may provide the date of the first available transaction and last available transaction as part of the response in the Meta section in the FirstAvailableDateTime and LastAvailableDateTime fields.

5.2 Enumerations

5.2.1 Static Enumerations

5.2.2 ISO Enumerations

These following ISO Enumerations are used in the Account APIs.

5.2.3 Namespaced Enumerations

The enumerated values specified by Open Banking are documented in Swagger specification.

6.  Swagger Code

The swagger code file for the Sharing Transaction History/ Account Information and Sharing Product Details APIs can be accessed at this link.

CENTRAL BANK OF BAHRAIN © 2020