Contents

Version Control

Overview

The NZ Banking Data API 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 Payment Initiation and Account Information.

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.

Payments NZ API Standards Overview

The Payments NZ (PNZ) API Standards were designed to create an API-based payments ecosystem for NZ and simplify partnering in the payments industry. These standards enable retail 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. Below is a high level overview of the context in which these APIs will be used.

Overview Diagram

Open

Steps

Step 1: Request account information or make a payment

• The Customer interacts with a Third Party, such as an online merchant or payment services provider. For example, to buy goods or services.

• The Customer elects to access their account information and/or make a payment via the Third Party.

Step 2: Inform Financial Institution that one of its Customers is requesting the Third Party access their account information or make a payment on their behalf 

• The Third Party connects to the Financial Institution that services the Customer's account(s) and informs the Financial Institution that one of its Customer's wants the Third Party to access their account information or make a payment on their behalf.

• The Third Party must have been previously approved/authorised by the Financial Institution. 

Step 3: Authorise consent for Third Party to access their account information or make a payment on their behalf

• The Financial Institution authenticates the Customer and asks the Customer to select the accounts the Third Party may request information about and/or make payments from.

• The principle we have agreed is that consent is managed between the Customer and the Third Party - so the details cannot be changed (with the Financial Institution) in this step. The Customer will only be able to authorise or reject the Third Party's request in its entirety.

Step 4: Request access to the Customer's account information or make a payment

• The Financial Institution authenticates the Third Party and ensures the Customer has authorised consent for the request before providing the account information or making a payment.

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. Version 1.0.0 of the Payments NZ API standards are now in the public domain in read-only format and cannot currently be used in partnership with any API Provider (as defined in the specification).

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/ and OpenAPI-Specification

Standards

The PNZ API Working Group principles for developing these API standards:

• PNZ API Working Group will adopt existing standards where relevant/appropriate to minimise re-inventing the wheel.

• The initial scope of these Standards is limited to current scope - i.e., PNZ API pilot. However, the intention is that the scope of the Standards will extend to include additional resources and APIs.

• 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

Open Banking

The principles we have applied to re-use of the UK Open Banking Standard are:

• Only resources that are required for the PNZ API pilot will be included in the API documentation. The specification will leave all other resources intact and unchanged. 

• We will modify Open Banking elements where the existing standard does not cater for the NZ Market (such as adding the "BECSElectronicCredit" Scheme or the addition of the Payment link). 

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

Digital signatures will facilitate non-repudiation for Open Banking APIs. 

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.

Due diligence has been carried out to ensure that the API has the necessary fields to function with BECS payments - as per agreed scope.

We will provide further mapping guidance to ensure that differences are understood between the Open Banking Payment API standard, and BECS payments where applicable.

Status Codes

The API uses 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).

• A Status field in some of the resource payloads reflects the status of resources.

Additional status codes may be provided at the discretion of the API Provider.

Unique Identifiers (Id Fields)

A REST resource should have a unique identifier (e.g. a primary key) that may be used to identify the resource. These unique identifiers are used to construct URLs to identify and address specific resources.

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 option for some resources.

An API Provider that chooses to populate optional Id fields must ensure that the values are unique and immutable.

Definition of Optionality

For endpoints and fields within each resource, the following definitions apply:

• 'Mandatory' endpoints or fields marked must be implemented by the API Provider.

• 'Optional' endpoints may be implemented by the API Provider.

Notes

1. API Providers are free to decide whether to implement any of the ‘Optional’ endpoints and fields.

2. API Providers must make documentation available to Third Parties as to which optional endpoints and fields are implemented for this specification. 

Basics

Actors

In the NZ context, there are three actors:

The upstream Open Banking standard uses PSD2 parlance and acronyms that are is not applicable or relevant to the New Zealand market. Below is a summary of the NZ equivalent for many common Open Banking/PSD2 terms.  Note that where practical, the documentation and specifications have retained the Open Banking parlance and acronyms in brackets:

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

All dates in the JSON payloads are represented in ISO 8601 date-time format. All date-time fields in responses must include the timezone. An example is below:

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 resources defined by these APIs may be addressed through a path structure consisting of the following parts:

• An optional API Provider specific path prefix

• The constant string "open-banking-nz"

• The version of the APIs expressed as /v[major-version].[minor-version]/

• The resource name

Examples:

/examplebank.api.co.nz/open-banking-nz/v1.1/payments

/open-banking-nz/v1.0/payments

/apis/open-banking-nz/v1.1/accounts

Headers

Request Headers

The following headers should be inserted by the Third Party in each API call:

(Reference: Section 6.3 - Financial API — Part 1: Read Only API Security Profile (Implementer’s Draft).)

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

Return & Error 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.

API Providers must respond with error response in the OAuth/OIDC flow with mandatory alignment of error codes to those specified in RFC 6749 Section 4.1.2.1

Further information about status codes

When a Third Party tries to request a resource URL with a resource Id that does not exist, the API Provider must respond with a 403 (Forbidden) rather than a 404 (Not Found).

E.g., if a Third Party tries to GET /payments/22289 where 22289 is not a valid PaymentId, the API Provider must respond with a 403.

When a Third Party tries to request a resource URL that results in no business data being returned (e.g. a request to retrieve standing order on an account that does not have standing orders) the API Provider must respond with a 200 (OK) and set the array to be empty.