1 Version Control
2 Definition
3 Endpoints
- 3.1 GET /accounts/{AccountId}/balances
- 3.2 GET /balances
4 Data Model
- 4.1 UML Diagram
- 4.2 Notes
- 4.3 Permission Codes
- 4.4 Data Dictionary
- 4.5 Enumerations
5 Usage Examples
- 5.1 Balances - Specific Account
  - 5.1.1 Request
  - 5.1.2 Response
- 5.2 Balances - Bulk
  - 5.2.1 Request
  - 5.2.2 Response

Version Control

Version	Date	Author	Comments

Version

Date

Author

Comments

2.0.0

Apr 30, 2020

Payments NZ API Working Group

Baseline

2.1-draft1

Jun 15, 2020

@Gavin Wong (Unlicensed)

Updated:

Usage Example version from v2.0 to v2.1

Definition

This resource represents the net increases and decreases in an account (AccountId) at a specific point in time.

An account (AccountId) can have multiple balance types (these follow the standard ISO 20022 balance type enumerations). If an API Provider includes a credit line in an available balance - then the balance representation will have a section for the credit line amount and type.

Endpoints

Resource	Endpoint	Mandatory?	Scope	Grant Type	Idempotency Key	Parameters	Request Object	Response Object

Resource

Endpoint

Mandatory?

Scope

Grant Type

Idempotency Key

Parameters

Request Object

Response Object

balances

GET /accounts/{AccountId}/balances

Mandatory

accounts

Redirect Flow; or

Decoupled Flow

No

OBReadBalance1

balances

GET /balances

Optional

accounts

Redirect Flow; or

Decoupled Flow

No

Pagination

OBReadBalance1

GET /accounts/{AccountId}/balances

The API endpoint allows a Third Party to retrieve the account balance information for a specific AccountId (which is retrieved in the call to GET /accounts).

The Third Party must have an access token issued by the API Provider using an authorization flow (either redirect flow or decoupled flow).

GET /balances

The API endpoint allows a Third Party to retrieve the account balances in bulk, if an API Provider has implemented the bulk retrieval endpoints.

The Third Party must have an access token issued by the API Provider using an authorization flow (either redirect flow or decoupled flow).
This will retrieve the account balances for all accounts linked to the account-access-consent.

Data Model

The OBReadBalance1 object will be used for the call to:

GET /accounts/{AccountId}/balances
GET /balances

UML Diagram

Notes

Multiple balances can be returned (each with a different value for Type) for an account. This is for API Providers that show multiple balances in their online channels.
The CreditLine section can be repeated - as multiple credit lines may be included in an available balance.
A DateTime element has been used instead of a complex choice element of Date and DateTime. Where time elements do not exist in API Provider systems - the time portion of the DateTime element will be defaulted to 00:00:00+00:00

Permission Codes

The resource requires the ReadBalances permission. The resource response payload does not differ depending on the permissions granted.

Data Dictionary

Name	Occurrence	XPath	EnhancedDefinition	Class	Codes

Name	Occurrence	XPath	EnhancedDefinition	Class	Codes
OBReadBalance1		OBReadBalance1		OBReadBalance1
Data	1..1	OBReadBalance1/Data		OBReadDataBalance1
Balance	1..n	OBReadBalance1/Data/Balance		OBCashBalance1
AccountId	1..1	OBReadBalance1/Data/Balance/AccountId	A unique and immutable identifier used to identify the account resource. This identifier has no meaning to the account owner.	Max40Text
CreditDebitIndicator	1..1	OBReadBalance1/Data/Balance/CreditDebitIndicator	Indicates whether the balance is a credit or a debit balance. Usage: A zero balance is considered to be a credit balance.	OBCreditDebitCode	Credit Debit
Type	1..1	OBReadBalance1/Data/Balance/Type	Balance type, in a coded form.	OBBalanceType1Code	ClosingAvailable ClosingBooked Expected ForwardAvailable Information InterimAvailable InterimBooked OpeningAvailable OpeningBooked PreviouslyClosedBooked
DateTime	1..1	OBReadBalance1/Data/Balance/DateTime	Indicates the date (and time) of the balance.	ISODateTime
Amount	1..1	OBReadBalance1/Data/Balance/Amount	Amount of money of the cash balance.	OBActiveOrHistoricCurrencyAndAmount
Amount	1..1	OBReadBalance1/Data/Balance/Amount/Amount	A number of monetary units specified in an active currency where the unit of currency is explicit and compliant with ISO 4217.	ActiveCurrencyAndAmount_SimpleType	^\d{1,13}\.\d{1,5}$
Currency	1..1	OBReadBalance1/Data/Balance/Amount/Currency	A code allocated to a currency by a Maintenance Agency under an international identification scheme, as described in the latest edition of the international standard ISO 4217 "Codes for the representation of currencies and funds".	ActiveOrHistoricCurrencyCode	^[A-Z]{3,3}$
CreditLine	0..n	OBReadBalance1/Data/Balance/CreditLine	Set of elements used to provide details on the credit line.	OBCreditLine1
Included	1..1	OBReadBalance1/Data/Balance/CreditLine/Included	Indicates whether or not the credit line is included in the balance of the account. Usage: If not present, credit line is not included in the balance amount of the account.	xs:boolean
Type	0..1	OBReadBalance1/Data/Balance/CreditLine/Type	Limit type, in a coded form.	OBExternalLimitType1Code	Emergency Pre-Agreed Temporary
Amount	0..1	OBReadBalance1/Data/Balance/CreditLine/Amount	Amount of money of the credit line.	OBActiveOrHistoricCurrencyAndAmount
Amount	1..1	OBReadBalance1/Data/Balance/CreditLine/Amount/Amount	A number of monetary units specified in an active currency where the unit of currency is explicit and compliant with ISO 4217.	ActiveCurrencyAndAmount_SimpleType	^\d{1,13}\.\d{1,5}$
Currency	1..1	OBReadBalance1/Data/Balance/CreditLine/Amount/Currency	A code allocated to a currency by a Maintenance Agency under an international identification scheme, as described in the latest edition of the international standard ISO 4217 "Codes for the representation of currencies and funds".	ActiveOrHistoricCurrencyCode	^[A-Z]{3,3}$

Enumerations

This section gives the definitions for enumerations used.

Code Class	Name	Definition

Code Class	Name	Definition
OBBalanceType1Code	ClosingAvailable	Closing balance of amount of money that is at the disposal of the account owner on the date specified.
OBBalanceType1Code	ClosingBooked	Balance of the account at the end of the pre-agreed account reporting period. It is the sum of the opening booked balance at the beginning of the period and all entries booked to the account during the pre-agreed account reporting period.
OBBalanceType1Code	Expected	Balance, composed of booked entries and pending items known at the time of calculation , which projects the end of day balance if everything is booked on the account and no other entry is posted.
OBBalanceType1Code	ForwardAvailable	Forward available balance of money that is at the disposal of the account owner on the date specified.
OBBalanceType1Code	Information	Balance for informational purposes.
OBBalanceType1Code	InterimAvailable	Opening booked balance, plus today's credits, plus overdraft facility (if held) minus today debits, minus uncleared funds (note: uncleared funds equal the total of uncleared banked minus any uncleared funds amount held). This is the total available funds the customer is able to access. E.g. Interim Available Balance = Opening Booked Balance + Today's Credits + Overdraft Limit - Today's Debits - Uncleared Funds
OBBalanceType1Code	InterimBooked	This balance will be calculated at individual bank level as per existing internal definitions to ensure consistency for customers. What is included in the displayed balance may differ between banks. E.g. The balance of the account at a point in time / intraday / real time when requested, which may or may not include uncleared funds.
OBBalanceType1Code	OpeningAvailable	Opening balance of amount of money that is at the disposal of the account owner on the date specified.
OBBalanceType1Code	OpeningBooked	Opening Balance of an account at the end of batch processing that interest and fees are calculated on. This is the same balance as Previously Closed Booked Balance. Includes any uncleared funds, regardless of uncleared funds limits. E.g. balance after end of day process.
OBBalanceType1Code	PreviouslyClosedBooked	Balance of the account at the previously closed account reporting period. The opening booked balance for the new period has to be equal to this balance. Usage: the previously booked closing balance should equal (inclusive date) the booked closing balance of the date it references and equal the actual booked opening balance of the current date.
OBCreditDebitCode	Credit	Operation is a credit
OBCreditDebitCode	Debit	Operation is a debit
OBExternalLimitType1Code	Pre-Agreed	The amount of an arranged lending limit that has been agreed with the account holder
OBExternalLimitType1Code	Temporary	The amount of a temporary lending limit that has been agreed with the account holder
OBExternalLimitType1Code	Emergency	The amount of an arranged lending limit that can be borrowed on top of pre-agreed lending, that has been agreed with the account holder.

Usage Examples

Balances - Specific Account

Retrieving account balances for a specific account.

Request

GET Account Balances Request

GET /accounts/22289/balances HTTP/1.1
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
x-fapi-auth-date: 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

Response

GET Account Balances Response

HTTP/1.1 200 OK
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json
 
{
  "Data": {
    "Balance": [
      {
        "AccountId": "22289",
        "Amount": {
          "Amount": "1230.00",
          "Currency": "NZD"
        },
        "CreditDebitIndicator": "Credit",
        "Type": "InterimAvailable",
        "DateTime": "2017-04-05T10:43:07+00:00",
        "CreditLine": [
          {
            "Included": true,
            "Amount": {
              "Amount": "1000.00",
              "Currency": "NZD"
            },
            "Type": "Pre-Agreed"
          }
        ]
      }
    ]
  },
  "Links": {
    "Self": "https://examplebank.api.co.nz/open-banking-nz/v2.1/accounts/22289/balances"
  },
  "Meta": {
    "TotalPages": 1
  }
}

Balances - Bulk

Retrieving account balances for all accounts linked to the account-access-consent.

Request

GET Account Balances Request

GET /balances HTTP/1.1
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
x-fapi-auth-date: 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

Payments NZ API standards

Balances v2.3.0

Version Control

Definition

Endpoints

GET /accounts/{AccountId}/balances

GET /balances

Data Model

UML Diagram

Notes

Permission Codes

Data Dictionary

Enumerations

Usage Examples

Balances - Specific Account

Request

GET Account Balances Request

Response

GET Account Balances Response

Balances - Bulk

Request

GET Account Balances Request

Response

GET Account Balances Response