Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 2 Current »

Version Control

VersionDateAuthorComments
3.0-draft118-Apr-2018OB R/W API TeamInitial draft for Version 3.0
3.0-draft4 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 OB R/W API Team

Draft5 Changes:

3.0-draft6/rc1 OB R/W API Team

Draft6 Changes:

  • For consistency - added a Permission Codes section to clarify expected behaviour.
3.0-draft7 OB R/W API TeamNo Change
3.0-RC2 OB R/W API TeamNo Change
3.0-RC3 OB R/W API TeamNo Change
3.0 OB R/W API TeamThis is the baseline version. No change from RC3.

Endpoints


ResourceHTTP OperationEndpointMandatory?ScopeGrant TypeIdempotency KeyParametersRequest ObjectResponse Object
1balancesGETGET /accounts/{AccountId}/balancesMandatoryaccountsAuthorization CodeNo

OBReadBalance1
2balancesGETGET /balancesOptionalaccountsAuthorization CodeNoPagination
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

NameOccurrenceXPathEnhancedDefinitionClassCodesPattern
OBReadBalance1
OBReadBalance1
OBReadBalance1

Data1..1OBReadBalance1/Data
OBReadDataBalance1

Balance1..nOBReadBalance1/Data/BalanceSet of elements used to define the balance details.OBCashBalance1

AccountId1..1OBReadBalance1/Data/Balance/AccountIdA unique and immutable identifier used to identify the account resource. This identifier has no meaning to the account owner.Max40Text

CreditDebitIndicator1..1OBReadBalance1/Data/Balance/CreditDebitIndicatorIndicates whether the balance is a credit or a debit balance.
Usage: A zero balance is considered to be a credit balance.
OBCreditDebitCodeCredit
Debit

Type1..1OBReadBalance1/Data/Balance/TypeBalance type, in a coded form.OBBalanceType1CodeClosingAvailable
ClosingBooked
ClosingCleared
Expected
ForwardAvailable
Information
InterimAvailable
InterimBooked
InterimCleared
OpeningAvailable
OpeningBooked
OpeningCleared
PreviouslyClosedBooked

DateTime1..1OBReadBalance1/Data/Balance/DateTimeIndicates the date (and time) of the balance.ISODateTime

Amount1..1OBReadBalance1/Data/Balance/AmountAmount of money of the cash balance.OBActiveOrHistoricCurrencyAndAmount

Amount1..1OBReadBalance1/Data/Balance/Amount/AmountA number of monetary units specified in an active currency where the unit of currency is explicit and compliant with ISO 4217.ActiveCurrencyAndAmount_SimpleType

Currency1..1OBReadBalance1/Data/Balance/Amount/CurrencyA 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}$
CreditLine0..nOBReadBalance1/Data/Balance/CreditLineSet of elements used to provide details on the credit line.OBCreditLine1

Included1..1OBReadBalance1/Data/Balance/CreditLine/IncludedIndicates 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

Type0..1OBReadBalance1/Data/Balance/CreditLine/TypeLimit type, in a coded form.OBExternalLimitType1CodeAvailable
Credit
Emergency
Pre-Agreed
Temporary

Amount0..1OBReadBalance1/Data/Balance/CreditLine/AmountAmount of money of the credit line.OBActiveOrHistoricCurrencyAndAmount

Amount1..1OBReadBalance1/Data/Balance/CreditLine/Amount/AmountA number of monetary units specified in an active currency where the unit of currency is explicit and compliant with ISO 4217.ActiveCurrencyAndAmount_SimpleType

Currency1..1OBReadBalance1/Data/Balance/CreditLine/Amount/CurrencyA 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

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 GMT
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
  }
}
  • No labels