Version | Date | Author | Comments |
---|---|---|---|
1.0.0 | 01 March 2019 | Payments NZ API Working Group | Account Information specification |
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 v1.0 which provides a description of the elements that are common across all the NZ Banking Data APIs.
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 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.
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.
This API does not cater for:
The figure below provides a general outline of account information requests and flow using the Account Information APIs.
Step 1: Request account information
Step 2: Setup Account Request
Step 3: Authorise Consent
Step 4: Request account Information
participant "Customer" as Cx |
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.
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:
Page Link | Resource | Endpoint | Mandatory? | |
---|---|---|---|---|
1 | Account Requests | account-requests | POST /account-requests | Mandatory |
2 | GET /account-requests/{AccountRequestId} | Mandatory | ||
3 | DELETE /account-requests/{AccountRequestId} | Mandatory | ||
4 | Accounts | accounts | GET /accounts | Mandatory |
5 | GET /accounts/{AccountId} | Mandatory | ||
6 | Balances | balances | GET /accounts/{AccountId}/balances | Mandatory |
7 | GET /balances | Optional | ||
8 | Transactions | transactions | GET /accounts/{AccountId}/transactions | Mandatory |
9 | GET /transactions | Optional | ||
10 | Beneficiaries | beneficiaries | GET/accounts/{AccountId}/beneficiaries | Optional |
11 | GET /beneficiaries | Optional | ||
12 | Direct Debits | direct-debits | GET /accounts/{AccountId}/direct-debits | Optional |
13 | GET /direct-debits | Optional | ||
14 | Standing Orders | standing orders | GET/accounts/{AccountId}/standing-orders | Optional |
15 | GET/standing-orders | Optional | ||
16 | Offers | offers | GET /accounts/{AccountId}/offers | Optional |
17 | GET /offers | Optional | ||
18 | Party | party | GET /accounts/{AccountId}/party | Optional |
19 | GET /party | Optional | ||
20 | Scheduled Payments | scheduled-payments | GET /accounts/{AccountId}/scheduled-payments | Optional |
21 | GET /scheduled-payments | Optional | ||
22 | Statements | statements | GET /accounts/{AccountId}/statements | Optional |
23 | GET /accounts/{AccountId}/statements/{StatementId} | Optional | ||
24 | GET /accounts/{AccountId}/statements/{StatementId}/file | Optional | ||
25 | GET /accounts/{AccountId}/statements/{StatementId}/transactions | Optional | ||
26 | GET /statements | Optional |
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 access tokens required for accessing the Account Info APIs must have one of the following scopes:
third_party_client_credential accounts |
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.
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:
Once these steps are complete, the consent is considered to have been authorised by the Customer.
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 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:
Permissions | Endpoints | Business Logic | Data 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 payload | Ability to read account identification details for the beneficiary |
ReadDirectDebits | /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 | Permissions must also include at least one of:
| 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
| 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:
| Ability to read only credit transactions |
ReadTransactionsDebits | /transactions /accounts/{AccountId}/transactions | Access to debit transactions. Permissions must also include one of:
| Ability to read only debit transactions |
ReadStatementsBasic | /statements /accounts/{AccountId}/statements | Ability to read basic statement details | |
ReadStatementsDetail | /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-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 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:
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.
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.
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 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):
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.
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.
For Accounts & Transaction 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 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.
"Meta": { "TotalPages": 1, "FirstAvailableDateTime": "2017-05-03T00:00:00+00:00", "LastAvailableDateTime": "2017-12-03T00:00:00+00:00" } |
Use the below link to download and access the raw YAML swagger specifications in .txt format.