Account and Transaction API

This API includes the account information and transaction API flows and payloads. The Account Information Service Provider (AISP) can use the endpoints described below to do the following:

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

Basic flow

The diagram below shows the basic flow of a request for account information using the account information API.

1. Request account information - The PSU consents to allow an AISP to access account information data.
2. Setup account request - The AISP creates an account-request resource by connecting to the ASPSP that services the PSU's account(s). The ASPSP gets alerted that a PSU has granted access to account and transaction information to an AISP. The ASPSP responds with an identifier for the resource (the AccountRequestId, which is the intent identifier). 
   1. A POST request is sent to the /account-requests endpoint.
   2. The setup payload includes the following fields that the PSU consents to share with the AISP:
      1. Permissions - a list of data clusters that have been consented for access
      2. Expiration Date - an optional expiration for when the AISP will no longer have access to the PSU's data
      3. Transaction Validity Period - the From/To date range that specifies a transaction history period, which can be accessed by the AISP
   3. An AISP may be a broker for data to other 4th parties, and so it is valid for a customer to have multiple account-requests for the same accounts, with different consent/authorisation parameters agreed. 
3. Authorise consent - The AISP redirects the PSU to the ASPSP. The redirect includes the AccountRequestId generated in the previous step. This allows the ASPSP to correlate the account-request that was setup. The ASPSP authenticates the PSU. The ASPSP updates the state of the account-request resource internally to indicate that the account request has been authorised. It is agreed that the consent is managed between the PSU and the AISP, so the account-request details cannot be changed (with the ASPSP) in this step. The PSU will only be able to authorise or reject the account-request details in its entirety. During authorisation, the PSU selects accounts that are authorised for the AISP request (in the ASPSP's banking interface). The PSU is redirected back to the AISP.
4. Request data - A GET request is sent to the relevant resource. The unique AccountId(s) that are valid for the account-request are returned with a call to GET /accounts. This will always be the first call once an AISP has a valid access token.

Sequence diagram

Endpoints

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

Security and access control

API scopes

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

accounts

Grants types

AISPs must use a client credentials grant to obtain a token to access the account-requests resource.

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

Consent authorisation

OAuth 2.0 scopes are coarse-grained and the set of available scopes are defined at the point of client registration. There is no standard method for specifying and enforcing fine-grained scopes (e.g. a scope to specify that account information should only be provided for certain time periods). 

A consent authorisation is used to define the fine-grained scope that is granted by the PSU to the AISP.

The AISP must create an account-request resource through a POST operation. This resource indicates the consent that the AISP claims it has been given by the PSU 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 PSU.

The ASPSP responds with an AccountRequestId. This is the intent-id that is used when initiating the authorization code grant.

As part of the authorization code grant:

• The ASPSP authenticates the PSU.
• The ASPSP plays back the consent (registered by the AISP) back to the PSU to get consent authorisation. The PSU may accept or reject the consent in its entirety (but not selectively).
• The ASPSP presents the PSU 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 PSU.

Consent elements

The Account Request resource consists of the following fields that together form the elements of the consent provided by the PSU to the AISP:

• Permissions: The set of data clusters that the PSU has consented to allow the AISP to access
• ExpirationDateTime: The date-time up to which the consent is valid.
• TransactionFromDateTime: The earliest booking date of transactions that the PSU has consented to provide access to the AISP.
• TransactionToDateTime: The last booking date of transactions that the PSU has consented to provide access to the AISP.

Consent revocation

A PSU can revoke consent for accessing account information at any point in time.

The PSU can revoke authorisation directly with the ASPSP. The mechanisms for this are in the competitive space and are up to each ASPSP to implement in the ASPSP's banking interface. ASPSPs are under no obligation to notify AISPs regarding the revocation of authorisation in v1.0.

The PSU can 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 (otherwise it may be in breach of GDPR).
• The AISP should call the DELETE operation on the account-request resource to indicate to the ASPSP that the PSU has revoked consent.

Changes to selected account(s)

The PSU can 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 can 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 not limited to):

• The account being closed.
• The PSU's mandate to operate the account is revoked.
• The account is barred or frozen.

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