Balances v2.0.0
Version Control
| Version | Date | Author | Comments |
|---|---|---|---|
| 2.0-rc2 | Open Banking Read/Write API Team | This is the initial version following specification restructuring. Updates:
| |
| 2.0-rc3 | Open Banking Read/Write API Team | This is the initial version for release candidate 3 Updates:
| |
| 2.0.0 | Open Banking Read/Write API Team | This is the baseline version. No changes from v2.0-rc3. |
Endpoints
| Resource | HTTP Operation | Endpoint | Mandatory? | Scope | Grant Type | Idempotent | Parameters | Request Object | Response Object | |
|---|---|---|---|---|---|---|---|---|---|---|
| 1 | balances | GET | GET /accounts/{AccountId}/balances | Mandatory | accounts | Authorization Code | OBReadBalance1 | |||
| 2 | balances | GET | GET /balances | Optional | accounts | Authorization Code | Pagination | OBReadBalance1 |
GET /accounts/{AccountId}/balances
An AISP may retrieve the account balance information resource for a specific AccountId (which is retrieved in the call to GET /accounts).
GET /balances
If an ASPSP has implemented the bulk retrieval endpoints - an AISP may optionally retrieve the account information resources in bulk.
This will retrieve the resources for all authorised accounts linked to the account-request.
Data Model
The OBReadBalance1 object will be used for the call to:
- GET /accounts/{AccountId}/balances
- GET /balances
Resource Definition
This resource represents the net increases and decreases in an account (AccountId) at a specific point in time.
An account (AccountId) may have multiple balance types (these follow the standard ISO 20022 balance type enumerations). If an ASPSP includes a credit line in an available balance - then the balance representation will have a section for the credit line amount and type.
UML Diagram
Notes:
- Multiple balances may be returned (each with a different value for Type) for an account. This is for ASPSPs that show multiple balances in their online channels.
- The CreditLine section may 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 ASPSP systems - the time portion of the DateTime element will be defaulted to 00:00:00+00:00
Data Dictionary
| Name | Occurrence | XPath | EnhancedDefinition | Class | Codes | Pattern |
|---|---|---|---|---|---|---|
| OBReadBalance1 | OBReadBalance1 | OBReadBalance1 | ||||
| Data | 1..1 | OBReadBalance1/Data | OBReadDataBalance1 | |||
| Balance | 1..n | OBReadBalance1/Data/Balance | Set of elements used to define the balance details. | 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 | ||
| Amount | 1..1 | OBReadBalance1/Data/Balance/Amount | Amount of money of the cash balance. | ActiveOrHistoricCurrencyAndAmount | ||
| 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}$ | |
| 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 | ||
| 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 | ||
| Amount | 0..1 | OBReadBalance1/Data/Balance/CreditLine/Amount | Amount of money of the credit line. | ActiveOrHistoricCurrencyAndAmount | ||
| 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}$ | |
| Type | 0..1 | OBReadBalance1/Data/Balance/CreditLine/Type | Limit type, in a coded form. | OBExternalLimitType1Code | Available Credit Emergency Pre-Agreed Temporary |
Enumerations
| 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 | Available balance calculated in the course of the account servicer's business day, at the time specified, and subject to further changes during the business day. The interim balance is calculated on the basis of booked credit and debit items during the calculation time/period specified. |
| OBBalanceType1Code | InterimBooked | Balance calculated in the course of the account servicer's business day, at the time specified, and subject to further changes during the business day. The interim balance is calculated on the basis of booked credit and debit items during the calculation time/period specified. |
| OBBalanceType1Code | OpeningAvailable | Opening balance of amount of money that is at the disposal of the account owner on the date specified. |
| OBBalanceType1Code | OpeningBooked | Book balance of the account at the beginning of the account reporting period. It always equals the closing book balance from the previous report. |
| 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 |
| OBExternalLimitType2Code | Pre-Agreed | The amount of an arranged lending limit that has been agreed with the account holder |
| OBExternalLimitType2Code | Temporary | The amount of a temporary lending limit that has been agreed with the account holder |
| OBExternalLimitType2Code | 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 |
| OBExternalLimitType2Code | Credit | The amount of a credit limit that has been agreed with the account holder |
| OBExternalLimitType2Code | Available | The amount of credit limit available to the account holder |
Usage Examples
Specific Account
Request
Get Account Balances Request
GET /accounts/22289/balances HTTP/1.1 Authorization: Bearer Az90SAOJklae x-fapi-financial-id: OB/2017/001 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
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": "GBP"
},
"CreditDebitIndicator": "Credit",
"Type": "InterimAvailable",
"DateTime": "2017-04-05T10:43:07+00:00",
"CreditLine": [
{
"Included": true,
"Amount": {
"Amount": "1000.00",
"Currency": "GBP"
},
"Type": "Pre-Agreed"
}
]
}
]
},
"Links": {
"Self": "https://api.alphabank.com/open-banking/v2.0/accounts/22289/balances/"
},
"Meta": {
"TotalPages": 1
}
}
Bulk
Request
Get Balances Request
GET /balances HTTP/1.1 Authorization: Bearer Az90SAOJklae x-fapi-financial-id: OB/2017/001 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
Response
Get 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": "GBP"
},
"CreditDebitIndicator": "Credit",
"Type": "InterimAvailable",
"DateTime": "2017-04-05T10:43:07+00:00",
"CreditLine": [
{
"Included": true,
"Amount": {
"Amount": "1000.00",
"Currency": "GBP"
},
"Type": "Pre-Agreed"
}
]
},
{
"AccountId": "31820",
"Amount": {
"Amount": "57.36",
"Currency": "GBP"
},
"CreditDebitIndicator": "Debit",
"Type": "InterimBooked",
"DateTime": "2017-05-02T14:22:09+00:00"
}
]
},
"Links": {
"Self": "https://api.alphabank.com/open-banking/v2.0/balances/"
},
"Meta": {
"TotalPages": 1
}
}
© Open Banking Limited 2019 | https://www.openbanking.org.uk/open-licence | https://www.openbanking.org.uk