Version Control

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.

Open

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 the appropriate 4xx code.

• 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.

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:

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

All dates in the HTTP headers are represented as RFC 7231 Full Dates. An example is below:

All 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. 

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

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

Whether the Customer is present or not-present is identified via the x-fapi-customer-ip-address header. If the Customer IP address is supplied, it is inferred that the Customer is present during the interaction.

The implications to this are:

• API Providers will need to rely on the Third Party's assertion.

Response Headers

HTTP Status Codes

The following are the HTTP response codes for the different HTTP methods - across all API endpoints.

An API Provider may return other standard HTTP status codes (e.g. from gateways and other edge devices) as described in RFC 7231 - Section 6.

An API Provider must respond with error response in the OAuth/OIDC flow with mandatory alignment of error codes to those specified in OpenID Connect Core Specification Section 3.1.2.6.