Version Control

Version	Date	Author	Comments
3.0-draft1	18-Apr-2018	OB R/W API Team	Initial draft for Version 3.0
3.0-draft4	29 May 2018	OB R/W API Team	UML diagram update for Amount field, and data dictionary update to reflect UML diagram update. Clarified use of Idempotency Key in endpoint table.
3.0-draft5	13 Jun 2018	OB R/W API Team	Draft5 Changes: Updated examples to change UTC to GMT to be in line with https://tools.ietf.org/html/rfc7231#page-66 Additional Balance/Type enumerations requested for InterimCleared, OpeningCleared and ClosingCleared
3.0-draft6/rc1	27 Jun 2018	OB R/W API Team	Draft6 Changes: For consistency - added a Permission Codes section to clarify expected behaviour.
3.0-draft7	17 Jul 2018	OB R/W API Team	No Change
3.0-RC2	19 Jul 2018	OB R/W API Team	No Change
3.0-RC3	06 Aug 2018	OB R/W API Team	No Change
3.0	07 Sep 2018	OB R/W API Team	This is the baseline version. No change from RC3.

Endpoints

	Resource	HTTP Operation	Endpoint	Mandatory?	Scope	Grant Type	Idempotency Key	Parameters	Request Object	Response Object
1	balances	GET	GET /accounts/{AccountId}/balances	Mandatory	accounts	Authorization Code	No			OBReadBalance1
2	balances	GET	GET /balances	Optional	accounts	Authorization Code	No	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

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	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
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 ClosingCleared Expected ForwardAvailable Information InterimAvailable InterimBooked InterimCleared OpeningAvailable OpeningBooked OpeningCleared 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
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	Available Credit 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
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}$

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 GMT
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