Balances v2.3.1

Version Control

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

Response

GET Account Balances Response