NZ Banking Data API Specification v2.0.2
- 1 Version Control
- 2 Overview
- 2.1 Overview Diagram
- 2.1.1 Steps
- 2.2 Document Structure
- 2.3 Known Issues
- 2.4 Design Principles
- 2.4.1 RESTful APIs
- 2.4.2 Standards
- 2.4.3 Extensibility
- 2.4.4 Idempotency
- 2.4.5 Message Signing
- 2.4.6 Message Encryption
- 2.4.7 Agnostic to Payment Schemes
- 2.4.8 Status Codes
- 2.4.9 Unique Identifiers (Id Fields)
- 2.4.10 Categorisation of Implementation Requirements
- 2.4.11 Open Banking UK
- 2.1 Overview Diagram
- 3 Basics
- 3.1 Actors
- 3.2 Character Encoding
- 3.3 Date Formats
- 3.4 Resource URI Path Structure
- 3.5 Headers
- 3.5.1 Request Headers
- 3.5.2 Response Headers
- 3.6 HTTP Status Codes
- 3.7 Pre-Conditions
- 3.8 Idempotency
- 3.9 Filtering
- 3.10 Pagination
- 3.11 Archiving
- 4 Security & Access Control
- 4.1 Scopes
- 4.2 Consent Authorisation
- 4.3 Token Expiry
- 4.3.1 Token Expiry Time
- 4.4 Supported Grant Types
- 4.4.1 Client Credentials Grant
- 4.4.2 Redirect Flow (Hybrid)
- 4.4.2.1 ID Token
- 4.4.2.2 Error Condition
- 4.4.3 Decoupled Flow (CIBA)
- 4.4.3.1 ID Token Hint
- 4.4.3.2 Login Hint Token
- 4.4.3.2.1 UML Diagram
- 4.4.3.2.2 Data Model
- 4.4.3.2.3 Example
- 4.5 Changes to Consent Status
- 4.6 Consent Re-authorisation
- 4.6.1 Use of Refresh Token
- 4.7 Risk Scoring Information
- 5 Data Model
- 5.1 Common Payload Structure
- 5.1.1 Request Structure
- 5.1.2 Response Structure
- 5.1.2.1.1 Response
- 5.1.2.2 Links
- 5.1.2.2.1 Example Links (Self only)
- 5.1.2.2.2 Example Links
- 5.1.2.3 Meta
- 5.1.2.3.1 Example Meta
- 5.1.3 Error Response Structure
- 5.1.3.1.1 Response
- 5.1.3.2 UML Diagram
- 5.1.3.3 Data Dictionary
- 5.1.3.3.1 Enumerations
- 5.2 Optional Fields
- 5.3 Enumerations
- 5.4 Common Classes
- 5.4.1 NZRisk1
- 5.4.1.1 UML Diagram
- 5.4.1.2 Notes
- 5.4.1.3 Data Dictionary
- 5.4.1 NZRisk1
- 5.1 Common Payload Structure
- 6 Usage Examples
- 6.1 Pagination Flows
- 6.1.1 Request
- 6.1.2 Paginated Resource Response
- 6.1.3 Request Next Page of Results
- 6.1.4 Paginated Resource Response (Next)
- 6.2 Error Flows
- 6.1 Pagination Flows
Version Control
Version | Date | Author | Comments |
|---|---|---|---|
1.0.0 | 01 March 2019 | Payments NZ API Working Group | Baseline |
v2.0-draft1 | Jun 4, 2019 | @Gavin Wong (Unlicensed) | Updates:
Additions:
Removed:
Errata:
|
v2.0-draft2 | Jul 8, 2019 | @Gavin Wong (Unlicensed) | Updates:
Additions:
Removed:
Errata:
|
v2.0-draft3 | Oct 1, 2019 | @Gavin Wong (Unlicensed) | Updates:
Additions:
Errata:
|
v2.0-rc2 | Dec 24, 2019 | @Gavin Wong (Unlicensed) | Updates:
Additions:
Errata:
|
v2.0.0 | Mar 31, 2020 | @Gavin Wong (Unlicensed) | No updates |
v2.0.1 | Jul 17, 2020 | @Gavin Wong (Unlicensed) | No updates to API specification from v2.0.0. Patch update to Swagger specification to include documented query parameters. |
v2.0.2 | Nov 5, 2022 | @Nigel Somerfield | Patch update to Swagger specification to BECSRemittance - DebtorReference and CreditorReference - specify |
Overview
The NZ Banking Data API Specification was designed to create an API based payments ecosystem for NZ and simplify partnering in the payments industry. These standards enable Banks to develop API endpoints to an agreed standard so that Third Parties can build web and mobile applications that make it easier for banking customers to pay for goods and services. This main specification provides a description of the elements that are common across all the NZ Banking Data APIs.
This specification should be read in conjunction with the individual NZ Banking API Specifications for:
Account Information API Specification
Payment Initiation API Specification
The PNZ API standards are based on the UK Open Banking standard. The PNZ API standards include adjustments to and place limitations on the UK Open Banking standard to make the standards more suitable to the NZ market. The Open Banking standard is now in the public domain; the PNZ API standards are not in the public domain as they are currently under development. Access to the PNZ API standards is currently limited to those organisations approved/authorised to operate in the NZ payments API ecosystem - Bank's and Third Parties. Approval and authorisation is managed by Payments NZ.
Overview Diagram
The figure below provides a general outline of a flow using the NZ Banking Data APIs.
Steps
Step 1: Agree Consent
This flow begins with a Customer consenting to allow a Third Party to access the Customer's protected resources with the API Provider.
Step 2: Create Consent
The Third Party connects to the API Provider that services the Customer's account(s) and creates a consent.
The API Provider responds with an identifier for the consent (the ConsentId).
Step 3: Authorise Consent
The Third Party initiates the authorisation flow for the Customer to authorise the consent.
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.
Step 4: Access Protected Resources
The API Provider authenticates the Third Party and Customer has authorised consent for the request before providing access to protected resources.
Step 5: Retrieve Consent Status
The Third Party may retrieve the status of the consent (with the ConsentId).
Document Structure
This document consists of the following parts:
Overview: Provides an overview of the Payments NZ API Standards and the key decisions and principles that contributed to the specification.
Basics: The section begins with an introduction to how the APIs are used.
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.
Known Issues
This document and its sub-pages must be read in conjunction with the https://paymentsnz.atlassian.net/wiki/spaces/PaymentsDirectionAPIStandardsDevelopment/pages/139788339.
Design Principles
RESTful APIs
The API adheres to RESTful API concepts where possible and sensible to do so.
However, the priority is to have an API that is simple to understand and easy to use. In instances where following RESTful principles would be convoluted and complex, the principles have not been followed.
References:
The highest level Data Description Language used is the JSON Schema : http://json-schema.org/
Best Practice has also been taken from the Data Description Language for APIs; JSON API : http://jsonapi.org/
The Interface Description Language used is the Swagger Specification version 2.0 (also known as Open API) : http://swagger.io/
Standards
The PNZ API Working Group principles for developing API standards:
PNZ API Working Group will adopt existing standards where relevant/appropriate to minimise re-inventing the wheel.
PNZ API Working Group will work with other relevant bodies to align with, contribute to and/or adopt other Standards work, especially relating to Open Banking UK.
Extensibility
It is intended that the API flows will be extended to cater for more complex use-cases in subsequent releases, and we have kept this in mind during the design.
Idempotency
Idempotency is difficult to implement consistently and leverage consistently.
As a result, idempotency is used sparingly in these specifications; with a preference to allow Third Parties to simply re-submit a request under failure conditions.
APIs have been defined to be idempotent, where not doing so would cause a poor Customer user-experience or increase false positive risk indicators.
Message Signing
Message signing must not be implemented for the Account Information API and Payment Initiation API request and responses.
Message Encryption
Message encryption must not be implemented for the Account Information API and Payment Initiation API request and responses.
Agnostic to Payment Schemes
The API will be designed so that it is agnostic to the underlying payment scheme that is responsible for carrying out the payment.
Status Codes
API responses use two status codes that serve two different purposes:
The HTTP Status Code reflects the outcome of the API call (the HTTP operation on the resource). Granular Functional Error Codes are specified as part of API Error Response Structure.
The Status field in a resource payload reflects the status of the resource.
Communicating a rejection status is done in two ways:
If the API Provider establishes a rejection scenario with payload or any contextual error during the API call, the API Provider must reject the request immediately with a 400 (Bad Request).
If the API Provider establishes a rejection scenario with the consent after the API call, the API Provider must set the Status of the consent to Rejected.
Unique Identifiers (Id Fields)
A REST resource should have a unique identifier (e.g. a primary key) that may be used to identify specific instances of a resource. These unique identifiers are used to construct URLs to identify and address specific instances of a resource.
However, considering that some of the resources described in this specification do not have a primary key in the system of record, the Id fields will be optional for some resources.
An API Provider must ensure that populated Id fields values are unique and immutable.
Categorisation of Implementation Requirements
The functionality, endpoints and fields within each resource are categorised as 'Mandatory' or 'Optional'.
API Providers must make documentation available to Third Parties (e.g. on their developer portals) specifying which 'Optional' endpoints and fields are implemented for any given implementation of the specification.
Mandatory
For functionalities and endpoints:
An API Provider must implement an endpoint that is marked Mandatory.
An API Provider must implement functionality that is marked Mandatory.
For fields:
A Third Party must specify the value of a Mandatory field.
An API Provider must process a Mandatory field when provided by the Third Party in an API request.
An API Provider must include meaningful values for Mandatory fields in an API response.
Optional
For functionalities and endpoints:
An API Provider may implement an Optional endpoint.
An API Provider may implement Optional functionality.
For fields:
A Third Party may specify the value of an Optional field.
An API Provider must process an Optional field when provided by the Third Party in an API request. If the API Provider cannot support a particular value in an Optional field, the API Provider must reject the request and respond with an error.
An API Provider may specify the value of an Optional field in an API response.
Open Banking UK
The principles we have applied to re-use of the Open Banking UK specifications are:
Only resources that are required will be included in the API specification.
We will modify Open Banking UK elements where the existing standard does not cater for the NZ Market (such as adding the "BECSElectronicCredit" Scheme).
Basics
Actors
In the NZ context, there are three main actors (API Provider, Third Party, and Customer).
The upstream Open Banking UK standard uses PSD2 parlance and acronyms that are not applicable or relevant to the New Zealand market. Below is a summary of the NZ equivalent for many common PSD2 terms.
Actor | Type | PSD2 Actor | NZ Description |
|---|---|---|---|
API Provider | Legal Entity | Account Servicing Payment Service Provider (ASPSP) | API Provider refers to a Registered Bank or Non-Bank Deposit Taker that has been accredited by the Payments NZ API Standards Body to utilise its API specifications and standards, and contribute to the standards ecosystem. The API Provider provides APIs in a manner that complies with the API Standards (e.g. Account Information and Payment Initiation APIs), and connects those APIs with a Third Party(s). |
Third Party | Legal Entity | Third Party Provider (TPP)
| Third Party refers to a legal entity that has been accredited by the Payments NZ API Standards Body to utilise its API specifications and standards, and contribute to the standards ecosystem. The Third Party is the entity that consumes an API in a manner that complies with the API Standards. References to a "Third Party" in the specification relate to a piece of registered software with an API Provider (with a specific client_id). A Third Party may engage in either or both of these services:
|
Customer | Person | Payment Service User (PSU) | Individuals who operate retail banking accounts who make use of an account information service or payment service. The banking accounts may be personal accounts or associated with businesses, trusts, etc. |
Merchant | Legal Entity | Merchant refers to a legal entity that interacts with the Customer and Third Party in an interaction not defined within the API specifications and standards. |
Character Encoding
The API requests and responses must use a UTF-8 character encoding. This is the default character encoding for JSON (RFC 7158 - Section 8.1).
However, an API Provider's downstream system may not accept some UTF-8 characters, such as emoji characters (e.g. "Happy Birthday 🎂🎂!" may not be an acceptable Payment Reference). If the API Provider rejects the message with a UTF-8 character that cannot be processed, the API Provider must respond with an HTTP 400 (Bad Request) status code.
Date Formats
An API Provider must accept all valid ISO-8601 date formats including its permitted variations (e.g. variations in how the timezone is defined, dates with or with a seconds or milliseconds part etc.) in the requests.
All dates in the JSON payloads are represented in ISO 8601 date-time format. All date-time fields in responses must include the timezone. For Example:
2017-04-05T10:43:07+00:00All dates in the query string (e.g., filter parameters) are represented in ISO 8601 date-time format and must not include the timezone.
If the DateTime contains a timezone, the API Provider must ignore the timezone component. The filter values will be assumed to refer to the same timezone as the timezone in which the resource is maintained.
For example:
2017-04-05T10:43:07
2017-04-05All dates in the HTTP headers are represented as RFC 7231 Full Dates. An example is below:
Sun, 10 Sep 2017 19:43:31 GMTAll dates in the JWT claims are expressed as a JSON number, representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time.
//Sun, 12 Feb 2018 14:45:00 UTC
1518446700Resource URI Path Structure
The path of the URI must follow the structure below (from the OB API Release Management document).
[participant-path-prefix]/open-banking-nz/[version]/[resource]/[resource-id]/[sub-resource]
This consists of the following elements:
[participant-path-prefix]
An optional API Provider specific path prefix.open-banking-nz
The constant string "open-banking-nz".[version]
The version of the APIs expressed as /v[major-version].[minor-version]/.[resource]/[resource-id]
Details the resource.[sub-resource]
Details the sub-resource.
An API Provider must use the same [participant-path-prefix] and host name for all its NZ Banking Data API resources.
Examples:
https://superbank.com/apis/open-banking-nz/v2.0/domestic-payment-consents
https://superbank.com/apis/open-banking-nz/v2.0/domestic-payments
https://superbank.com/apis/open-banking-nz/v2.0/account-access-consents
https://superbank.com/apis/open-banking-nz/v2.0/accountsFor brevity, the APIs are referred to by their resource names in these documents and in all examples.
Headers
Request Headers
The following headers should be inserted by the Third Party in each API call:
Header Value | Notes | POST Requests |
|---|