Version Control

Version

Date

Author

Comments

2.0.0

Payments NZ API Working Group

Baseline

2.1-draft1

 

Gavin Wong (Unlicensed)

Updated:

Removed:

2.1-rc2

Gavin Wong (Unlicensed)

Updated:

  • Scope definition based on Business WG feedback

Overview

This specification describes the Account Information API flows and payloads.

The API endpoints described here allow an API Provider to:

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:

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:

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:

Out of Scope

This specification does not cater for:

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

Step 2: Create Account Access Consent

Step 3: Authorise Consent

Step 4: Request Data

Step 5: Retrieve Status

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

GET

DELETE

Account Information Resources

GET

Endpoints

This section looks at the list of available API endpoints to access Account Information and optionality.

Endpoint design considerations:

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:

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:

Third Parties must use an authorisation flow using a redirect or decoupled flow to obtain a token with the scope accounts to make:

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:

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

Permissions codes will be used to limit the data that is returned in response to a protected resource request. 

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

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

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

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:

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:

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:

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:

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

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

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 found at the Payments NZ API Centre GitHub repo:

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