Contents
| Table of Contents | ||
|---|---|---|
|
...
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. 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).
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.
| Warning | ||
|---|---|---|
| ||
API requests and responses MUST NOT be digitally signed for implementation of the v1.x specification. This section is for future reference only. |
...
| Actor | Type | NZ Description |
|---|---|---|
| API Provider | Legal Entity | 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). |
| Customer | Person | Individuals who operate retail banking accounts who make use of a PNZ API Standards-based information service or payment service. The retail banking accounts may be personal accounts or associated with businesses, trusts, etc. |
| Third Party | Legal Entity | 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). |
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:
| Open Banking Abbreviation | Open Banking / PSD2 Actor | NZ Actor | NZ Description |
|---|---|---|---|
| AISP | Account Information Service Provider | Third Party | Accredited organisations providing web and mobile applications which consume one or more API Provider’s Account Information API in a manner that complies with the Payments NZ’s API Standards. |
| ASPSP | Account Servicing Payment Service Provider | API Provider | An accredited financial institution who provides and maintains a payment account for banking customers, and provides account information APIs to one or more Third Parties in a manner that complies with the Payments NZ’s API Standards. |
| PISP | Payment Initiation Service Provider | Third Party | Accredited organisations providing web and mobile applications which consume one or more API Provider’s payment initiation APIs in a manner that complies with the Payments NZ’s API Standards. |
| PSP | Payment Service Provider (ASPSP or TPP) | API Provider or Third Party | An accredited financial institution who provides payment services to customers and provides payment initiation APIs to one or more Third Parties in a manner that complies with the Payments NZ’s API Standards. |
| PSU | Payment Service User | Customer | A person making use of a payment service as either payer, payee or both. The customer’s account may be a personal account or associated with businesses, trusts, etc. |
| TPP | Third Party Provider | Third Party | An accredited organisation that provides payment related services in a manner that complies with the Payments NZ’s 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). |
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).
...
| Header Value | Notes | Mandatory ? |
|---|---|---|
| Content-Type | Standard HTTP Header; Represents the format of the payload returned in the response. The API Provider must return Content-Type: application/json as a content header in response to requests that return a HTTP body (e.g. POST and GET requests) | Conditionally Mandatory |
| x-jws-signature | Header containing a detached JWS signature of the body of the payload. If provided will be ignored by the Third Party. | Not for v1.x |
| x-fapi-interaction-id | An RFC4122 UID used as a correlation id. The API Provider must set the response header | Mandatory |
| 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). | Optional |
Return & Error Codes
The following are the HTTP response codes for the different HTTP methods - across all API endpoints.
Situation | HTTP Status | Notes | Returned by POST | Returned by GET | Returned by DELETE |
|---|---|---|---|---|---|
| Query completed successfully | 200 OK | No | Yes | No | |
| Normal execution. The request has succeeded. | 201 Created | The operation results in the creation of a new resource. | Yes | No | No |
| Delete operation 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 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 |
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.
If an API Provider has not implemented an optional API, it must respond with a 501 (Not Implemented) for requests to that URL.
The table below illustrates some examples of expected behaviour:
| Situation | Request | Response |
|---|---|---|
| Third Party attempts to retrieve a payment with an PaymentId that does not exist | GET /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) |
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).
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 /payments/1001 where a payment resource with Id 1001 belongs to another Third Party.
- The Third Party tries to access an account/transaction resource, 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.
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.
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.
...
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
...