Version Control

Overview

This specification describes the Account Information API flows and payloads.

The API endpoints described here allow an API Provider to:

• Register an intent to retrieve account information by creating an account-access-consent. This registers the data "permissions" that the Customer has consented to provide to the Third Party; and 

• Subsequently, retrieve account information data.

This specification should be read in conjunction with NZ Banking Data API Specification which provides a description of the elements that are common across all the NZ Banking Data APIs.

Document Structure

This document consists of the following parts:

• Overview: Provides an overview of the scope of the API and the key decisions that contributed to the specification.

• Basics: The section identifies the resources, operations that are permitted on those resources, and various special cases.

• Endpoints: Provides the list of endpoints for the API specification. The individual endpoints are documented in separate sections along with the data model that they employ.

• Security & Access Control: Specifies the means for Third Parties and Customers to authenticate themselves and provide consent.

• Data Model: Describes the data model for the API payloads.

• Usage Examples: Examples for normal flows, and alternate flows.

• Swagger Specifications: Provides links to the swagger specifications for the APIs.

Scope

The Account Information API provides the ability for Third Parties to access a Customer's account information for NZ bank accounts. This version of the API specification allows a Third Party to access NZ BECS identifiable accounts and credit card accounts:

• If a Customer has access to these accounts in their online banking, then these accounts must be made available for access via the Account Information API.

• An API Provider must define and publish what account types are available for access via the Account Information API in their developer portal.

The minimum API Provider NZ BECS identifiable and credit card account product types (covering both business and personal accounts) that are in scope of the Account Information API are:

• Transactional accounts. This includes accounts that are sometimes are referred to as: current accounts; cheque accounts; debit card accounts; personal accounts; business accounts; call accounts; etc.

• Credit card accounts

• Savings accounts

• Lending accounts. This includes accounts that are sometimes referred to as: personal loan accounts, fixed rate home loan accounts, floating home loan accounts; floating home loan accounts; business loan accounts; or mortgage offset transactional accounts; etc.

Out of Scope

This specification does not cater for:

• Write operations (the ability to create) standing orders, direct debits and beneficiaries.

• Progressive or changing consent - if the consent between the Third Party and Customer changes, then the existing account-access-consent object is deleted and a new account-access-consent is created with the new consent.

• The ability for a Third Party to pre-specify the list of accounts that are linked with the account-access-consent.

• Access that requires multiple authorisers.

• Non-functional requirements and specification of caching and throttling.

Basics

Overview

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

Overview Diagram

Open

Steps

Step 1: Agree Account Access Consent

• This flow begins with a Customer consenting to allow a Third Party to access their account information data. 

Step 2: Create Account Access Consent

• The Third Party connects to the API Provider that services the Customer's account(s) and creates an account-access-consent.

• The account-access-consent is a long lived consent.

• This informs the API Provider that one of its Customers intends to grant account information access to a Third Party.

• The API Provider responds with an identifier for the account-access-consent (the ConsentId).

• This step is carried out by making a POST request to the account-access-consent endpoint.

• The Third Party may be a broker for data to other 4th parties, and so it is valid for a Customer to have multiple account-access-consents for the same accounts, with different consent parameters agreed.

Step 3: Authorise Consent

• The Third Party initiates the authorisation flow for the Customer to authorise the consent.

• The Third Party chooses either the redirection flow or a decoupled flow to authorise the Customer.

  • In a redirection flow:

    • The Third Party redirects the Customer to the API Provider.

    • The redirect includes the ConsentId (generated in Step 2).

    • This allows the API Provider to correlate the account-access-consent that was setup.

    • The API Provider authenticates the Customer.

    • The Customer selects the account(s) that are linked to the account-access-consent at this stage.

    • The Customer authorises the consent with the API Provider. The Customer will only be able to authorise or reject the consent details in its entirety.

    • The API Provider updates the state of the account-access-consent internally to indicate that the consent has been authorised.

    • Once the consent has been authorised, the Customer is redirected back to the Third Party.

  • In a decoupled flow:

    • The decoupled flow is initiated by the Third Party calling a back-channel authorisation request endpoint.

    • The back-channel authorisation request contains a 'hint' that identifies the Customer and the consent to be authorised.

    • The API Provider requests the Customer to authorise consent on an authentication device that is separate from the consumption device on which the Customer is interacting with the Third Party.

    • The API Provider authenticates the Customer.

    • The Customer selects the account(s) that are linked to the account-access-consent at this stage.

    • The Customer authorises the consent with the API Provider. The Customer will only be able to authorise or reject the consent details in its entirety.

    • The API Provider updates the state of the account-access-consent internally to indicate that the consent has been authorised.

    • Once the consent has been authorised, the API Provider may make a callback to the Third Party to notify them of successful authorisation.

Step 4: Request Data

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

• The unique AccountId(s) that are linked to the account-access-consent will be returned with a call to GET /accounts. This is commonly one of a Third Party’s first actions once a Third Party has a valid access token.

Step 5: Retrieve Status

• The Third Party may retrieve the status of the account-access-consent (with the ConsentId).

• This is carried out by making call to GET /account-access-consents/{ConsentId}.

Sequence Diagram

Open

Release Management

This section overviews the release management and versioning strategy for the Account Information APIs.

Account Access Consents

POST

• An API Provider must allow an account-access-consent created on a lower version, to be used to access account information resources in a higher version.

  • E.g., a ConsentId created in v2, must be allowed be used to access v3 account information endpoints

• An API Provider must allow a token that is bound to a Consent in a lower version, to be used to access account information endpoints in a higher version.

  • E.g., a token issued from an authorization code grant using an account-access-consent ConsentId from v2 must be allowed to be used to access GET /accounts in v3.

• An API Provider must not allow an account-access-consent created on a higher version, to be used to access account information resources in a lower version.

  • E.g., a ConsentId created in v2, must not be used to access v1 account information endpoints

GET

• An API Provider must allow an account-access-consent created on a lower version, to be accessed via a higher version. In the case where the account-access-consent is the same, but the structure has changed in a higher version, sensible defaults must be used, with the API Provider's developer portal clearly specifying the behaviour.
  
  

  • E.g., a ConsentId created in v2 must be allowed be accessed via v3, as this is a long lived consent.

• An API Provider must not allow an account-access-consent created on a higher version, to be accessed via a lower version.

  • E.g., a ConsentId created in v3 must not be accessed via v2.

• An API Provider must ensure the Consent object (including the Permissions) in an account-access-consent is unchanged when accessed in a different version.

  • E.g., an account-access-consent created in v2 will have the same Consent object when accessed via v2 and v3.

• An API Provider may allow an expired account-access-consent created on a lower version, to be accessed via a higher version.

  • E.g., an expired ConsentId created in v2 may be accessed via v3.

DELETE

• An API Provider must not allow an account-access-consent created in a higher version, to be deleted in a lower version.

  • E.g., a ConsentId created in v3 must not allowed to be deleted via v2.

• An API Provider must allow an account-access-consent created in a lower version, to be deleted in a higher version.

  • E.g., a ConsentId created in v1 must be allowed to be deleted via v2.

Account Information Resources

GET

• An API Provider must allow a token that is bound to a Consent in a lower version, to access account information endpoints of a higher version. 

  • E.g., a token issued from an authorization code grant using an AccountRequestId from v1 must be allowed to be used to access GET /accounts in v2.

• An API Provider must allow an account-access-consent created in a lower version, to access account information endpoints of a higher version.

  • E.g., an AccountRequestId from v1 must be allowed to be used as the ConsentId in v2 to access GET /accounts.

• An API Provider must not allow an account-access-consent created in a higher version, to access account information endpoints of a lower version.

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

• An API Provider must not allow an account-access-consent created in a lower version, to access a resource introduced in a higher version (as the Consent object will not have Permissions required to access the new resource).

  • E.g., 

• An API Provider may choose to populate new fields introduced in a higher version with sensible defaults (if mandatory) or not populate at all.

Endpoints

This section looks at the list of available API endpoints to access Account Information and optionality.

• The API Provider must implement the API endpoints in the table below that are marked as Mandatory.

• The API Provider may optionally implement the API endpoints that are marked as Optional.

• If an API Provider has not implemented an API endpoint marked as Optional, the API Provider must respond with a 501 (Not Implemented) for requests to that API endpoint.

Endpoint design considerations:

• Having resources that are finer grained (e.g., beneficiaries, direct-debits, standing-orders) means that we can, in the future, manage these resources (with unique identifiers)

• While balances is not a typical resource - we believe having an /accounts/{AccountId}/balances endpoint is simpler to understand than a URI to expand the /accounts resource 

Account Information Resources

Each of the high level resources are documented in sub-pages of the Account Information API specification with these sections:

• Definition

• Endpoints

• Data Model

  • UML Diagram

  • Notes

  • Filtering

  • Permission Codes - as they relate to accessing the resource

  • Data Dictionary - which defines fields, re-usable classes

  • Enumerations

• Usage Examples

Security & Access Control

Scopes

The access tokens required for accessing the Account Information APIs must have one of the following scopes:

Scopes

Grants Types

Third Parties must use a client credentials grant to obtain a token with the scope accounts to make:

• POST requests to the account-access-consents resource.

• GET requests to the account-access-consents resource.

• DELETE requests to the account-access-consents resource.

Third Parties must use an authorisation flow using a redirect or decoupled flow to obtain a token with the scope accounts to make:

• GET requests to access all other account information resources (i.e., all resources other than account-access-consents).

Consent Authorisation

The Third Party must create an account-access-consent through a POST operation. This account-access-consent contains the consent that the Third Party claims it has been given by the Customer to retrieve account and transaction information. At this stage, the consent is not yet authorised as the API Provider has not yet verified this claim with the Customer.

The API Provider responds with a ConsentId. This is the ConsentId that is used when initiating an authorisation flow (as described in the NZ Banking Data Security Profile).

As part of the authorisation flow:

• The API Provider authenticates the Customer.

• The API Provider plays back the consent (registered by the Third Party) back to the Customer - to get consent authorisation.

• The API Provider presents the Customer a list of accounts from which the Customer must select the account or accounts that apply to the consent.

• The Customer may accept or reject the consent in its entirety (but not selectively).

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

Consent Elements

The account-access-consents resource consists of the following fields, that together form the elements of the consent provided by the Customer to the Third Party:

• Permissions: The set of data clusters that the Customer has consented to allow the Third Party to access

• ExpirationDateTime: The date-time up to which the consent is valid.

• TransactionFromDateTime: The earliest point of the transaction / statement historical period that the Customer has consented to provide access to the Third Party.

• TransactionToDateTime: The last point of the transaction / statement historical period that the Customer has consented to provide access to the Third Party.

Permissions

Permissions codes will be used to limit the data that is returned in response to a protected 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 a Third Party to request a "Basic" permission code and the corresponding "Detail" permission code, it is not a malformed request, and the API Provider must not reject the request solely on the basis of duplication

The API Provider must reject account-access-consents with a 400 response code when:

• The Permissions array does not contain either ReadAccountsBasic or ReadAccountsDetail

• The Permissions array is empty

• The Permissions array includes a Permission code that is not supported by the API Provider (API Providers are expected to publish which API endpoints are supported)

• The Permissions array contains ReadTransactionsBasic but does not contain at least one of ReadTransactionsCredits and ReadTransactionsDebits

• The Permissions array contains ReadTransactionsDetail but does not contain at least one of ReadTransactionsCredits and ReadTransactionsDebits

• The Permissions array contains ReadTransactionsCredits but does not contain at least one of ReadTransactionsBasic and ReadTransactionsDetail

• The Permissions array contains ReadTransactionsDebits but does not contain at least one of ReadTransactionsBasic and ReadTransactionsDetail