ofOpen Finance Guide
GlossarySTETBlogContact
AISP

get/accounts/{accountResourceId}/balances

Retrieval of an account balances report (AISP)

OAuth2 scopes: aisp, aisp

Description

This call returns a set of balances for a given PSU account that is specified by the AISP through an account resource Identification

Prerequisites

  • The TPP was registered by the Registration Authority for the AISP role
  • The TPP and the PSU have a contract that was enrolled by the ASPSP
    • At this step, the ASPSP has delivered an OAUTH2 "Authorization Code" or "Resource Owner Password" access token to the TPP (cf. § 3.4.2).
  • The TPP and the ASPSP have successfully processed a mutual check and authentication
  • The TPP has presented its OAUTH2 "Authorization Code" or "Resource Owner Password" access token which allows the ASPSP to identify the relevant PSU and retrieve the linked PSU context (cf. § 3.4.2) if any.
  • The ASPSP takes into account the access token that establishes the link between the PSU and the AISP.
  • The TPP has previously retrieved the list of available accounts for the PSU

Business flow

The AISP requests the ASPSP on one of the PSU's accounts. The ASPSP answers by providing a list of balances on this account.

  • The ASPSP should provide at least one balance on the account.
    • For cash account, this balance should be the accounting balance (CACC)
    • For card transactions account, the accounting balance is meaningless and must be replaced by an other type of balance (OTHR).
  • Case of no registered transaction on the account, this balance will have an amount equal to zero.
  • The ASPSP can provide other balance restitutions, e.g. instant balance, as well, if possible.
  • Actually, from the PSD2 perspective, any other balances that are provided through the Web-Banking service of the ASPSP must also be provided by this ASPSP through the API.

Parameters (18)

  • Authorizationheaderstringrequired

    Access token to be passed as a header

  • accountResourceIdpathstringrequired

    Identification of account resource to fetch

    Constraints: pattern: ^([a-zA-Z0-9_ /\-?:\()\.,']{1,100})$

  • PSU-IP-Addressheaderstring

    IP address used by the PSU's terminal when connecting to the TPP

  • PSU-IP-Portheaderstring

    IP port used by the PSU's terminal when connecting to the TPP

  • PSU-HTTP-Methodheaderstring

    Http method for the most relevant PSU’s terminal request to the TTP

  • PSU-Dateheaderstring

    Timestamp of the most relevant PSU’s terminal request to the TTP

  • PSU-GEO-Locationheaderstring

    Geographical location of the PSU as provided by the PSU mobile terminal if any to the TPP

  • PSU-User-Agentheaderstring

    "User-Agent" header field sent by the PSU terminal when connecting to the TPP

  • PSU-Refererheaderstring

    "Referer" header field sent by the PSU terminal when connecting to the TPP. Notice that an initial typo in RFC 1945 specifies that "referer" (incorrect spelling) is to be used. The correct spelling "referrer" can be used but might not be understood.

  • PSU-Acceptheaderstring

    "Accept" header field sent by the PSU terminal when connecting to the TPP

  • PSU-Accept-Charsetheaderstring

    "Accept-Charset" header field sent by the PSU terminal when connecting to the TPP

  • PSU-Accept-Encodingheaderstring

    "Accept-Encoding" header field sent by the PSU terminal when connecting to the TPP

  • PSU-Accept-Languageheaderstring

    "Accept-Language" header field sent by the PSU terminal when connecting to the TPP

  • PSU-Device-IDheaderstring

    UUID (Universally Unique Identifier) for a device, which is used by the PSU, if available. UUID identifies either a device or a device dependant application installation. In case of installation identification this ID need to be unaltered until removal from device.

  • Digestheaderstring

    Digest of the body

  • Signatureheaderstringrequired

    http-signature of the request The keyId must specify the way to get the relevant qualified certificate. It is requested that this identifier is an URL aiming to provide the relevant Qualified Certificate.

  • X-Request-IDheaderstringrequired

    Correlation header to be set in a request and retrieved in the relevant response

    Constraints: maxLength: 70

  • workspacequerystring

    Workspace to be used for processing an AISP request. If not provided, the default workspace is computed from the authentication that was used for getting the OAuth2 Access Token.

    Constraints: maxLength: 32

Responses

200

The ASPSP answers with a list of account balances

Halobject

HalBalances

HYPERMEDIA structure used for returning the list of the relevant balances for a given account to the AISP

Fields (2)

  • balancesarray<BalanceResource>required

    List of account balances

    Item: BalanceResource

    Structure of an account balance

    • namestringrequired

      Label of the balance

      Constraints: maxLength: 70

    • balanceAmountAmountTyperequired

      Structure aiming to embed the amount and the currency to be used.

      Schema: AmountType

      Structure aiming to embed the amount and the currency to be used.

      • amountnumber (float)required

        ISO20022: Amount of money to be moved between the debtor and creditor, before deduction of charges, expressed in the currency as ordered by the initiating party.

        ISO20022: Amount of money to be moved between the debtor and creditor, before deduction of charges, expressed in the currency as ordered by the initiating party.

        Constraints: pattern: `^\-{0,1}[0-9]{1,13}(\.[0-9]{0,5}){0,1}$`

      • currencyCurrencyCodeISO 4217required

        Specifies the currency of the amount or of the account.

        Schema: CurrencyCode

        Specifies the currency of the amount or of the account. 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".

        Type: string

        Constraints: pattern: `^[A-Z]{3,3}$`

    • balanceTypeBalanceStatusrequired

      Type of balance

      Schema: BalanceStatus

      CodeNameDescription
      CLBD
      		ISO20022 ClosingBookedAccounting Balance
      XPCD
      		ISO20022 ExpectedInstant Balance
      VALU
      		(None)Value-date balance
      OTHR
      		(None)Other Balance
    • lastChangeDateTimestring (date-time)ISO 8601

      Timestamp of the last change of the balance amount

    • referenceDatestring (date-time)ISO 8601

      Reference date for the balance

    • lastCommittedTransactionstring

      Identification of the last committed transaction. This is actually useful for instant balance.

      Identification of the last committed transaction. This is actually useful for instant balance.

      Constraints: maxLength: 40

204

No content.

Shared response definition: 204

400

Invalid status value

Technicalobject

Error400Model

Specific 400 error report structure

Fields (6)

  • timestampstring (date-time)ISO 8601

    current timestamp

  • statusinteger (int32)required

    HTTP error code

  • errorstring

    HTTP error text

    Constraints: maxLength: 140

  • messagestringrequired

    HTTP textual reason phrase

    Constraints: maxLength: 140

  • pathstring

    Relevant path that was used

    Constraints: maxLength: 140

  • acceptedAuthenticationApproachAuthenticationApproaches

    Can only be set by the ASPSP

    Can only be set by the ASPSP Authentication approaches that are supported by the ASPSP. The PISP can provide several choices separated by commas.

    Schema: AuthenticationApproach

    Code
    REDIRECT
    DECOUPLED
    EMBEDDED-1-FACTOR
    NONE

401

Unauthorized, authentication failure.

Technicalobject

ErrorModel

Generic error report structure

Fields (5)

  • timestampstring (date-time)ISO 8601

    current timestamp

  • statusinteger (int32)required

    HTTP error code

  • errorstring

    HTTP error text

    Constraints: maxLength: 140

  • messagestringrequired

    HTTP textual reason phrase

    Constraints: maxLength: 140

  • pathstring

    Relevant path that was used

    Constraints: maxLength: 140

403

Forbidden, authentication successful but access to resource is not allowed.

Technicalobject

ErrorModel

Generic error report structure

Fields (5)

  • timestampstring (date-time)ISO 8601

    current timestamp

  • statusinteger (int32)required

    HTTP error code

  • errorstring

    HTTP error text

    Constraints: maxLength: 140

  • messagestringrequired

    HTTP textual reason phrase

    Constraints: maxLength: 140

  • pathstring

    Relevant path that was used

    Constraints: maxLength: 140

404

Not found, no request available.

Technicalobject

ErrorModel

Generic error report structure

Fields (5)

  • timestampstring (date-time)ISO 8601

    current timestamp

  • statusinteger (int32)required

    HTTP error code

  • errorstring

    HTTP error text

    Constraints: maxLength: 140

  • messagestringrequired

    HTTP textual reason phrase

    Constraints: maxLength: 140

  • pathstring

    Relevant path that was used

    Constraints: maxLength: 140

405

Method Not Allowed.

Technicalobject

ErrorModel

Generic error report structure

Fields (5)

  • timestampstring (date-time)ISO 8601

    current timestamp

  • statusinteger (int32)required

    HTTP error code

  • errorstring

    HTTP error text

    Constraints: maxLength: 140

  • messagestringrequired

    HTTP textual reason phrase

    Constraints: maxLength: 140

  • pathstring

    Relevant path that was used

    Constraints: maxLength: 140

406

Not Acceptable.

Technicalobject

ErrorModel

Generic error report structure

Fields (5)

  • timestampstring (date-time)ISO 8601

    current timestamp

  • statusinteger (int32)required

    HTTP error code

  • errorstring

    HTTP error text

    Constraints: maxLength: 140

  • messagestringrequired

    HTTP textual reason phrase

    Constraints: maxLength: 140

  • pathstring

    Relevant path that was used

    Constraints: maxLength: 140

408

Request Timeout.

Technicalobject

ErrorModel

Generic error report structure

Fields (5)

  • timestampstring (date-time)ISO 8601

    current timestamp

  • statusinteger (int32)required

    HTTP error code

  • errorstring

    HTTP error text

    Constraints: maxLength: 140

  • messagestringrequired

    HTTP textual reason phrase

    Constraints: maxLength: 140

  • pathstring

    Relevant path that was used

    Constraints: maxLength: 140

429

Too many requests.

Technicalobject

ErrorModel

Generic error report structure

Fields (5)

  • timestampstring (date-time)ISO 8601

    current timestamp

  • statusinteger (int32)required

    HTTP error code

  • errorstring

    HTTP error text

    Constraints: maxLength: 140

  • messagestringrequired

    HTTP textual reason phrase

    Constraints: maxLength: 140

  • pathstring

    Relevant path that was used

    Constraints: maxLength: 140

500

Internal server error.

Technicalobject

ErrorModel

Generic error report structure

Fields (5)

  • timestampstring (date-time)ISO 8601

    current timestamp

  • statusinteger (int32)required

    HTTP error code

  • errorstring

    HTTP error text

    Constraints: maxLength: 140

  • messagestringrequired

    HTTP textual reason phrase

    Constraints: maxLength: 140

  • pathstring

    Relevant path that was used

    Constraints: maxLength: 140

503

Service unavailable.

Technicalobject

ErrorModel

Generic error report structure

Fields (5)

  • timestampstring (date-time)ISO 8601

    current timestamp

  • statusinteger (int32)required

    HTTP error code

  • errorstring

    HTTP error text

    Constraints: maxLength: 140

  • messagestringrequired

    HTTP textual reason phrase

    Constraints: maxLength: 140

  • pathstring

    Relevant path that was used

    Constraints: maxLength: 140

Schemas used by this endpoint

Every structure referenced by this operation, listed once. Cross-references resolve to anchors on this page.

ISO20022object

AmountType

Structure aiming to embed the amount and the currency to be used.

Fields (2)

  • amountnumber (float)required

    ISO20022: Amount of money to be moved between the debtor and creditor, before deduction of charges, expressed in the currency as ordered by the initiating party.

    ISO20022: Amount of money to be moved between the debtor and creditor, before deduction of charges, expressed in the currency as ordered by the initiating party.

    Constraints: pattern: `^\-{0,1}[0-9]{1,13}(\.[0-9]{0,5}){0,1}$`

  • currencyCurrencyCodeISO 4217required

    Schema: CurrencyCode

Technicalstring

AuthenticationApproach

Authentication approaches that can be applied. REDIRECT: the PSU is redirected by the TPP to the ASPSP which processes identification and authentication DECOUPLED: the TPP identifies the PSU and forwards the identification to the ASPSP which processes the authentication through a decoupled device EMBEDDED-1-FACTOR: the TPP identifies the PSU and forwards the identification to the ASPSP which starts the authentication. The TPP forwards one authentication factor of the PSU (e.g. OTP or response to a challenge) NONE: there is no need for the PSU to authenticate

Code
REDIRECT
DECOUPLED
EMBEDDED-1-FACTOR
NONE
Technicalarray of AuthenticationApproach

AuthenticationApproaches

List of authentication approaches

Items: AuthenticationApproach

Resourcesobject

BalanceResource

Structure of an account balance

Fields (6)

  • namestringrequired

    Label of the balance

    Constraints: maxLength: 70

  • balanceAmountAmountTyperequired

    Schema: AmountType

  • balanceTypeBalanceStatusrequired

    Schema: BalanceStatus

  • lastChangeDateTimestring (date-time)ISO 8601

    Timestamp of the last change of the balance amount

  • referenceDatestring (date-time)ISO 8601

    Reference date for the balance

  • lastCommittedTransactionstring

    Identification of the last committed transaction. This is actually useful for instant balance.

    Identification of the last committed transaction. This is actually useful for instant balance.

    Constraints: maxLength: 40

ISO20022string

BalanceStatus

Type of balance

CodeNameDescription
CLBD
ISO20022 ClosingBookedAccounting Balance
XPCD
ISO20022 ExpectedInstant Balance
VALU
(None)Value-date balance
OTHR
(None)Other Balance
ISO20022string

CurrencyCode

Specifies the currency of the amount or of the account. 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".

Technicalobject

Error400Model

Specific 400 error report structure

Fields (6)

  • timestampstring (date-time)ISO 8601

    current timestamp

  • statusinteger (int32)required

    HTTP error code

  • errorstring

    HTTP error text

    Constraints: maxLength: 140

  • messagestringrequired

    HTTP textual reason phrase

    Constraints: maxLength: 140

  • pathstring

    Relevant path that was used

    Constraints: maxLength: 140

  • acceptedAuthenticationApproachAuthenticationApproaches

    Can only be set by the ASPSP

    Can only be set by the ASPSP Authentication approaches that are supported by the ASPSP. The PISP can provide several choices separated by commas.

    Schema: AuthenticationApproaches

Technicalobject

ErrorModel

Generic error report structure

Fields (5)

  • timestampstring (date-time)ISO 8601

    current timestamp

  • statusinteger (int32)required

    HTTP error code

  • errorstring

    HTTP error text

    Constraints: maxLength: 140

  • messagestringrequired

    HTTP textual reason phrase

    Constraints: maxLength: 140

  • pathstring

    Relevant path that was used

    Constraints: maxLength: 140

Halobject

HalBalances

HYPERMEDIA structure used for returning the list of the relevant balances for a given account to the AISP

Fields (2)