Account Information API Specification v2.0.0

Version Control

Version

Date

Author

Comments

Version

Date

Author

Comments

1.0.0

01 March 2019

Payments NZ API Working Group

Baseline Account Information specifications 

v2.0-draft1

May 31, 2019 

@Gavin Wong

Updates:

  • References to "account request" to "account access consent"

  • References to "Financial Institution" to "API Provider"

  • Updated and standardised draft1-Steps to:

    • Step 1: Agree Account Access Consent

    • Step 2: Create Account Access Consent

    • Step 3: Authorise Consent

    • Step 4: Request Data

    • Step 5: Retrieve Status (consistency for all specifications)

  • Step 3: Authorise Consent includes alternative flows for:

    • In a redirection flow

    • In a decoupled flow

  • Updated draft1-ConsentAuthorisation to reference authorization code flow can either be redirect or decoupled

  • Updated section heading "Changes to Selected Account(s)" to draft1-ConsentUpdates and clarified that:

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

    • "The Customer must select the accounts to which the consent is linked at the point of consent authorisation." from "The Customer must select the accounts to which the consent should be applied at the point of consent authorisation."

  • Updated language in draft1-TransactionTo/FromDateTime to clarify "The API Provider must restrict access..." instead of "The Third Party must be restricted to..."

Additions:

  • Data Model and Usage Examples added to draft1-DocumentStructure

  • draft1-ReleaseManagement section for accessing Account Information APIs - taken from OBIE v3.1.2 but reworded for clarity

  • draft1-AccountInformationResources section to describe sub-page content

  • Added guidance (per OBIE v3.1.2) to draft1-Permissions to clarify that "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."

  • Guidance in draft1-DetailPermissions that "The ReadStatementsDetail is required to access the statement file download via: /accounts/{AccountId}/statements/{StatementId}/file"

  • draft1-ConsentRe-authentication (to align with OBIE v3.1.2)

Removed:

  • References to "v1.0"

  • "Accounts other than domestic retail Bank accounts." in draft1-OutofScope as scope of accounts has not been agreed.

  • References in draft1-Scope to "it is not clear from a Legal perspective how the changing of these details over time.." as no longer relevant.

  • "Handling Expired Account-Requests" as duplicated

Errata:

  • Updated references in table for Transaction permissions for completeness to to include access to /accounts/{AccountId}/statements/{StatementId}/transactions

v2.0-draft2

Jul 8, 2019 

@Gavin Wong

Updates:

  • References to intent-id to ConsentId

  • Added loop for Step 4 in v2.0-draft2-SequenceDiagram

  • Renamed Consent Re-authentication to "Re-authorisation" in v2.0-draft2-ConsentRe-authorisation

  • References to authorization code grant updated to generic "authorisation flow"

  • Updated references to "older version" to "lower version" and "newer version" to "higher version" (from Technical Decision 006)

Additions:

  • In draft1-Steps clarification that "The account-access-consent is a long lived consent."

  • in draft2-Scope clarification that "... the API specification is silent on what account types must be accessible" - reflecting Business Decision - 003 - Account Type Scope

Errata:

  • Updated reference to payment-order consent to account access consent

v2.0-draft3

Oct 17, 2019 

@Gavin Wong

Additions:

  • Rejection scenarios for:

    • draft3-ExpirationDateTime for "The ExpirationDateTime value is in the past"

    • draft3-TransactionTo/FromDateTime for "The TransactionToDateTime value is in the past"

    • draft3-TransactionTo/FromDateTime for "The TransactionToDateTime not greater than the TransactionFromDateTime"

Updates:

  • Updated draft3-Permissions section to explicitly highlight API Provider rejection scenarios

v2.0-rc2

Dec 23, 2019

@Gavin Wong

Updates:

Errata:

  • Updating references to “resources” to clarify language

  • Updated references to “account-requests”

  • In the Steps section updated “The API Provider chooses either the redirection flow or a decoupled flow” to “The Third Party chooses either the redirection flow or a decoupled flow”

v2.0

Mar 20, 2020

@Gavin Wong

Errata:

  • Removed guidance on Expiration Date Time that “If no ExpirationDateTime is provided, the API Provider will determine the validity period of the accounts request.” as this is inconsistent with consent being immutable

  • Reference to “account-request”

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

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 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

Optional

GET /party

Optional

Scheduled Payments

scheduled-payments

GET /accounts/{AccountId}/scheduled-payments

Optional

GET /scheduled-payments

Optional

Statements

statements

GET /accounts/{AccountId}/statements

Optional

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

Optional

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

Optional

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

Optional

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
1 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).

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.

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

Permissions

Endpoints

Business Logic

Data Cluster Description

Permissions

Endpoints

Business Logic

Data Cluster Description

ReadAccountsBasic

  • /accounts

  • /accounts/{AccountId}



Ability to read basic account information

ReadBalances

  • /balances

  • /accounts/{AccountId}/balances



Ability to read all balance information

ReadAccountsDetail

  • /accounts

  • /accounts/{AccountId}

Access to additional elements in the payload (the additional data elements are listed in the table below)

Ability to read account identification details

ReadBeneficiariesBasic

  • /beneficiaries

  • /accounts/{AccountId}/beneficiaries



Ability to read basic beneficiary details

ReadBeneficiariesDetail

  • /beneficiaries

  • /accounts/{AccountId}/beneficiaries

Access to additional elements in the payload

Ability to read account identification details for the beneficiary

ReadDirectDebits

  • /direct-debits

  • /accounts/{AccountId}/direct-debits



Ability to read all direct debit information

ReadStandingOrdersBasic

  • /standing-orders

  • /accounts/{AccountId}/standing-orders



Ability to read basic standing order information

ReadStandingOrdersDetail

  • /standing-orders

  • /accounts/{AccountId}/standing-orders

Access to additional elements in the payload

Ability to read account identification details for beneficiary of the standing order

ReadTransactionsBasic

  • /transactions

  • /accounts/{AccountId}/transactions

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

Permissions must also include at least one of:

  • ReadTransactionsCredits

  • ReadTransactionsDebits

Ability to read basic transaction information

ReadTransactionsDetail

  • /transactions

  • /accounts/{AccountId}/transactions

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

Access to additional elements in the payload

Permissions must also include at least one of

  • ReadTransactionsCredits

  • ReadTransactionsDebits

Ability to read transaction data elements which may hold silent party details

ReadTransactionsCredits

  • /transactions

  • /accounts/{AccountId}/transactions

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

Access to credit transactions.

Permissions must also include one of:

  • ReadTransactionsBasic

  • ReadTransactionsDetail

Ability to read only credit transactions

ReadTransactionsDebits

  • /transactions

  • /accounts/{AccountId}/transactions

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

Access to debit transactions.

Permissions must also include one of:

  • ReadTransactionsBasic

  • ReadTransactionsDetail

Ability to read only debit transactions

ReadStatementsBasic

  • /statements

  • /accounts/{AccountId}/statements



Ability to read basic statement details

ReadStatementsDetail

  • /statements

  • /accounts/{AccountId}/statements

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

Access to additional elements in the payload

Access to download the statement file.

Ability to read statement data elements which may leak other information about the account

ReadOffers

  • /offers

  • /accounts/{AccountId}/offers



Ability to read all offer information

ReadParty

  • /accounts/{AccountId}/party



Ability to read party information on the account owner.

ReadPartyAuthUser

  • /party



Ability to read party information on the user logged in.

ReadScheduledPaymentsBasic

  • /scheduled-payments

  • /accounts/{AccountId}/scheduled-payments



Ability to read basic statement details

ReadScheduledPaymentsDetail

  • /scheduled-payments

  • /accounts/{AccountId}/scheduled-payments

Access to additional elements in the payload

Ability to read account identification details for beneficiary of the scheduled payment

ReadPAN

All API endpoints where PAN is available as a structured field

Request to access to PAN in the clear

Request to access PAN in the clear across the available endpoints. 

If this permission code is not in the account-access-consent, the Third Party will receive a masked PAN.

While a Third Party may request to access PAN in the clear, an API Provider may still respond with a masked PAN if the API Provider takes a legal view to respond with only the masked PAN.

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. 

Permission - Detail Codes

Data Element Name

Occurrence

XPath

Permission - Detail Codes

Data Element Name

Occurrence

XPath

ReadAccountsDetail

Account

0..1

OBReadAccount2/Data/Account/Account

ReadAccountsDetail

Servicer

0..1

OBReadAccount2/Data/Account/Servicer

ReadBeneficiariesDetail

CreditorAgent

0..1

OBReadBeneficiary2/Data/Beneficiary/CreditorAgent

ReadBeneficiariesDetail

CreditorAccount

0..1

OBReadBeneficiary2/Data/Beneficiary/CreditorAccount

ReadStandingOrdersDetail

CreditorAgent

0..1

OBReadStandingOrder2/Data/StandingOrder/CreditorAgent

ReadStandingOrdersDetail

CreditorAccount

0..1

OBReadStandingOrder2/Data/StandingOrder/CreditorAccount

ReadTransactionsDetail

TransactionInformation

0..1

OBReadTransaction2/Data/Transaction/TransactionInformation

ReadTransactionsDetail

Balance

0..1

OBReadTransaction2/Data/Transaction/Balance

ReadTransactionsDetail

MerchantDetails

0..1

OBReadTransaction2/Data/Transaction/MerchantDetails

ReadTransactionsDetail

CreditorAccount

0..1

OBReadTransaction2/Data/Transaction/CreditorAccount

ReadTransactionsDetail

DebtorAccount

0..1

OBReadTransaction2/Data/Transaction/DebtorAccount

ReadStatementsDetail

StatementAmount

0..*

OBReadStatement1/Data/Statement/StatementAmount

ReadScheduledPaymentsDetail

CreditorAgent

0..1

OBReadScheduledPayment1/Data/ScheduledPayment/CreditorAgent

ReadScheduledPaymentsDetail

CreditorAccount

0..1

OBReadScheduledPayment1/Data/ScheduledPayment/CreditorAccount

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

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.

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.

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
1 2 3 4 5 "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 from the Payments NZ API Centre GitHub repo:

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