Contents

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 request". This registers the data "permissions"  that the Customer has consented to provide to the Third Party; and 

• Subsequently, retrieve account data.

This specification should be read in conjunction with NZ Banking Data API Specification v1.0 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 end-points are documented in separate sections along with the data model that they employ and usage examples.

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

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 (and in the future transaction) information for domestic retail Bank accounts.

Out of Scope

This API does not cater for:

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

• Accounts other than domestic retail Bank accounts.

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

• The ability for the Third Party to pre-specify the list of accounts that have been agreed with the Customer for consent/authorisation. At the time of writing the specification - it is not clear from a Legal perspective how the changing of these details over time (e.g, customers adding or deleting accounts) affects the original agreed authorisation. 

• The ability for the Third Party to specify and "hints" for the types of accounts that have been agreed with the Customer for consent/authorisation (e.g., product or customer channel types). At the time of writing the specification - it is not clear from a Legal perspective how the changing of these details over time affects the original agreed authorisation. 

• Multi-authentication flows have been designed - but the full implications of the multi-authentication flows have not been worked through - so these are not in the v1.0 specification.

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

Basics

Overview

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

Overview Diagram

Open

Steps

Step 1: Request account information

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

Step 2: Setup Account Request

• The Third Party connects to the Financial Institution that services the Customer's (or Customer's) account(s) and creates an account-request resource. This informs the Financial Institution that one of its Customers (or Customers) is granting access to account information to a Third Party. The Financial Institution responds with an identifier for the resource (the AccountRequestId - which is the intent identifier).

• This step is carried out by making a POST request to /account-requests endpoint

• The setup payload will include these fields - which describe the data that the Customer  has consented with the Third Party:

  • Permissions - a list of data clusters that have been consented for access (e.g. ReadAccountsBasic - ability to read basic account information, ReadAccountsDetail - ability to read account identification details)

  • Expiration Date - an optional expiration for when the Third Party will no longer have access to the Customer's (or Customer's) data

• A Third Party 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. 

Step 3: Authorise Consent

• The Third Party redirects the Customer to the Financial Institution. The redirect includes the AccountRequestId generated in the previous step. This allows the Financial Institution to correlate the account-request that was setup. The Financial Institution authenticates the Customer and updates the state of the account-request resource internally to indicate that the account request has been authorised.

• The principle we have agreed is that consent is managed between the Customer and the Third Party - so the account-request details cannot be changed (with the Financial Institution in this step. The Customer will only be able to authorise or reject the account-request details in its entirety.

• During authorisation - the Customer selects accounts that are authorised for the Third Party request (in the Financial Institution's (or API Provider's) banking interface).

• The Customer is redirected back to the Third Party.

Step 4: Request account Information

• This is carried out by making a GET request the /accounts endpoint.

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

Sequence Diagram

Open

Idempotency

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

If a time-out error occurs - then we would expect a Third Party to create a new account-request resource - rather than try with the same resource.

Endpoints

This section looks at the list of available API endpoints to access Account Information and optionality (definitions of mandatory and optional are defined in the Principles section of the NZ Banking Data API Specification).

The API Provider must implement the API end-points in the table below that are marked as mandatory.

The API Provider may optionally implement the API end-points that are marked as non-mandatory.

If an API Provider has not implemented an optional API endpoint, it must respond with a 501 (Not Implemented) for requests to that URL.

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 

Mapping to Schemes & Standards

ISO 20022

The Account Info API resources, where possible, have been borrowed from the ISO 20022 camt.052 XML standard. However - has been adapted for APIs based as per our design principles. 

Deviations from the camt.052 XML standard are:

• The camt.052 header section and trailer sections have been removed - as these are not required for a RESTful API

• Resources have been identified, and payload structures have been designed for these resources - rather than a full message (i.e., camt.052) that encompasses all resources in a report format. This has meant we've designed separate endpoints and payloads to cover:

  • accounts

  • balances

  • beneficiaries

  • direct-debits

  • offers

  • party

  • standing-orders

  • statements

  • transactions

  • scheduled-payments

• New payloads have been designed for beneficiaries, direct-debits and standing-orders resources - as these are not in the ISO 20022 standard (or the camt.052 message)

• A DateTime element has been used instead of a complex choice element of Date and DateTime (across all API endpoints). Where time elements do not exist in API Provider systems - the expectation is the time portion of the DateTime element will be defaulted to 00:00:00+00:00

• Variations for the accounts structure include: 

  • Standardised inline with the Payment API account structures

  • Contains elements to identify an account Nickname, SecondaryIdentification

• Variations for the balances structure include:

  • Adding a Type into the CreditLine section - to allow for multiple credit line types affecting the available balance

  • DateTime element has been specified instead of a complex choice of Date and DateTime

• Variations for the transactions structure include:

  • Renaming "entry" to "transaction"

  • DateTime elements used instead of a complex choice of Date and DateTime

  • Flattening of the structure for BankTransactionCode and ProprietaryBankTransactionCode

  • Additional information for an AddressLine, MerchantDetails, and a running Balance

Security & Access Control

Scopes

The access tokens required for accessing the Account Info 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 third_party_client_credential to access the account-requests resource.

Third Parties must use an authorization code grant to obtain a token with the scope accounts to access all other resources.

Consent Authorisation

The Third Party must create an account-request resource through a POST operation. This resource indicates 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 an AccountRequestId. This is the intent-id that is used when initiating the authorization code grant (as described in the Trust Framework).

As part of the authorization code grant:

• 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 Customer may accept or reject the consent in its entirety (but not selectively).

• The API Provider presents the Customer 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 Customer.

Consent Elements

The Account Request 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 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)

The permissions array must contain either ReadAccountsBasic or ReadAccountsDetail.

The following combinations of permissions are not allowed, and the API Provider must reject these account-requests with a 400 response code:

• Account requests with an empty Permissions array

• Account requests with a permission code that is not supported by the API Provider (API Providers are expected to publish which API endpoints are supported)

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

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

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

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