Open banking APIs for developers

Base URI: https://apis.openbanking.prod.kiwibank.co.nz/open-banking-nz/v3.0/

These endpoints are universal across both Kiwibank and NZHL customer realms. Authorisation is controlled via the IDP used during authentication.

Your design flows must comply with Kiwibank’s timeout constraints across all authentication flows.

Kiwibank supports the following OpenID Connect (OIDC) authentication flows:

• Authorization Code Flow
• Hybrid Flow (primarily for v2.3 compatibility)
• CIBA (Client Initiated Backchannel Authentication)

Authenticating as a Confidential Client

All TPPs must authenticate as confidential clients using:

• private_key_jwt as specified in Section 9 of the OpenID Connect Core specification

Key points:

• Client authentication is performed using a signed JWT
• JWTs must be signed using PS512
• The signing key must correspond to the public key registered in the client’s JWKS

CIBA Authentication

We support CIBA with Ping & Poll mode, suitable for decoupled authentication journeys.

Supported CIBA Hints

The following CIBA hint types are supported:

• id_token_hint

CIBA Mode

• Ping
• Poll

Kiwibank provides open banking APIs for:

• Kiwibank customers
• NZHL customers

Both customer groups share the same open banking API endpoint but use different IDP realms.

Third-party providers must direct authentication requests to the correct IDP based on the customer being authenticated.

Supported JWS Algorithms

All request objects, client assertions, and signed payloads must use: PS512.

Note: Other algorithms are not supported.

Required changes for TPPs using v2.3 compatibility mode

If you’re a TPP using v2.3 compatibility mode to connect to Kiwibank’s v3 endpoints, you’ll need to implement a few required changes. These ensure your integration works correctly and avoids issues in compatibility mode.

1. Extended identifier field lengths

• The account and payment objects must support identifier fields of up to 128 characters.
• This is an increase from the previous limit of 40 characters, and failure to accommodate this will result in fatal errors as the identifiers issued by Kiwibank may be longer than 40 characters.
  

2. Updated accountSubType enumeration

The accountSubType field in the account object has been updated to align with Version 3.

Added values:

• Lending
• Transactions

TPPs must ensure their systems can handle these updated enumerations.

3. Mandatory claims in Hybrid Flow Request Object

• When using the Hybrid Authentication Flow, the Request Object JWS must include two mandatory claims:
  • exp (Expiration Time)
  • nbf (Not Before Time)
• These claims are required for the request to be accepted by Kiwibank’s authorisation server. Missing claims will result in request rejection.
• Example: Request Object JWS (non-normative)

Below is an example of a Request Object JWS used in the Hybrid Flow. This example is not base64-encoded and is provided for illustrative purposes only.

Transaction API: credit card date range limits

The Transaction API applies specific limits to credit card accounts when querying date ranges. These limits do not apply to other account types.

Statement endpoints are unavailable until 1 December 2026.

What this means

• Clients cannot retrieve more than six months of credit card transaction data in a single API call
• To access longer periods (within the two‑year limit), consumers must split requests into multiple sequential queries

Recommendation

Developers should implement logic to segment large date ranges into multiple 6‑month intervals and aggregate the results client-side to ensure complete data retrieval.