Contents
Table of Contents | ||
---|---|---|
|
...
Version | Date | Author | Comments |
---|---|---|---|
1.0.16 Dec 20180 | 01 March 2019 | Payments NZ API Working Group | This is the baseline version resulting from restructuring into NZ Banking Data API Specification with common elements |
...
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
...