Account Information API Specification v2.3.0

Version Control

Version

Date

Author

Comments

Version

Date

Author

Comments

2.0.0

Apr 30, 2020

Payments NZ API Working Group

Baseline

2.1-draft1

Jun 15, 2020 

@Gavin Wong (Unlicensed)

Updated:

Removed:

2.1-rc2

Sep 29, 2020

@Gavin Wong (Unlicensed)

Updated:

  • Scope definition based on Business WG feedback

2.2-draft1

Nov 4, 2021

@Gavin Wong (Unlicensed)

Updated:

  • Updated statements and party endpoints to be mandatory as per v2.2 scope

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

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

participant Customer participant Third Party participant API Provider Authorisation Server participant API Provider Resource Server note over Customer, API Provider Resource Server Step 1: Agree Account Access Consent end note Customer -> Third Party: Agree account access consent note over Customer, API Provider Resource Server Step 2: Create Account Access Consent end note Third Party <-> API Provider Authorisation Server: Establish TLS 1.2 MA Third Party -> API Provider Authorisation Server: Initiate Client Credentials Grant API Provider Authorisation Server -> Third Party: Return access-token Third Party <-> API Provider Resource Server: Establish TLS 1.2 MA Third Party -> API Provider Resource Server: POST /account-access-consents note over API Provider Resource Server: Consent Status: AwaitingAuthorisation API Provider Resource Server -> Third Party: HTTP 201 (Created), ConsentId note over Customer, API Provider Resource Server Step 3: Authorise Consent end note alt Redirection (using authorization code grant) Third Party -> Customer: HTTP 302 (Found), Redirect (ConsentId) Customer -> API Provider Authorisation Server: Follow redirect (ConsentId) Customer <-> API Provider Authorisation Server: Authenticate Customer <-> API Provider Authorisation Server: Select accounts linked to account access consent Customer <-> API Provider Authorisation Server: Authorise consent note over API Provider Resource Server: Consent Status: Authorised API Provider Authorisation Server -> Customer: HTTP 302 (Found), Redirect (authorization-code) Customer -> Third Party: Follow redirect (authorization-code) Third Party <-> API Provider Authorisation Server: Establish TLS 1.2 MA Third Party -> API Provider Authorisation Server: Exchange authorization-code for access token API Provider Authorisation Server -> Third Party: Return access-token else Decoupled (Using CIBA) Third Party -> API Provider Authorisation Server: POST /bc-authorize (login_hint_token) API Provider Authorisation Server -> Third Party: OK Customer -> API Provider Authorisation Server: Authorise (Consent Id) Customer <-> API Provider Authorisation Server: Authenticate Customer <-> API Provider Authorisation Server: Select accounts linked to account access consent Customer <-> API Provider Authorisation Server: Authorise consent note over API Provider Resource Server: Consent Status: Authorised alt Using callback API Provider Authorisation Server -> Third Party: Callback (authorization-code) Third Party <-> API Provider Authorisation Server: Establish TLS 1.2 MA Third Party -> API Provider Authorisation Server: Exchange authorization-code for access token API Provider Authorisation Server -> Third Party: Return access-token else Using polling Third Party <-> API Provider Authorisation Server: Establish TLS 1.2 MA Third Party -> API Provider Authorisation Server: Poll at /token using auth-req-id API Provider Authorisation Server -> Third Party: Return access-token end alt end alt note over Customer, API Provider Resource Server Step 4: Request Data end note Third Party <-> API Provider Resource Server: Establish TLS 1.2 MA Third Party -> API Provider Resource Server: GET /accounts API Provider Resource Server -> Third Party: HTTP 200 (OK), List of accounts containing AccountId(s) opt Request other account information resources loop Third Party -> API Provider Resource Server: GET /accounts/{AccountId}/transactions API Provider Resource Server -> Third Party: HTTP 200 (OK) List of transactions for a specific account end end opt note over Customer, API Provider Resource Server Step 5: Retrieve Status end note opt account-access-consents Third Party <-> API Provider Resource Server: Establish TLS 1.2 MA Third Party -> API Provider Resource Server: GET /account-access-consents/{ConsentId} API Provider Resource Server -> Third Party: HTTP 200 (OK) account-access-consent resource end opt

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 

Page Link

Resource

Endpoint

Mandatory?

Page Link

Resource

Endpoint

Mandatory?

Account Access Consents

account-access-consents

POST /account-access-consents

Mandatory

GET /account-access-consents/{ConsentId}

Mandatory

DELETE /account-access-consents/{ConsentId}

Mandatory

Accounts

accounts

GET /accounts

Mandatory

GET /accounts/{AccountId}

Mandatory

Balances

balances

GET /accounts/{AccountId}/balances

Mandatory

GET /balances

Optional

Transactions

transactions

GET /accounts/{AccountId}/transactions

Mandatory

GET /transactions

Optional

Beneficiaries

beneficiaries

GET/accounts/{AccountId}/beneficiaries

Optional

GET /beneficiaries

Optional

Direct Debits

direct-debits

GET /accounts/{AccountId}/direct-debits

Optional

GET /direct-debits

Optional

Standing Orders

standing orders

GET/accounts/{AccountId}/standing-orders

Optional

GET/standing-orders

Optional

Offers

offers

GET /accounts/{AccountId}/offers

Optional

GET /offers

Optional

Party

party

GET /accounts/{AccountId}/party

Mandatory

GET /party

Mandatory

Scheduled Payments

scheduled-payments

GET /accounts/{AccountId}/scheduled-payments

Optional

GET /scheduled-payments

Optional

Statements

statements

GET /accounts/{AccountId}/statements

Mandatory

GET /accounts/{AccountId}/statements/{StatementId}

Mandatory

GET /accounts/{AccountId}/statements/{StatementId}/file

Mandatory

GET /accounts/{AccountId}/statements/{StatementId}/transactions

Mandatory

GET /statements

Optional

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
accounts

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