Contents

Version Control

VersionDateAuthorComments
1.0.001 March 2019Payments NZ API Working GroupNZ Banking Data API Specification with common elements

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



Steps

Step 1: Request account information or make a payment

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 

Step 3: Authorise consent for Third Party to access their account information or make a payment on their behalf

Step 4: Request access to the Customer's account information or make 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. Version 1.0.0 of the Payments NZ API standards are now in the public domain in 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:

Standards

The PNZ API Working Group principles for developing these API standards:

Open Banking

The principles we have applied to re-use of the UK Open Banking Standard are:

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. 

API requests and responses MUST NOT be digitally signed for implementation of the v1.x specification.

This section is for future reference only.


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.

Due diligence has been carried out to ensure that the API has the necessary fields to function with BECS payments - as per agreed scope.

We will provide further mapping guidance to ensure that differences are understood between the Open Banking Payment API standard, and BECS payments where applicable.

Status Codes

The API uses two status codes that serve two different purposes:

Additional status codes may be provided at the discretion of the API Provider.


Unique Identifiers (Id Fields)

A REST resource should have a unique identifier (e.g. a primary key) that may be used to identify the resource. These unique identifiers are used to construct URLs to identify and address specific resources.

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 option for some resources.

An API Provider that chooses to populate optional Id fields must ensure that the values are unique and immutable.

Definition of Optionality

For endpoints and fields within each resource, the following definitions apply:

  • 'Mandatory' endpoints or fields marked must be implemented by the API Provider.
  • 'Optional' endpoints may be implemented by the API Provider.

Notes

  1. API Providers are free to decide whether to implement any of the ‘Optional’ endpoints and fields.
  2. API Providers must make documentation available to Third Parties as to which optional endpoints and fields are implemented for this specification. 

Basics

Actors

In the NZ context, there are three actors:

ActorTypeNZ Description
API ProviderLegal 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).

CustomerPersonIndividuals 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 PartyLegal 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 AbbreviationOpen Banking / PSD2 ActorNZ ActorNZ Description
AISPAccount Information Service Provider Third PartyAccredited 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.
ASPSPAccount Servicing Payment Service Provider API ProviderAn 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.
PISPPayment Initiation Service Provider Third PartyAccredited 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.
PSPPayment Service Provider (ASPSP or TPP)API Provider or Third PartyAn 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.
PSUPayment Service UserCustomerA 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.
TPPThird 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).

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:

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:


Header ValueNotesPOST RequestsGET RequestsDELETE Requests
x-fapi-financial-id

The unique id of the API Provider to which the request is issued.

The unique id will be issued by PNZ.

If provided it will be ignored by the API Provider.

Not for v1.x

Not for v1.x

Not for v1.x

x-fapi-customer-last-logged-time

The time when the Customer last logged in with the Third Party.

OptionalOptionalOptional
x-fapi-customer-ip-address

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

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

OptionalOptionalOptional
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, this comprises of either the Basic / Bearer Authentication Schemes.

MandatoryMandatoryMandatory
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 415 Unsupported Media Type.

MandatoryDo not useDo not use
Accept

Standard HTTP Header; Determine the Content-Type that is required from the Server.

If specified, it must indicate that the only a JSON response is accepted (e.g by setting the value to application/json) as a content header for all endpoints that respond with JSON.

For 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 any other value, API Provider must respond with a 406 Not Acceptable.

If not specified, default is application/json

OptionalOptionalOptional
x-idempotency-key

Custom HTTP Header; Unique request identifier to support idempotency.

Mandatory for POST requests to idempotent resource end-points.

Must not be specified for other requests.

Conditionally MandatoryDo not useDo not use
x-jws-signature

Header containing a detached JWS signature of the body of the payload.

If provided will be ignored by the API Provider

Not for v1.xNot for v1.xNot for v1.x


(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:

Response Headers


Header ValueNotesMandatory ?
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 x-fapi-interaction-id to the value received from the corresponding fapi client request header or to aRFC4122UUID value if the request header was not provided to track the interaction.

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 POSTReturned by GETReturned by DELETE
Query completed successfully200 OK
NoYesNo
Normal execution. The request has succeeded.201 CreatedThe operation results in the creation of a new resource.YesNoNo
Delete operation completed successfully204 No Content
NoNoYes

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

400 Bad RequestThe requested operation will not be carried out.YesYesYes

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.

YesYesYes

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.

YesYesYes
The Third Party tried to access the resource with a method that is not supported.405 Method Not Allowed
YesYesYes
The request contained an Accept header that requested a content-type other than application/json and a character set other than UTF-8406 Not Acceptable
YesYesYes
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.

YesYesYes
Something went wrong on the API gateway or micro-service500 Internal Server ErrorThe operation failed.YesYesYes
The Third Party tried to access a resource that has not been implemented by the API Provider501 Not Implemented
YesYesYes


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:


SituationRequestResponse
Third Party attempts to retrieve a payment with an PaymentId that does not existGET /payments/1001403 (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-debits501 (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:

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:

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:

Message Signing


Important

API requests and responses MUST NOT be digitally signed for implementation of the v1.x specification.

This section is for future reference only.

Pagination

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

In such a situation, the API Provider MUST:

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:

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:

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.

Error Condition

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.

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:

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

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

Data Dictionary

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

EndUserAppName0..1NZRisk1/EndUserAppNameName of the end user facing application.Max70Text

EndUserAppVersion0..1NZRisk1/EndUserAppVersionVersion of the end user facing application.Max14Text

PaymentContextCode0..1NZRisk1/PaymentContextCodeSpecifies the payment contextOBExternalPaymentContext1CodeBillPayment
EcommerceGoods
EcommerceServices
Other
PersonToPerson

MerchantName0..1NZRisk1/MerchantNameName of the merchant.Max70Text

MerchantNZBN0..1NZRisk1/MerchantNZBNNZ business number for the merchant.Max70Text

MerchantCategoryCode0..1NZRisk1/MerchantCategoryCodeCategory code conform to ISO 18245, related to the type of services or goods the merchant provides for the transaction.Min3Max4Text

MerchantCustomerIdentification0..1NZRisk1/MerchantCustomerIdentificationThe unique customer identifier of the Customer with the merchant.Max70Text

GeoLocation0..1NZRisk1/GeoLocationLocation of the end-user on the Earth specified by two numbers representing vertical and horizontal position.NZGeoLocation1

Latitude1..1NZRisk1/GeoLocation/LatitudeLatitude measured in decimal format.Max14Text
^-?\d{1,3}\.\d{1,8}$
Longitude1..1NZRisk1/GeoLocation/LongitudeLongitude measured in decimal format.Max14Text
^-?\d{1,3}\.\d{1,8}$
DeliveryAddress0..1NZRisk1/DeliveryAddressInformation that locates and identifies a specific address, as defined by postal services or in free format text.PostalAddress18

AddressLine0..2NZRisk1/DeliveryAddress/AddressLineInformation that locates and identifies a specific address, as defined by postal services, that is presented in free format text.Max70Text

StreetName0..1NZRisk1/DeliveryAddress/StreetNameName of a street or thoroughfare.Max70Text

BuildingNumber0..1NZRisk1/DeliveryAddress/BuildingNumberNumber that identifies the position of a building on a street.Max16Text

PostCode0..1NZRisk1/DeliveryAddress/PostCodeIdentifier consisting of a group of letters and/or numbers that is added to a postal address to assist the sorting of mail.Max16Text

TownName1..1NZRisk1/DeliveryAddress/TownNameName of a built-up area, with defined boundaries, and a local government.Max35Text

CountrySubDivision0..2NZRisk1/DeliveryAddress/CountrySubDivisionIdentifies a subdivision of a country, for instance state, region, county.Max35Text

Country1..1NZRisk1/DeliveryAddress/CountryNation 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.


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:

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

participant "Customer" as Cx
participant "Third Party" as 3P
participant "API Provider\nAuthorisation Server" as APIProviderAS
participant "API Provider\nResource Server" as APIProviderRS
alt Request data with a missing or expired access-token
3P <-> APIProviderRS: Establish TLS 1.2 MA
3P <-> APIProviderRS: GET /accounts
APIProviderRS -> 3P: HTTP 401 (Unauthorized)
3P -> APIProviderRS: GET /accounts/{AccountId}/transactions
APIProviderRS -> 3P: HTTP 401 (Unauthorized)
end alt

Incomplete or Malformed Request Payload

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

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


participant "Customer" as Cx
participant "Third Party" as 3P
participant "API Provider\nAuthorisation Server" as APIProviderAS
participant "API Provider\nResource Server" as APIProviderRS
alt Third Party attempts to setup an account request\nwith a malformed payload
3P <-> APIProviderRS: Establish TLS 1.2 MA
3P -> APIProviderRS: POST /account-requests
APIProviderRS -> 3P: HTTP 400 (Bad Request)
end alt


Missing or Invalid Access Token Scope

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

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

participant "Customer" as Cx
participant "Third Party" as 3P
participant "API Provider\nAuthorisation Server" as APIProviderAS
participant "API Provider\nResource Server" as APIProviderRS 
alt Request data with a missing or invalid\naccess-token scope
3P <-> APIProviderRS: Establish TLS 1.2 MA
3P -> APIProviderRS: GET /accounts
APIProviderRS -> 3P: HTTP 403 (Forbidden)  
3P -> APIProviderRS: GET /accounts/{AccountId}/transactions
APIProviderRS -> 3P: HTTP 403 (Forbidden)
end alt

Sudden Burst of API Requests

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

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

participant "Customer" as Cx
participant "Third Party" as 3P
participant "API Provider\nAuthorisation Server" as APIProviderAS
participant "API Provider\nResource Server" as APIProviderRS
alt Third Party attempts to retrieve an Account Resource
3P <-> APIProviderRS: Establish TLS 1.2 MA    
loop Burst of multiple GET requests
3P -> APIProviderRS: GET /accounts/{AccountId}
opt Option for API Provider to return 429 response
APIProviderRS -> 3P: HTTP 429 (Too Many Requests)
end
end
end

Failed Authorisation Consent

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

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.

participant "Customer" as Cx
participant "Third Party" as 3P
participant "API Provider\nAuthorisation Server" as APIProviderAS
participant "API Provider\nResource Server" as APIProviderRS
note over Cx, APIProviderRS
Step 1: Request account information
end note
Cx -> 3P: Get account/transaction information
note over Cx, APIProviderRS
Step 2: Setup account request
end note
3P <-> APIProviderAS: Establish TLS 1.2 MA
3P -> APIProviderAS: Initiate Client Credentials Grant
APIProviderAS -> 3P: access-token
3P <-> APIProviderRS: Establish TLS 1.2 MA
3P -> APIProviderRS: POST /account-requests
APIProviderRS -> 3P: HTTP 201 (Created), AccountRequestId
3P -> Cx: HTTP 302 (Found), Redirect (AccountRequestId)
note over Cx, APIProviderRS
Step 3: Failed authorise consent
end note
Cx -> APIProviderAS: Follow redirect (AccountRequestId)
Cx -> APIProviderAS: Invalid Credentials
APIProviderAS -> Cx: HTTP 302 (Found), Redirect (error)
Cx -> 3P: Follow redirect (error)
3P -> Cx : Error Response