NZ Banking Data API Specification v2.1.0

Version Control

Version

Date

Author

Comments

Version

Date

Author

Comments

2.0.0

Apr 30, 2020

Payments NZ API Working Group

Baseline

2.1-draft1

Jun 15, 2020 

@Gavin Wong (Unlicensed)

Errata:

Updated:

  • Usage Example version from v2.0 to v2.1

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:

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

Actor

Type

PSD2 Actor

NZ Description

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)

  • Account Information Service Provider (AISP)

  • Payment Initiation Service Provider (PISP)

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:

  • Payment initiation services

  • Account information 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:00

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:

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

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

Sun, 10 Sep 2017 19:43:31 GMT

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:

Header Value

Notes

POST Requests

GET Requests

DELETE Requests

Header Value

Notes

POST Requests

GET Requests

DELETE Requests

x-fapi-auth-date

The time when the Customer last logged in with the Third Party. The value is supplied as a HTTP-date as in section 7.1.1.1 of [RFC7231].

E.g., x-fapi-auth-date: Tue, 11 Sep 2012 19:43:31 GMT

May use

May use

May use

x-fapi-customer-ip-address

The Customer's IP address if the Customer is currently logged in with the Third Party.

May use

May use

May use

x-fapi-interaction-id

An RFC4122 UID used as a correlation Id.

If provided, the API Provider must "play back" this value in the x-fapi-interaction-id response header.

May use

May use

May use

Authorization

Standard HTTP Header. 

Allows credentials to be provided to the Authorisation / Resource Server depending on the type of resource being requested. For OAuth 2.0 / OIDC, this comprises of either the Basic / Bearer Authentication Schemes.

Must use

Must use

Must use

Content-Type

Standard HTTP Header.

Represents the format of the payload being provided in the request.

This must be set to application/json.

If set to any other value, the API Provider must respond with a 415 (Unsupported Media Type).

Must use

Must not use

Must not use

Accept

Standard HTTP Header.

Determines the Content-Type that is required from the server.

  • For requests to API endpoints that respond only with JSON, the Accept header must be set to value application/json.

  • For requests to API endpoints that do not respond with JSON (e.g., GET /statements/{StatementId}/file), the API Provider must specify the available options on their developer portals.

If set to an unacceptable value, the API Provider must respond with a 406 (Not Acceptable).

If not specified, the default is application/json.

May use

May use

May use

x-idempotency-key

Custom HTTP Header.

Unique request identifier to support idempotency.

Must be specified for POST requests to idempotent resource endpoints.

Must not be specified for other requests.

Must use if endpoint is an idempotent endpoint.

Must not use if endpoint is not an idempotent endpoint.

Must not use

Must not use

x-customer-user-agent

The header indicates the user-agent that the Customer is using.

The Third Party may populate this field with the user-agent indicated by the Customer.

If the Customer is using a Third Party mobile app, the Third Party must ensure that the user-agent string is different from browser based user-agent strings.

May use

May use

May use

x-merchant-ip-address

The Merchant's IP address if the Third Party is interacting with a Merchant.

May use

May use

May use

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

Header Value

Notes

Mandatory ?

Header Value

Notes

Mandatory ?

Content-Type

Standard HTTP Header.

Represents the format of the payload returned in the response.

  • For responses to API endpoints that respond only with JSON, the API Provider must return Content-Type: application/json as a content header in response to requests.

  • For responses to API endpoints that do not respond with JSON, the API Provider must return the relevant Content-Type as the content header in response to requests.

Must use

x-fapi-interaction-id

An RFC4122 UID used as a correlation Id.

The API Provider must set the response header x-fapi-interaction-id to the value received from the corresponding FAPI client request header or to a RFC4122 UUID value if the request header was not provided to track the interaction. The header must be returned for both successful and error responses.

Must use

Retry-After



Header indicating the time (in seconds) that the Third Party should wait before retrying an operation.

The API Provider determines the rate limits and retry time frames.

The API Provider should include this header along with responses with the HTTP status code of 429 (Too Many Requests).

May use

Location

Header indicating the location of the resource created by the request.

May use

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.

An API Provider must respond with the NZ Banking Data Error Response Structure for all errors during API Calls.

Situation

HTTP Status

Notes

Returned by POST

Returned by GET

Returned by DELETE

Situation

HTTP Status

Notes

Returned by POST

Returned by GET

Returned by DELETE

GET request completed successfully.

200 OK



No

Yes

No

POST request completed successfully.

201 Created

The operation results in the creation of a new resource.

Yes

No

No

DELETE request completed successfully.

204 No Content



No

No

Yes

Request has malformed, missing or non-compliant JSON body, URL parameters or header fields.

400 Bad Request

The requested operation will not be carried out.

Yes

Yes

Yes

Authorization header missing or invalid token

401 Unauthorized

The operation was refused access.

Re-authenticating the Customer may result in an appropriate token that may be used.

Yes

Yes

Yes

Token has incorrect scope or a security policy was violated.

403 Forbidden

The operation was refused access.

Re-authenticating the Customer is unlikely to remediate the situation.

Yes

Yes

Yes

The Third Party tried to access the resource with a method that is not supported.

405 Method Not Allowed



Yes

Yes

Yes

The request contained an Accept header that requested a content-type other than application/json and a character set other than UTF-8

406 Not Acceptable



Yes

Yes

Yes

The operation was refused because the payload is in a format not supported by this method on the target resource.

415 Unsupported Media Type



Yes

No

No

The operation was refused as too many requests have been made within a certain timeframe.

429 Too Many Requests

API Providers may throttle requests when they are made in excess of their fair usage policy.

API Providers must document their fair usage policies in their developer portals.

The API Provider must respond with this status if it throttles the request.

The API Provider should include a Retry-After header in the response indicating how long the Third Party must wait before retrying the operation.

Yes

Yes

Yes

Something went wrong on the API gateway or micro-service

500 Internal Server Error

The operation failed.

Yes

Yes

Yes

The Third Party tried to access a resource that has not been implemented by the API Provider

501 Not Implemented



Yes

Yes

Yes

Service version deprecation

503 Service Unavailable

Where an API is deprecated and no longer operationally supported by an API Provider, its URI path may still be active and accept API requests. In this context it is recommended that a 503 Service Unavailable be returned so that the Third Party is aware of the API version being offline.

Yes

Yes

Yes

403 (Forbidden) v/s 404 (Not Found) v/s 501 (Not Implemented)

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). This is so API Providers do not accidentally disclose the existence of a resource instance.

E.g., if a Third Party tries to GET /domestic-payments/22289 where 22289 is not a valid DomesticPaymentId, the API Provider must respond with a 403 (Forbidden).

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

If an API Provider has not implemented an optional API, the API Provider must respond with a 501 (Not Implemented) for requests to that URL.

The table below illustrates some examples of expected behaviour:

Situation

Request

Response

Situation

Request

Response

Third Party attempts to retrieve a payment with an DomesticPaymentId that does not exist

GET /domestic-payments/1001

403 (Forbidden)

Third Party attempts to retrieve a resource that is in the specification, but not implemented by the API Provider.

E.g., an API Provider has chosen not to implement the bulk direct-debit endpoint

GET /direct-debits

501 (Not Implemented)

Third Party attempts to retrieve standing orders for an AccountId that exists, but does not have any standing orders

GET /accounts/1000/standing-orders

200 (OK)

 

403 (Forbidden)

When a Third Party tries to access a resource that it does not have permission to access, the API Provider must return a 403 (Forbidden), with an optional body with Error Response.

The situation could arise when:

  • The Third Party uses an access token that does not have the appropriate scope to access the requested resource.

  • The Third Party attempted to access a resource with an Id that it does not have access to. E.g., an attempt to access GET /domestic-payments/1001 where a domestic-payments resource with Id 1001 belongs to another Third Party.

  • The Third Party tries to access an account information resource, and the Third Party does not have a consent authorisation with the right Permissions to access the requested resource. E.g., an attempt to access GET /standing-orders when the ReadStandingOrdersBasic permission was not included in the consent authorisation.

  • The Third Party tries to access an account/transaction resource and the Third Party does not have a consent authorisation for the AccountId. E.g., an attempt to access GET /accounts/2001 or GET /accounts/2001/transactions when the Customer has not selected AccountId 2001 for authorisation.

  • The Third Party tries to access a protected payment resource, and the Third Party does not have a consent authorisation with the right consent parameters to access the requested resource. E.g., an attempt to POST /domestic-payments with a mis-match with the Consent object in the domestic-payment-consent.

When the Third Party uses an access token that is no longer valid, the situation could potentially be remedied by asking the Customer to re-authenticate. This should be indicated by a 401 (Unauthorized) status code.

401 (Unauthorized)

When the Third Party uses an expired access token, the API Provider must return a 401 (Unauthorized) without any error response.

The situation could arise when an API Provider has chosen to expire an access token, reasons may include:

  1. The consent has expired (e.g., the expiration date time has lapsed)

  2. Suspicious usage of the access token or suspected fraud

  3. The Customer has revoked consent

This error can potentially be remedied by asking the Customer to re-authenticate or authenticate with the right permissions.

429 (Too Many Requests)

When a Third Party tries to access a resource too frequently the API Provider may return a 429 (Too Many Requests). This is a non functional requirement and is down to individual API Providers to decide throttling limits.

This situation could arise when:

  • A Third Party decides to implement "Real Time Payment Status" functionality for its users and implements this badly by polling a GET endpoint or an Idempotent POST endpoint in excess of the API Provider's fair usage policy to provide pseudo "real-time" Status updates to the user.

  • A Third Party decides to use the Single Immediate Payment endpoint as if it were a batch payment facility and sends a large number of payment requests in a very short space of time such that it exceeds the API Provider's fair usage policy. 

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 with required scopes.

  3. The Third Party must have valid network and signing certificates issued by one of the accepted Certificate Authorities.

Pre-conditions for API Providers

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

  2. The API Provider must have valid network and signing certificates issued by one of the accepted Certificate Authorities.

Idempotency

An idempotency key is used to guard against the creation of duplicate resources when using the POST API endpoints (where indicated). 

If an idempotency key is required 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 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 or modify an existing resource for a POST request if it is determined to be an idempotent request. 

  • The Third Party must not change any part of an API request (i.e., parameters, header or body) while using the same x-idempotency-key. The API Provider may treat this as a fraudulent action.

  • If a Third Party attempts a different API request (the parameters, header or body changed) with an x-idempotency-key used in the preceding 24 hours - the behaviour is unspecified - as the result will depend on whether the original request has been successfully received by the API Provider.

  • The API Provider must respond to a successful API request with the current resource status (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.

If an idempotency key is not required for an API endpoint:

  • The API Provider must ignore the idempotency key if provided.

Filtering

An API Provider must provide limited support of filtering on GET operations that return multiple records.

The filter parameters, are always specific to particular field(s) of the resource, and follow the rules/formats defined under the resource's data dictionary. The format for dates in the filter parameters are defined in the Date Formats section.

Pagination

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

In a paginated response, the API Provider must provide:

  • A link to the next page of resources in the Links.Next field of the response if a subsequent page of resource records exists. The absence of a next link would indicate that the current page is the last page of results.

  • A link to the previous page of resources in the Links.Prev field of the response if a previous page of resource records exists. The absence of a prev link would indicate that the current page is the first page of results.

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

  • A "Self" link to the resource in the Links.Self field as with all other API responses, as described in the Links sections.

In a paginated response, 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.

In a paginated response, the API Provider may provide:

  • The total number of pages in the Meta.TotalPages field.

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.

If the original request from the Third Party included filter parameters, the paginated response must return only results that match the filter.

API Providers are not expected to implement pagination with transaction isolation. The underlying data-set may change between two subsequent requests. This may result in situations where the same transaction is returned on more than one page.

Archiving

Archiving of consent resources (identified with a ConsentId) will be for API Providers to define based on their internal Legal and Regulatory requirements. Archiving in this context means the ConsentId is no longer available via the API (e.g., a 403 response from a GET /domestic-payment-consents/{ConsentId}).

An API Provider may only archive a consent in these two scenarios:

  • The consent is not in the Authorised state - the API Provider may archive the consent 24 hours after the last consent status update (the StatusUpdateDateTime).

  • The consent has expired - the API Provider may archive the consent 24 hours after the consent expiration date time.

The implications of this are:

  • API Providers must not archive a ConsentId within the first 24 hours of the consent creation

  • API Providers may archive a ConsentId that is not in the Authorised state 24 hours after the last state change

  • API Providers may archive a ConsentId that is in the Authorised state 24 hours after the consent expiration date (e.g., the ExpirationDateTime for an account-access-consent)

Security & Access Control

Scopes

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.

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

A consent (identified with a ConsentId) is used to define the fine-grained permissions that are granted by the Customer to the Third Party. The NZ Banking APIs use a variety of consents resources such as account-access-consents and domestic-payment-consents. The act of a Customer providing authorisation of a consent with an API Provider is called consent authorisation.

Two generic consent types are used in the API specification:

  • Short lived consents - these are used for one-off access to a protected resource

  • Long lived consents - these are used for enduring access to a protected resource

Steps for consent authorisation are:

  • The Third Party requests an API Provider to create a consent (with the fine-grained permissions) using a client credentials grant.

  • The API Provider creates the consent and responds with a ConsentId.

  • The Third Party then initiates an authorisation flow (passing in the ConsentId as a parameter) where the Customer authorises the consent with the API Provider. The supported grant types for the authorisation flow are described below.

  • The API Provider issues an access token to the Third Party tied to the authorised consent and the Customer.

Token Expiry

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 consent does not change and the API Provider must not modify the state of the consent.

Token Expiry Time

The expiry time for issued access tokens and refresh tokens must be deterministic for the Third Party.

In order to achieve this:

  • The API Provider must indicate the lifetime in seconds of the access token in the expires_in field of the JSON object returned by the token endpoint (see https://tools.ietf.org/html/rfc6749#section-4.2.2).

  • If the API Provider issues a refresh token, the API Provider must indicate the date-time at which the refresh token will expire in a claim named https://www.apicentre.paymentsnz.co.nz/refresh_token_expires_at in the ID Token (returned by the token endpoint or userinfo endpoint). Its value must be a number containing a NumericDate value, as specified in https://tools.ietf.org/html/rfc7519#section-2.

  • NumericDate is a JSON numeric value representing the number of seconds from 1970-01-01T00:00:00Z UTC until the specified UTC date-time, ignoring leap seconds.

  • If the API Provider does not issue a refresh token, the API Provider must not populate the https://www.apicentre.paymentsnz.co.nz/refresh_token_expires_at claim in the ID Token.

  • If the API Provider issues a refresh token that does not expire, the API Provider must populate the claim named https://www.apicentre.paymentsnz.co.nz/refresh_token_expires_at in the ID Token with a value representing the number of seconds to 03:14:07 UTC on 19 January 2038 (end of UNIX epoch).

Supported Grant Types

OAuth2.0 and OIDC provide support for a variety of methods for the Authorization Server to issue an access token to the Client. These methods are called Grants.

Some of these Grant Types only identify the client, but not the resource owner. It is sufficient to provide the client's identity.

On the other hand, other grant types identify the client and resource owner. The resource owner must be authenticated to issue access tokens through such a grant type.

The NZ Banking Data API specification supports a sub-set of these grants as well as the FAPI Profile CIBA grant.

The NZ Banking Data Security Profile describes these grants in detail.

Grant Type

Mandatory?

Grant Type

Mandatory?

Client Credentials

Mandatory

Redirect Flow (Hybrid)

Mandatory

Decoupled Flow (CIBA)

Optional

Client Credentials Grant

Some of the APIs can be accessed using an access token issued through a Client Credentials Grant. These APIs are not restricted resources owned by the Customer and do not require Customer consent authorisation. It is sufficient to identify and authenticate the Third Party in order to call these APIs.

The Client Credentials Grant is documented in Section 4.4 of the OAuth 2.0 RFC.

Redirect Flow (Hybrid)

The Hybrid Flow enables access to APIs that require the Customer as well as Third Party to be identified and authenticated.

The Hybrid Flow (see Section 3.3. of the OIDC Specification) provides a redirect based mechanism to redirect a Customer to the API Provider's authorisation pages in order to authenticate the Customer and generate an authorization code. The Third Party can then exchange this authorization code for an access token (and optionally refresh token) by calling the API Provider's token endpoint and authenticating itself. The Hybrid Flow is deemed to be more secure than using the standard Authorization Code Grant (see Section 4.1 of the OAuth 2.0 RFC and Section 3.1 of the OIDC Specification).

The NZ Banking Data Security Profile and FAPI Read & Write API Security Profile specify a more stringent set of requirements that API Providers and Third Parties must adhere to.

ID Token

When an access token is generated through a Hybrid Flow, an OIDC Authorization Server will also issue an ID Token along with the access token.

The ID Token is a signed JWT that consists of a number of claims that identify the resource owner. In the NZ Banking Data API context, the ID Token always identifies the ConsentId that was authorised which can be mapped onto a single Customer.

As the ID Token is signed by the API Provider and bound to a specific Third Party (through the aud claim), the ID Token could be leveraged to identify the Customer in subsequent authorisation requests. OIDC caters for this by allowing the ID Token to be passed into an authorization code grant request as the id_token_hint query parameter (as documented here).

Error Condition

If the Customer does not complete a successful consent authorisation (e.g. if the Customer is not authenticated successfully), the hybrid flow 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.

Decoupled Flow (CIBA)

The CIBA flow is a decoupled authentication flow that enables access to APIs that require the Customer as well as Third Party to be identified and authenticated.

The Client Initiated Back-channel Authentication flow is part of the OpenID specifications. A FAPI Profile of the CIBA specification is available and API Providers that implement the CIBA Flow must adhere to this FAPI profile.

An API Provider may optionally implement the CIBA Flow to allow Customers to authenticate themselves using a decoupled authentication device that may be distinct from the consumption device on which they consume the Third Party application.

The NZ Banking Data Security Profile specifies a more stringent set of requirements that API Providers and Third Parties must adhere to.

An API Provider that implements the CIBA Flow:

  • must support the id_token_hint as a method of identifying the Customer to be authenticated.

  • may support login_hint_token as a method of identifying the Customer to be authenticated.

  • must document on their developer portal, the methods of identifying a Customer that the API Provider supports.

A Third Party:

  • must pass a method of identifying the Customer in the authorisation request object using either the login_hint_token or id_token_hint (i.e., not both).

  • must create a consent with the API Provider prior to creating the CIBA authorisation request.

  • must pass the generated ConsentId as a custom claim in the authorisation request object (this allows the access token that is eventually generated to be bound to a specific consent).

If an API Provider does not support a specific method of identifying a Customer, the API Provider must return an error with the error field set to invalid_request as per https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html#rfc.section.13.

ID Token Hint

To identify a Customer through a previously issued ID Token - the Third Party must issue an authorisation request object with an id_token_hint which contains an ID Token from a previously successful authentication event for the Customer. As this is a previously used ID Token, it is valid for a Third Party to use an expired ID Token.

Third Parties must provide either a login_hint_token or id_token_hint (i.e., not both).

Login Hint Token

The login_hint_token is a token in the CIBA authorisation request object that contains a subject_type and corresponding claim that identifies the Customer for whom authentication is being requested.

Third Parties must provide either a login_hint_token or an id_token_hint (i.e., not both).

The NZ Banking Data APIs support these login_hint_token identification claims:

  • phone

  • email

  • username

  • api_provider_token

  • third_party_token

UML Diagram
Data Model

Name

Occurrence

XPath

EnhancedDefinition

Class

Codes

Name

Occurrence

XPath

EnhancedDefinition

Class

Codes

NZLoginHintToken1



NZLoginHintToken1



NZLoginHintToken1



subject

0..1

NZLoginHintToken1/subject



NZLoginHintType1



subject_type

1..1

NZLoginHintToken1/subject/subject_type

The type of subject identification used in the login_hint_token. The subject_type must be accompanied by the corresponding claim field. E.g., a subject_type of "phone" must be accompanied by the corresponding phone claim.

NZCIBASubject1Code

api_provider_token
email
phone
third_party_token
username

phone

0..1

NZLoginHintToken1/subject/phone

A phone number that identifies the Customer with the API Provider.

PhoneNumber

\+[0-9]{1,3}-[0-9()+\-]{1,30}

email

0..1

NZLoginHintToken1/subject/email

An email address that identifies the Customer with the API Provider.

Max256Text



username

0..1

NZLoginHintToken1/subject/username

The username that identifies the Customer with the API Provider.

Max70Text



api_provider_token

0..1

NZLoginHintToken1/subject/api_provider_token

A token generated by a Customer's authentication device that identifies the Customer with the API Provider. This token is passed to the Third Party.

xs:string



third_party_token

0..1

NZLoginHintToken1/subject/third_party_token

A token generated by a Third Party and registered with a Customer's authentication device by the Customer.

xs:string



Example

This is an example of a login_hint_token using the phone number as the subject_type:

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 update the consent Status as Revoked.

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

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.

Consent re-authorisation is the scenario where the API Provider requests a long-lived consent to be re-authorised (e.g., because of fraud risk). In this scenario, the Third Party reuses the existing ConsentId, and the API Provider may tailor the re-authorisation flow to be more efficient than the full consent authorisation flow.

A Third Party may request a Customer to re-authorise an existing long-lived consent that is in the Authorised state (using the existing ConsentId) at any point of time. This includes before and after the tokens bound to the consent have expired.

An API Provider must accept a request from a Third Party to re-authorise a long-lived consent (that is in the Authorised state) at any point of time. This includes before and after the tokens bound to the consent have expired.

Once a consent is re-authorised, the Third Party must not use access tokens and refresh tokens that were previously issued for the same consent.

If an API Provider issues a new access token and refresh token as a result of consent re-authorisation, it may invalidate the previously issued access tokens and refresh tokens for the same consent.

Use of Refresh Token

An API Provider may issue a refresh token along with an access token as a result of consent re-authorisation.

When an access token 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 initiate a consent re-authorisation flow.

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:

Request

Data

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

The structure of this element differs for each API endpoint, and is documented on each API resource sub-page.

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. The structure of the Risk section is documented in the section for NZRisk1.

Response Structure

The top level response structure for the NZ Banking APIs:

Response

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

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

An API Provider must provide the "Self" member in an API response. 

If an API provides a paginated response, the Links section must also contain the members "First", "Prev", "Next" and "Last".

For example:

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:

Example Meta

Error Response Structure

The error response structure is used to structure the response body for API Provider error responses.

Response

UML Diagram

Data Dictionary

Name

Occurrence

XPath

EnhancedDefinition

Class

Codes

Name

Occurrence

XPath

EnhancedDefinition

Class

Codes

NZErrorResponse1



NZErrorResponse1

An array of detail error codes, and messages, and URLs to documentation to help remediation.

NZErrorResponse1



Code

1..1

NZErrorResponse1/Code

High level textual error code to help categorise the errors.

Max128Text



Id

0..1

NZErrorResponse1/Id

A unique reference for the error instance, for audit purposes, in case of unknown/unclassified errors.

Max128Text



Message

1..1

NZErrorResponse1/Message

Brief Error message. E.g., 'There is something wrong with the request parameters provided'.

Max500Text



Errors

1..n

NZErrorResponse1/Errors

NZError1





ErrorCode

1..1

NZErrorResponse1/Errors/ErrorCode

Low level textual error code.

NZErrorResponseError2Code

Field.Expected
Field.Invalid
Field.Missing
Field.Unexpected
Header.Invalid
Header.Missing

QueryParam.Invalid
Reauthenticate
Reauthorise
Resource.Consent.CreditorAccount
Resource.Consent.DebtorAccount
Resource.Consent.Exceed.DataPermissions
Resource.Consent.Exceed.Dates
Resource.Consent.Exceed.Frequency
Resource.Consent.Exceed.MaximumAmount
Resource.Consent.Exceed.TotalAmount
Resource.Consent.Exceed.TotalCount
Resource.Consent.Exceed.TransactionDates
Resource.Consent.InvalidStatus
Resource.Consent.Mismatch
Resource.Invalid
UnexpectedError
Unsupported.AccountIdentifier
Unsupported.AccountSecondaryIdentifier
Unsupported.Currency
Unsupported.Scheme

Message

1..1

NZErrorResponse1/Errors/Message

A free text description of the error that occurred. E.g., 'A mandatory field isn't supplied'.

Max500Text



Path

0..1

NZErrorResponse1/Errors/Path

A recommended but optional reference to the JSON Path of the field with error, e.g., Data.Consent.InstructedAmount.Currency

Max500Text



Url

0..1

NZErrorResponse1/Errors/Url

URL to help remediate the problem, provide more information or to API Reference.

xs:anyURI



Enumerations

Code Class

Name

Definition

Code Class

Name

Definition

NZErrorResponseError2Code

Field.Expected

For the scenario, when a field value is not provided in the payload, that is expected in combination with preceding field value pairs.
The corresponding path must be populated with the path of the unexpected field.

NZErrorResponseError2Code

Field.Invalid

An invalid value is supplied in one of the fields. Reference of the invalid field should be provided in the path field, and the URL field may have the link to a website explaining the valid behaviour. The error message should describe the problem in detail.

NZErrorResponseError2Code

Field.Missing

A mandatory field, required for the API, is missing from the payload. This error code can be used, if it is not already captured under the validation for Resource.Invalid.
Reference of the missing field should be provided in the path field, and URL field may have the link to a website explaining the valid behaviour.

NZErrorResponseError2Code

Field.Unexpected

For the scenario, when a field value is provided in the payload, that is not expected in combination with preceding field value pairs.

NZErrorResponseError2Code

Header.Invalid

An invalid value is supplied in the HTTP header. The HTTP Header should be specified in the path element.

NZErrorResponseError2Code

Header.Missing

A required HTTP header has not been provided. The HTTP Header should be specified in the path element.

NZErrorResponseError2Code

QueryParam.Invalid

An invalid value is supplied in the query parameter. The query parameter should be specified in the path element.

NZErrorResponseError2Code

Reauthenticate

The API Provider must use this error code to indicate that re-authentication by the Customer is required to process the request.

NZErrorResponseError2Code

Reauthorise

The API Provider must use this error code to indicate that re-authorisation by the Customer is required to process the request.

NZErrorResponseError2Code

Resource.Consent.CreditorAccount

The protected resource is outside the valid creditor account(s) for the payment-consent.

NZErrorResponseError2Code

Resource.Consent.DebtorAccount

The protected resource is outside the valid debtor account(s) for the payment-consent.

NZErrorResponseError2Code

Resource.Consent.Exceed.DataPermissions

The protected resource is outside the valid data permissions for the account-access-consent.

NZErrorResponseError2Code

Resource.Consent.Exceed.Dates

The protected resource is outside the valid date ranges for the consent.

NZErrorResponseError2Code

Resource.Consent.Exceed.Frequency

The protected resource is outside frequency limits for the payment-consent.

NZErrorResponseError2Code

Resource.Consent.Exceed.MaximumAmount

The protected resource is outside the maximum amount for the payment-consent.

NZErrorResponseError2Code

Resource.Consent.Exceed.TotalAmount

The protected resource is outside the total amount for the payment-consent.

NZErrorResponseError2Code

Resource.Consent.Exceed.TotalCount

The protected resource is outside the total count for the payment-consent.

NZErrorResponseError2Code

Resource.Consent.Exceed.TransactionDates

The protected resource is outside the valid transaction date ranges for the account-access-consent.

NZErrorResponseError2Code

Resource.Consent.InvalidStatus

The resource’s associated consent is not in a status that would allow the resource to be created, or a request to be executed.
E.g., if a consent resource had a status of AwaitingAuthorisation or Rejected, a resource could not be created against this consent.
The path element should be populated with the field in the consent resource that is invalid.

NZErrorResponseError2Code

Resource.Consent.Mismatch

Consent and protected resource mismatch. For example, if an element in the resource’s Initiation or Risk section does not match the consent section.
The path element should be populated with the field of the resource that does not match the consent.

NZErrorResponseError2Code

Resource.Invalid

The payload request does not match the endpoint schema.

NZErrorResponseError2Code

UnexpectedError

An error code that can be used, when an unexpected error occurs.
The API Provider must populate the message with a meaningful error description, without revealing sensitive information.

NZErrorResponseError2Code

Unsupported.AccountIdentifier

The account identifier is unsupported for the given scheme.
The path element should be populated with the path of the AccountIdentifier.

NZErrorResponseError2Code

Unsupported.AccountSecondaryIdentifier

The account secondary identifier is unsupported for the given scheme.
The path element should be populated with the path of the AccountSecondaryIdentifier.

NZErrorResponseError2Code

Unsupported.Currency

The currency is not supported. Use Field.Invalid for invalid Currency.
The URL should be populated with a link to API Provider documentation listing out the supported currencies.
The path element should be populated with the path of the Currency.

NZErrorResponseError2Code

Unsupported.Scheme

Identification scheme is not supported.
The URL should be populated with a link to API Provider documentation listing out the supported schemes.
The path element should be populated with the path of the scheme.

Optional Fields

In objects where the value for an optional field is not specified, the field must be excluded from the JSON payload (i.e., the field must not included in the payload with the field set to null).

In objects where an array field is defined as having 0..n values, the array field must be included in the payload with an empty array.

In the case of empty objects, unless specified, the object must be excluded from the JSON payload.

Enumerations

The specifications include various enumerated data types, where values are fixed to a defined set of alternatives (i.e. static enumerations). These static enumerations are listed on each API Specification page.

Common Classes

This section describes object classes that are reused within the NZ Banking APIs.

NZRisk1

This section describes the NZRisk1 class.

UML Diagram

Notes

  • Payments for EcommerceGoods and EcommerceServices should have a MerchantCategoryCode and MerchantCustomerIdentification populated.

  • Ecommerce payments which have a delivery address must have the DeliveryAddress populated. The AddressType for the DeliveryAddress object must be set to "DeliveryTo".

  • 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

Name

Occurrence

XPath

EnhancedDefinition

Class

Codes

Pattern

Name

Occurrence

XPath

EnhancedDefinition

Class

Codes

Pattern

NZRisk1



NZRisk1

The Risk section is sent by the initiating party to the API Provider. It is used to specify additional details for risk scoring.

NZRisk1





EndUserAppName

0..1

NZRisk1/EndUserAppName

Name of the end user facing application.

Max70Text





EndUserAppVersion

0..1

NZRisk1/EndUserAppVersion

Version of the end user facing application.

Max14Text





PaymentContextCode

0..1

NZRisk1/PaymentContextCode

Specifies the payment context

OBExternalPaymentContext1Code

BillPayment
EcommerceGoods
EcommerceServices
Other
PersonToPerson



MerchantName

0..1

NZRisk1/MerchantName

Name of the merchant.

Max70Text





MerchantNZBN

0..1

NZRisk1/MerchantNZBN

NZ business number for the merchant.

Max70Text





MerchantCategoryCode

0..1

NZRisk1/MerchantCategoryCode

Category code conform to ISO 18245, related to the type of services or goods the merchant provides for the transaction.

Min3Max4Text





MerchantCustomerIdentification

0..1

NZRisk1/MerchantCustomerIdentification

The unique customer identifier of the Customer with the merchant.

Max70Text





GeoLocation

0..1

NZRisk1/GeoLocation

Location of the end-user on the Earth specified by two numbers representing vertical and horizontal position.

NZGeoLocation1





Latitude

1..1

NZRisk1/GeoLocation/Latitude

Latitude measured in decimal format.

Max14Text



^-?\d{1,3}\.\d{1,8}$

Longitude

1..1

NZRisk1/GeoLocation/Longitude

Longitude measured in decimal format.

Max14Text



^-?\d{1,3}\.\d{1,8}$

DeliveryAddress

0..1

NZRisk1/DeliveryAddress

Information that locates and identifies a specific address, as defined by postal services.

OBPostalAddress8





AddressType

0..1

NZRisk1/DeliveryAddress/AddressType

Identifies the nature of the postal address.

OBAddressTypeCode

DeliveryTo



AddressLine

0..5

NZRisk1/DeliveryAddress/AddressLine

Information that locates and identifies a specific address, as defined by postal services, that is presented in free format text.

Max70Text





StreetName

0..1

NZRisk1/DeliveryAddress/StreetName

Name of a street or thoroughfare.

Max70Text





BuildingNumber

0..1

NZRisk1/DeliveryAddress/BuildingNumber

Number that identifies the position of a building on a street.

Max16Text





PostCode

0..1

NZRisk1/DeliveryAddress/PostCode

Identifier consisting of a group of letters and/or numbers that is added to a postal address to assist the sorting of mail.

Max16Text





TownName

0..1

NZRisk1/DeliveryAddress/TownName

Name of a built-up area, with defined boundaries, and a local government.

Max35Text





CountrySubDivision

0..1

NZRisk1/DeliveryAddress/CountrySubDivision

Identifies a subdivision of a country eg, state, region, county.

Max35Text





Country

1..1

NZRisk1/DeliveryAddress/Country

Nation with its own government, occupying a particular territory.

CountryCode

 

^[A-Z]{2,2}$

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.

Request

Paginated Resource Response

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. 

Request Next Page of Results

Paginated Resource Response (Next)

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: Agree Account Access Consent

  • Step 2: Create Account Access Consent

  • 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: Agree Account Access Consent

  • Step 2: Create Account Access Consent

  • Step 3: Authorise Consent

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

Missing or Invalid Access Token Scope

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

  • Step 1: Agree Account Access Consent

  • Step 2: Create Account Access Consent

  • 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: Agree Account Access Consent

  • Step 2: Create Account Access Consent

  • 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

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

  • Step 1: Agree Account Access Consent

  • Step 2: Create Account Access Consent

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.