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.

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:

third_party_client_credential
accounts

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.

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

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

Expiration Date Time

The ExpirationDateTime is an optional field which specifies the expiration for Third Party access to the Customer's data.

The field is optional - as the consent for Third Party access to a Customer's data can be indefinite.

If no ExpirationDateTime is provided, the API Provider will determine the validity period of the accounts request.

ExpirationDateTime will also apply to the refresh token, if issued.

The ExpirationDateTime applies to all Permissions (data clusters) being consented.

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 Third Party must be restricted to accessing transactions within this period when accessing the transactions resource.

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

Consent Revocation

A Customer may revoke consent for accessing account information at any point in time.

The Customer may revoke authorisation directly with the API Provider. The mechanisms for this are in the competitive space and are up to each API Provider to implement in the API Provider's banking interface. If the Customer revokes authorisation with the API Provider, the Status of the account-request resource must be set to Revoked.

The Customer may request the Third Party to revoke consent that it has authorised. If consent is revoked with the Third Party:

• The Third Party must cease to access the APIs at that point.
• The Third Party must call the DELETE operation on the account-request resource (before confirming consent revocation with the Customer) to indicate to the API Provider that the Customer has revoked consent.

Changes to Selected Account(s)

The 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 API Provider. 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 Customer'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 API Provider must not revoke authorisation to other accounts.

Handling Expired Account-Requests

When an account-request has expired, the Third Party may use their client credentials grant access token to request the expired account-request. In this instance, the status will be as it was (e.g. Authorised) but the ExpirationDateTime will reflect the request has expired.

  "Meta": {
    "TotalPages": 1,
	"FirstAvailableDateTime": "2017-05-03T00:00:00+00:00",
	"LastAvailableDateTime": "2017-12-03T00:00:00+00:00"
  }

Swagger Specifications

Use the below link to access and download the Payments NZ API Centre GitHub repo: