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

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:

2017-04-05T10:43:07+00:00

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

Sun, 10 Sep 2017 19:43:31 UTC

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. 

//Sun, 12 Feb 2018 14:45:00 UTC
1518446700

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

Pre-Conditions

The following pre-conditions must be satisfied in order to use these APIs:

Pre-conditions for Third Parties

1. The Third Party must have completed onboarding with PNZ.
2. The Third Party must have completed registration with each of the API Providers that it wants to transact with and have been issued with a client-id.
   1. To use the Payment Initiation APIs, the client-id must have "payments" as one of the permitted scopes.
   2. To use the Account/Transaction APIs, the client-id must have "accounts" as one of the permitted scopes.
3. The Third Party must have valid network and signing certificates issued by each API Provider.

Pre-conditions for API Providers

1. The API Provider must have completed onboarding with PNZ.

Idempotency

If idempotency is implemented for an API endpoint:

• The x-idempotency-key provided in the header must be at most 40 characters in size. If a larger x-idempotency-key length is provided, the API Provider must reject the request with a status code is 400 (Bad Request).
• The Third Party must not change the request body while using the same x-idempotency-key. If the Third Party changes the request body, the API Provider must not modify the end resource. The API Provider may treat this as a fraudulent action.
• The API Provider must treat a request as idempotent if it had received the first request with the same x-idempotency-key from the same Third Party in the preceding 24 hours. 
• The API Provider must not create a new resource for a POST request if it is determined to be an idempotent request.
• The API Provider must respond to the request with the current status of the resource (or a status which is at least as current as what's available on existing online channels) and a HTTP status code of 201 (Created).
• The Third Party must not use the idempotent behaviour to poll the status of resources.

Message Signing

Pagination

An API Provider MAY provide a paginated response for GET operations that return multiple records.

In such a situation, the API Provider MUST:

• If a subsequent page of resource records exists, the API Provider must provide a link to the next page of resources in the Links.Next field of the response. The absence of a next link would indicate that the current page is the last page of results.
• If a previous page of resource records exists, the API Provider must provide a link to the previous page of resources in the Links.Prev field of the response. The absence of a prev link would indicate that the current page is the first page of results.

For a paginated responses, the API Provider SHOULD ensure that the number of records on a page are within reasonable limits - a minimum of 25 records (except on the last page where there are no further records) and a maximum of 1000 records.

Additionally, the API Provider MAY provide:

• A link to the first page of results in the Links.First field.
• A link to the last page of results in the Links.Last field.
• The total number of pages in the Meta.TotalPages field.

As with all other responses, the API Provider MUST include a "self" link to the resource in the Links.Self field as described in the Links sections.

This standard does not specify how the pagination parameters are passed by the API Provider and each API Provider may employ their own mechanisms to paginate the response.

Archiving

Archiving of intent-id resources will be for API Providers to define based on their internal Legal and Regulatory requirements.

Any payments that are not in the state AcceptedCustomerProfile may be deleted or archived after 24 hours and any account-requests that are not in the state Authorised may be deleted or archived after 24 hours. Archiving in this context means the intent-id is no longer available via the API (e.g., a 403 response from a GET /payments/{PaymentId}).

In addition:

• API Providers must not archive intent-ids within the first 24 hours of creation

• API Providers may archive expired intent-ids after 24 hours of creation

Security & Access Control

Scopes & Grant Types

To access each of the APIs, the API must be called with an access token in the HTTP Authorization header.

The scopes required with these access tokens and the grant type used to get the access token are specified in the specific API documentation.

Consent Authorisation

OAuth 2.0 scopes are coarse grained and the set of available scopes are defined at the point of client registration. There is no standard method for specifying and enforcing fine grained scopes (e.g. a scope to specify that account information should only be provided for certain time periods or to enforce payments of a specified amount on a specified date). 

An intent is used to define the fine-grained permissions that are granted by the Customer to the Third Party. 

The act of providing authorisation of an intent by a Customer to an API Provider is called consent authorisation.

The NZ Banking APIs use a variety of intents such as payments and account-requests.

A Third Party requests an API Provider to create intent by using a client credentials grant. The API Provider creates the intent and responds with the intent-id. The Third Party then redirects the Customer to the API Provider to authorise consent for the intent, passing in an intent-id as a parameter. This is done through an authorization grant flow and results in the issuance of an access token which is bound to a single Customer and an intent.

If the Customer does not complete a successful consent authorisation (e.g. if the Customer is not authenticated successfully), the authorization code grant ends with a redirection to the Third Party with an error response as described in RFC 6749 Section 4.1.2.1. The Customer is redirected to the Third Party with an error parameter indicating the error that occurred.

Handling Expired Access Tokens

Access Token issued through Client Credentials Grant

When an access token issued through a Client Credentials Grant expires, the Third Party must get a new access token by executing a client credential grant again.

Access Token issued through Authorization Code Grant

An API Provider may issue a refresh token along with an access token at the end of an authorization code grant.

When an access token obtained through an authorization code grant expires, the Third Party may attempt to get a new access and refresh token as defined in Section 6 of the OAuth 2.0 specification.

If the Third Party fails to get an access token using a refresh token, the Third Party must get the Customer to initiate a fresh authorisation code grant. 

Changes to an Intent's Authorised State

A Customer may revoke their consent either through the Third Party or directly through the API Provider. This only applies to long-lived consents.

• When the Customer revokes their consent with the API Provider, the API Provider must mark the underlying intent status as Revoked.

• When the Customer revokes their consent with the Third Party, the Third Party must make a DELETE request to the consent resource. 

In each of the above cases, the consent states are terminal i.e., the API Provider must not allow any further state changes. The API Provider must not permit any authorisation code grants to be initiated with such a consent.

Effect of Token Expiry on an Intent's Authorized State

An API Provider may issue an access token and refresh token for a long-lived consent. These tokens may expire before the consent expires. In such a situation, the state of the intent does not change and the API Provider must not modify the state of the intent.

Risk Scoring Information

Information for risk scoring and assessment will come via:

• FAPI HTTP headers. These are defined in Section 6.3 of the FAPI specification and in the Headers section of the NZ Banking Data Specification.
• Additional fields identified by the industry as business logic security concerns which will be passed in the Risk section of the payload in the JSON object. 

These are the set of additional fields in the Risk section are documented in the Data Model section.

Data Model

Common Payload Structure

This section gives an overview of the top level structure for the API payloads for the NZ Banking APIs.

The data contained within the Data section is documented with each individual API endpoint.

Request Structure

The top level request structure for the NZ Banking APIs:

{
  "Data": {
    ...
  },
  "Risk": {
    ...
  }
}

Data

The Data section contains the request data for the specific API request.

The structure of this element differs for each API endpoint.

Risk

The Risk section contains risk indicators for the specific API request as provided by the Third Party.

The risk indicators contained in this element may be different for each API endpoint.

Response Structure

The top level response structure for the NZ Banking APIs:

{
  "Data": {
    ...
  },
  "Risk": {
    ...
  },
  "Links": {
    ...
  },
  "Meta": {
    ...
  }
}

In line with the principle of RESTful APIs, the full resource must be replayed as part of the response.

Two additional top level sections are included in the response for:

• Links

• Meta

Links

The Links section is mandatory and will always contain absolute URIs to related resources.

The "Self" member is mandatory. 

"Links": {
  "Self": "https://examplebank.api.co.nz/open-banking-nz/v1.1/payments/58923"
}

Where the API provides a paginated response, the Links elements must also contain the members First, Prev, Next and Last.

The "Payments" member is optional and only relevant if the Data section of the response contains representations of one or more accounts resources. The "Payments" member is mandatory if any of the accounts represented may be used for making payments. If this link is not present, none of the accounts are valid for payments at this time. Note: that this link does not indicate sufficient funds, only that payment activity is not expressly forbidden for the account(s) in the response.

For example:

"Links": {
  "Self": "https://examplebank.api.co.nz/open-banking-nz/v1.1/accounts?page[number]=3&page[size]=1",
  "First": "https://examplebank.api.co.nz/open-banking-nz/v1.1/accounts?page[number]=1&page[size]=1",
  "Prev": "https://examplebank.api.co.nz/open-banking-nz/v1.1/accounts?page[number]=2&page[size]=1",
  "Next": "https://examplebank.api.co.nz/open-banking-nz/v1.1/accounts?page[number]=4&page[size]=1",
  "Last": "https://examplebank.api.co.nz/open-banking-nz/v1.1/accounts?page[number]=13&page[size]=1",
  "Payments" : 'https://examplebank.api.co.nz/open-banking-nz/v1.1/payments'
}

Meta

The Meta section is mandatory, but can be empty. An optional member is "TotalPages" which is specified as an integer (int32) and shows how many pages of results (for pagination) are available.

For example:

"Meta": {
  "TotalPages": 13
}

Reused Classes

NZRisk1

This section describes the NZRisk1 class - which is re-used in both the Payment APIs and the Account and Transaction APIs.

UML Diagram

Notes

• Payments for EcommerceGoods and EcommerceServices will be expected to have a MerchantCategoryCode and MerchantCustomerIdentification populated. Payments for EcommerceGoods will also have the DeliveryAddress populated

• While some of the fields are specific to the Payment APIs, the working group decided to re-use this object for the Account and Transaction APIs as the fields are all optional.

Data Dictionary

Usage Examples

The usage examples for the individual APIs are documented in their respective pages.

This section provides usage examples for some repeating patterns that are used by multiple resources.

Pagination Flows

The example below illustrates how an API Provider may return a paginated response.

GET /accounts HTTP/1.1
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
x-fapi-customer-last-logged-time: Sun, 10 Sep 2017 19:43:31 UTC
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Accept: application/json

HTTP/1.1 200 OK
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json
 
{
  "Data": {
    ...
  },
  "Links": {
    "Self": "https://examplebank.api.co.nz/open-banking-nz/v1.1/accounts/",
    "Last": "https://examplebank.api.co.nz/open-banking-nz/v1.1/accounts?page=3",   
    "First": "https://examplebank.api.co.nz/open-banking-nz/v1.1/accounts/",   
    "Next": "https://examplebank.api.co.nz/open-banking-nz/v1.1/accounts?page=2"
  },
  "Meta": {
    "TotalPages": 3
  }
}

The example below illustrates how an API Provider may use the Links section of the payload to navigate to the Next page of the results. 

GET /accounts?page=2 HTTP/1.1
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
x-fapi-customer-last-logged-time: Sun, 10 Sep 2017 19:43:31 UTC
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Accept: application/json

HTTP/1.1 200 OK
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json
 
{
  "Data": {
    ...
  },
  "Links": {
    "Self": "https://examplebank.api.co.nz/open-banking-nz/v1.1/accounts?page=2",
    "Last": "https://examplebank.api.co.nz/open-banking-nz/v1.1/accounts?page=3",   
    "First": "https://examplebank.api.co.nz/open-banking-nz/v1.1/accounts/",   
    "Next": "https://examplebank.api.co.nz/open-banking-nz/v1.1/accounts?page=3"
  },
  "Meta": {
    "TotalPages": 3
  }
}

Error Flows

This section provides some examples of error scenarios and the expected outputs.

Missing or Expired Access Token

This flow assumes that the following Steps have been completed successfully:

• Step 1: Request Account Information
• Step 2: Setup Account Request
• Step 3: Authorise Consent

The Third Party attempts to provide an expired or missing access token to the API Provider in an attempt to Request Data

Incomplete or Malformed Request Payload

This flow assumes that the following Steps have been completed successfully:

• Step 1: Request Account Information
• Step 2: Setup Account Request
• Step 3: Authorise Consent

The Third Party provides a malformed request to the API Provider in an attempt to setup an Account Request.

Missing or Invalid Access Token Scope

This flow assumes that the following Steps have been completed successfully:

• Step 1: Request Account Information
• Step 2: Setup Account Request
• Step 3: Authorise Consent

The Third Party provides a (valid) access token which does not have a valid scope (or link to the correct Permissions) to Request Data

Sudden Burst of API Requests

This flow assumes that the following Steps have been completed successfully:

• Step 1: Request Account Information
• Step 2: Setup Account Request
• Step 3: Authorise Consent

The Third Party provides a (valid) access token which is used to generate a burst of multiple requests to retrieve an Accounts resource.

The API Provider can optionally choose to return a 429 Response

Failed Authorisation Consent

This flow assumes that the following Steps have been completed successfully:

• Step 1: Request Account Information
• Step 2: Setup Account Request

The Step 3: Authorise Consent Flow fails to succeed due to the Customer providing invalid credentials to the API Provider, resulting in no Authorization Code being generated.