4.1 Overview

One of the primary aims of the Guidelines is to provide simplification and consistency throughout each stage of API Standards implementation. Therefore, we have defined a core set of Account Information Services journeys to illustrate the roles played by each party in the the API Standards ecosystem.

The API Standards support Account Information Services. They enable a Third Party to access account information from accounts held at API Providers and to provide account information services to a Customer, provided they have obtained the Customer’s explicit consent.

This section describes the core journeys that support the set-up and management of Account Information Services. The key components are:

Account Information Consent – A Customer giving consent to a Third Party to request account information from their API Provider.
Consent Dashboard and Revocation – Third Party facility to enable a Customer to view and cancel consents given to that Third Party.
Access Dashboard and Revocation – API Provider facility to enable a Customer to view all Third Parties that have access to their account(s) and the ability to cancel that access. This should be available on those channels that the Customer uses to manage their accounts with the API Provider and be easy and intuitive for the Customer to find and use.
- This facility should not include unnecessary steps, superfluous information or language which could discourage the use of Third Party services or divert the Customer from the access management process.
Generic guidance around the effective use of re-direction screens (when the Customer is transferred to and from the API Provider’s domain).

NOTE: Limitations of Account Information Services Access for Customers acting with delegated user authority on behalf of Corporate Entities will only be able to use Third Party services, if this is permitted within the parameters of that delegated user authority

4.2 Account Information Services core journeys

4.2.1 Account Information consent

In this journey:

The Third Party presents a description of the service that it is providing and the data that it requires in order to support its service proposition.
The Customer selects the API Provider(s) where their payment account(s) is held.
The Customer is then directed to the domain of their API Provider(s) for authentication and to select the account(s) they want to give access to.
Once the Customer has been authenticated, their API Provider will be able to respond to the Third Party’s request by providing the account information that has been requested.

NOTE: When considering Third Party requests submitted by a Customer acting with delegated user authority on behalf of a corporate entity, the Customer may only be able to use Third Party services if this is permitted within the parameters of that delegated user authority.

4.2.2 Consent dashboard and revocation

A Third Party should provide Customers with a facility to view and cancel on-going consents that they have given to that API Provider. Additionally, they may have consented to share data from several API Providers with a single Third Party. This section describes how these consents should be displayed and how the Customer journey to cancel them should be constructed.

4.2.3 Access dashboard and revocation

API Providers should provide Customers with a facility to view and cancel on-going access that they have given to any Third Parties for each account held at that API Providers. This section describes how Third Party access should be displayed and how the Customer journey to cancel it should be constructed.

4.3 Permissions and data clusters for Account Information Services journeys

4.3.1 Permissions

In the Account Information Services Standards API design, data elements are logically grouped together into "permissions". It is at this level that Third Parties request data access. If they request access to a specific permission, they will have access to all the data elements in the permission. This provides a pragmatic approach, allowing Third Parties to be selective but at the same time creating a consent process that is at an acceptable level of granularity for the Customer. Details of the data elements within each permission are included in the API technical specifications.

4.3.2 Data clusters

OBIE Customer research shows that grouping permissions together and adding another layer of description aids the Customer’s understanding of the data they are being asked to consent to share. This approach also allows a consistency of language across Third Parties and API Providers to provide additional comfort to Customers that they are sharing the data they intend to. If consistent language is used across all Standards Users this will drive Customer familiarity and adoption. These groups of permissions are known as Data Clusters. Data Clusters are not reflected in the API specifications, they are purely a presentational layer on top of permissions to aid Customer understanding.

4.3.3 Data clusters structure and language

The following table describes how permissions should be grouped into Data Clusters and the language that should be used to describe the data at each of these levels. Both Third Parties and API Providers should describe the data being shared at a Data Cluster level and allow the Customer to "drill-down" to see the detail at permission level using the permission language set-out in the table below.

Where both Basic and Detail permissions are available from the same API end point, the Detail permission contains all data elements of the Basic permission plus the additional elements described in the table.

Data cluster language	API endpoints	Permissions	Permissions language	Information available
Your Account Details	Accounts	Accounts Basic	Any other name by which you refer to this account, and/or the currency of the account.	Currency of the account, Nickname of account (E.g. ‘Jakes Household account’)
	Accounts	Accounts Detail	Your account name, number	Account Name, Account Number
	Balances	Balances	Your account balance	Amount, Currency, Credit/Debit, Type of Balance, Date/Time, Credit Line
Your Regular Payments	Beneficiaries	Beneficiaries Basic	Payee agreements you have set up	List of Beneficiaries
	Beneficiaries	Beneficiaries Detail	Details of Payee agreements you have set up	Details of Beneficiaries account information (Name, Account) (plus all data provided in Beneficiaries Basic).
	Standing orders	Standing Order Basic	Your Standing Orders	SO Info, Frequency, Creditor Reference Info, First/Next/Final Payment information
	Standing orders	Standing Order Detail	Details of your Standing Orders	Details of Creditor Account Information (Name, Account) (plus all data provided in Standing Order Basic)
	Direct debits	Direct Debits	Your Direct Debits	Mandate info, Status, Name, Previous payment information
	Scheduled payments	Scheduled payments basic	Recurring and future dated payments	Scheduled dates, amount, reference. Does not include information about the beneficiary.
	Scheduled payments	Scheduled payments detail	Details of recurring and future dated payments	Scheduled dates, amount, reference. Includes information about the beneficiary.
Your account transactions	Transactions	Transactions basic credits	Your incoming transactions	Transaction Information on payments made into the Customer’s account (Reference, Amount, Status, Booking Data Info, Value Date info, Transaction Code). Does not include information about the entity that made the payment.
		Transactions basic debits	Your outgoing transactions	Same as above, but for debits.
		Transactions detail credits	Details of your incoming transactions	Transaction Information on payments made into the Customer’s account (Reference, Amount, Status, Booking Data Info, Value Date info, Transaction Code). Includes information about the entity that made the payment.
		Transactions detailed debits	Details of your outgoing transactions	Same as above but for debits.
		Transactions Basic	Your transactions	Transaction Information on payments for both credits in and debits out of the Customer’s account (Reference, Amount, Status, Booking Data Info, Value Date info, Transaction Code. Does not include information about the payer/payee.
		Transactions detail	Details of your transactions	Transaction Information on payments made both credits in and debits out of the Customer’s account (Reference, Amount, Status, Booking Data Info, Value Date info, Transaction Code). Includes information about the payer/payee.
Your statements	Statements	Statements basic	Information contained in your statement	All statement information excluding specific amounts related to various balance types, payments due etc.
	Statements	Statements detail	Details of information contained in your statement	All statement information including specific amounts related to various balance types, payments due etc.
	Offers	Offers	Offers available on your account	Balance transfer, promotional rates, limit increases, start and end dates.
Contact and party details	Account specific: Parties Party	Party	The full legal name(s) of account holder(s). Address(es), telephone number(s) and email address(es)*	The name of the account. Full Legal Name(s), Account Role(s), Beneficial Ownership, Legal Structure, Address or addresses, telephone numbers and email address as held by the bank/card issuer and party type (sole/joint etc.).

4.3.4 Optional data

If, with the consent of the Customer, a Third Party requests additional information, an API Provider may only provide this to a Third Party if it has authority from the Customer to use and disclose the additional information in that manner.

4.3.5 Relevance of data cluster against product type

The Third Party should ensure that is has business rules that manage the relationship between Data Cluster to product type and omit access to data clusters that are irrelevant to a product type, as well as its service offering.

For example, if a Third Party requests a cluster of data that is irrelevant to the product type associated to a payment account e.g. Direct Debit cluster requested for a Savings Account product type, the API Provider may provide that cluster as empty.

NOTE: With respect to the clusters and permissions language, the API Provider should consider whether the language that is displayed to the Customer is appropriate when the information being accessed relates to more than one party. For example, "Your data" may need to be adapted to just “data” to indicate to the Customer that the account information being displayed may not be solely specific to them, as is the case of joint accounts when the account information of both parties is requested.

Payments NZ API standards

4.0 Account Information Services (AIS)