Version Control
Version | Date | Author | Comments |
|---|---|---|---|
2.0.0 | Payments NZ API Working Group | Baseline | |
2.1-draft1 |
| Updated:
Removed:
| |
2.1-rc2 | Updated:
| ||
2.1.1 | Patch update to Swagger specification to BECSRemittance - DebtorReference and CreditorReference - specify | ||
2.1.2 |
| Patch update to Swagger to reflect /wiki/spaces/PaymentsDirectionAPIStandardsDevelopment/pages/1455358006, which determined that the standard error response body should be included in all non-success HTTP responses. | |
2.1.3 |
| Patch update to clarify the explanation of BookingDateTime:
was replaced with:
|
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 |
|---|---|---|---|---|---|---|---|---|
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 |
|---|---|---|---|---|---|
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. | OBCreditDebitCode | Credit |
Type | 1..1 | OBReadBalance1/Data/Balance/Type | Balance type, in a coded form. | OBBalanceType1Code | ClosingAvailable |
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. | xs:boolean | |
Type | 0..1 | OBReadBalance1/Data/Balance/CreditLine/Type | Limit type, in a coded form. | OBExternalLimitType1Code | Emergency |
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 |
|---|---|---|
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. |
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
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"
}
]
},
{
"AccountId": "31820",
"Amount": {
"Amount": "57.36",
"Currency": "NZD"
},
"CreditDebitIndicator": "Debit",
"Type": "InterimBooked",
"DateTime": "2017-05-02T14:22:09+00:00"
}
]
},
"Links": {
"Self": "https://examplebank.api.co.nz/open-banking-nz/v2.1/balances"
},
"Meta": {
"TotalPages": 1
}
}