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. The Open Banking standard is now in the public domain; the PNZ Version 1.0.0 of the Payments NZ API standards are not now 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 NZin read-only format and cannot currently be used in partnership with any API Provider (as defined in the specification).
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.
- 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
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
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).
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 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.
Digital signatures will facilitate non-repudiation for Open Banking APIs.
API requests and responses MUST NOT be digitally signed for implementation of the v1.x specification.
This section is for future reference only.