Account Information API Specification v1.0.0

Contents

Version Control

VersionDateAuthorComments
1.0.001 March 2019Payments NZ API Working Group

Account Information specification

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.

EndpointsProvides 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


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

 Click here to expand UML diagram source...

participant "Customer" as Cx
participant "Third Party" as 3P
participant "API Provider\nAuthorisation Server" as APIProviderAS
participant "API Provider\nResource Server" as APIProviderRS
note over Cx, APIProviderRS
Step 1: Request account information
end note
Cx -> 3P: Get account/transaction information
note over Cx, APIProviderRS
Step 2: Setup account request
end note
3P <-> APIProviderAS: Establish TLS 1.2 MA
3P -> APIProviderAS: Initiate Client Credentials Grant
APIProviderAS -> 3P: access-token
3P <-> APIProviderRS: Establish TLS 1.2 MA
3P -> APIProviderRS: POST /account_requests
APIProviderRS -> 3P: HTTP 201 (Created), AccountRequestId
3P -> Cx: HTTP 302 (Found), Redirect (AccountRequestId)
note over Cx, APIProviderRS
Step 3: Authorize consent
end note
Cx -> APIProviderAS: Follow redirect (AccountRequestId)
group Refer to Consent Guidelines
Cx <-> APIProviderAS: Authenticate, may involve multi-factors or other strong authentication mechanisms
Cx <-> APIProviderAS: Select accounts
end group
APIProviderAS -> Cx: HTTP 302 (Found), Redirect (authorization-code)
Cx -> 3P: Follow redirect (authorization-code)
3P <-> APIProviderAS: Establish TLS 1.2 MA
3P -> APIProviderAS: Exchange authorization-code for access token
APIProviderAS -> 3P: access-token
note over Cx, APIProviderRS
Step 4: Request Data
end note
3P <-> APIProviderRS: Establish TLS 1.2 MA
3P -> APIProviderRS: Get /accounts
APIProviderRS -> 3P: HTTP 200 (OK), List of accounts containing AccountId(s)

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 

Page LinkResourceEndpointMandatory?
1Account Requests

account-requestsPOST /account-requestsMandatory
2GET /account-requests/{AccountRequestId}Mandatory
3DELETE /account-requests/{AccountRequestId}Mandatory
4Accountsaccounts

GET /accounts

Mandatory

5GET /accounts/{AccountId}Mandatory
6Balancesbalances

GET /accounts/{AccountId}/balances

Mandatory
7GET /balancesOptional
8Transactionstransactions

GET /accounts/{AccountId}/transactions

Mandatory
9GET /transactionsOptional
10Beneficiariesbeneficiaries

GET/accounts/{AccountId}/beneficiaries

Optional
11GET /beneficiariesOptional
12Direct Debitsdirect-debits

GET /accounts/{AccountId}/direct-debits

Optional
13GET /direct-debitsOptional
14Standing Ordersstanding orders

GET/accounts/{AccountId}/standing-orders

Optional
15GET/standing-ordersOptional
16Offersoffers

GET /accounts/{AccountId}/offers

Optional
17GET /offersOptional
18Partyparty

GET /accounts/{AccountId}/party

Optional
19GET /partyOptional
20Scheduled Paymentsscheduled-payments

GET /accounts/{AccountId}/scheduled-payments

Optional
21GET /scheduled-paymentsOptional
22Statementsstatements

GET /accounts/{AccountId}/statements

Optional
23GET /accounts/{AccountId}/statements/{StatementId}Optional
24GET /accounts/{AccountId}/statements/{StatementId}/fileOptional
25GET /accounts/{AccountId}/statements/{StatementId}/transactionsOptional
26GET /statementsOptional

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
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.
PermissionsEndpointsBusiness LogicData Cluster Description
ReadAccountsBasic

/accounts

/accounts/{AccountId}


Ability to read basic account 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
ReadBalances

/balances

/accounts/{AccountId}/balances


Ability to read all balance information
ReadBeneficiariesBasic

/beneficiaries

/accounts/{AccountId}/beneficiaries


Ability to read basic beneficiary details
ReadBeneficiariesDetail/beneficiaries

/accounts/{AccountId}/beneficiaries

Access to additional elements in the payloadAbility 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 payloadAbility to read account identification details for beneficiary of the standing order
ReadTransactionsBasic/transactions
/accounts/{AccountId}/transactions

Permissions must also include at least one of:

  • ReadTransactionsCredits
  • ReadTransactionsDebits

Ability to read basic transaction information

ReadTransactionsDetail/transactions
/accounts/{AccountId}/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

Access to credit transactions.

Permissions must also include one of:

  • ReadTransactionsBasic
  • ReadTransactionsDetail
Ability to read only credit transactions
ReadTransactionsDebits/transactions
/accounts/{AccountId}/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 payloadAbility to read account identification details for beneficiary of the scheduled payment
ReadPANAll API endpoints where PAN is available as a structured fieldRequest 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-request, 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 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 CodesData Element NameOccurrenceXPath
ReadAccountsDetailAccount0..1OBReadAccount2/Data/Account/Account
ReadAccountsDetailServicer0..1OBReadAccount2/Data/Account/Servicer
ReadBeneficiariesDetailCreditorAgent0..1OBReadBeneficiary2/Data/Beneficiary/CreditorAgent
ReadBeneficiariesDetailCreditorAccount0..1OBReadBeneficiary2/Data/Beneficiary/CreditorAccount
ReadStandingOrdersDetailCreditorAgent0..1OBReadStandingOrder2/Data/StandingOrder/CreditorAgent
ReadStandingOrdersDetailCreditorAccount0..1OBReadStandingOrder2/Data/StandingOrder/CreditorAccount
ReadTransactionsDetailTransactionInformation0..1OBReadTransaction2/Data/Transaction/TransactionInformation
ReadTransactionsDetailBalance0..1OBReadTransaction2/Data/Transaction/Balance
ReadTransactionsDetailMerchantDetails0..1OBReadTransaction2/Data/Transaction/MerchantDetails
ReadTransactionsDetailCreditorAccount0..1

OBReadTransaction2/Data/Transaction/CreditorAccount

ReadTransactionsDetailDebtorAccount0..1OBReadTransaction2/Data/Transaction/DebtorAccount
ReadStatementsDetailStatementAmount0..*OBReadStatement1/Data/Statement/StatementAmount
ReadScheduledPaymentsDetailCreditorAgent0..1OBReadScheduledPayment1/Data/ScheduledPayment/CreditorAgent
ReadScheduledPaymentsDetailCreditorAccount0..1OBReadScheduledPayment1/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 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.


Data Model

Using Meta to identify Available Transaction Period

For Accounts & Transaction APIs, the Metasection 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 the date of the first available transaction and last available transaction as part of the response in the Meta section in the FirstAvailableDateTime and LastAvailableDateTime fields.

Example Meta
  "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:

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