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. While this version of the API specification only allows access to NZ BECS identifiable accounts, the API specification is silent on what account types must be accessible.

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 

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 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

Detail Permissions

The ReadStatementsDetail is required to access the statement file download via: /accounts/{AccountId}/statements/{StatementId}/file

The additional elements that are granted for "Detail" permissions are listed in this table.

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 ExpirationDateTime is optional - as the consent for Third Party access to a Customer's data can be indefinite.

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

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

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

• The ExpirationDateTime value is in the past

Transaction To/From Date Time

The TransactionToDateTime and the TransactionFromDateTime specify the period for consented transaction and/or statement history. 

Both the TransactionToDateTime and the TransactionFromDateTime are optional and one may be specified without the other.

The API Provider must restrict access to transactions between the TransactionToDateTime and TransactionFromDateTime when a Third Party accesses the transactions resource.

The API Provider must restrict access to statements which are completely within this period when a Third Party accesses the statements resource.

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

• The TransactionToDateTime value is in the past

• The TransactionToDateTime not greater than the TransactionFromDateTime

Consent Re-authorisation

An API Provider may allow a Customer to re-authorise an account-access-consent (as it is a long-lived consent) if:

• The account-access-consent has a status of Authorised; and 

• The ExpirationDateTime of the account-access-consent has not elapsed.

An API Provider may allow the Customer to update the linked accounts during consent re-authorisation.

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-access-consent 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-access-consents resource (before confirming consent revocation with the Customer) to indicate to the API Provider that the Customer has revoked consent.

Consent Updates

An API Provider must not allow a Customer to update the parameters of an account-access-consent.

Selected Accounts

The Customer must select the accounts to which the account-access-consent is linked 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.

• The Customer changes the selected accounts during consent re-authorisation.

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.

Data Model

Response Structure

Meta

For Accounts Information APIs, the Meta section in API responses may contain two additional fields to indicate the date range for which data has been returned.

The transactions or statements for a particular range of dates may be excluded from the response because:

• The API Provider does not provide historical transactions / statements for that date range.

• The Customer has not consented to transactions / statements for that date range.

The absence of transactions / statements in the payload does not indicate that there were no transactions / statements during that period. 

To ensure that the data is interpreted correctly, the API Provider may provide two additional fields as part of the response in the Meta section:

• The date of the first available transaction (FirstAvailableDateTime); and

• The date of the last available transaction (LastAvailableDateTime).

Example Meta

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

Swagger Specifications

The Swagger Specification for the Account Information APIs can be downloaded at the Payments NZ API Centre GitHub repo:

https://github.com/PaymentsNZ/API-Account-Information/tree/master/dist/v2.0.1