Algbra Balances API

openapi: 3.2.0
info:
  title: Account and Transaction API Specification Balances API
  description: Swagger for Account and Transaction API Specification
  termsOfService: https://tell.money/api_terms
  contact:
    name: Tell Connect Support
    email: tpp_support@tell.money
  version: v3.1.0
servers:
- url: https://secure.tell.systems/algbra/open-banking/v3.1/aisp
tags:
- name: Balances
paths:
  /accounts/{AccountId}/balances:
    get:
      tags:
      - Balances
      summary: Get Balances
      operationId: GetAccountsAccountIdBalances
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - $ref: '#/components/parameters/x-fapi-financial-id-Param'
      - $ref: '#/components/parameters/x-fapi-customer-last-logged-time-Param'
      - $ref: '#/components/parameters/x-fapi-customer-ip-address-Param'
      - $ref: '#/components/parameters/x-fapi-interaction-id-Param'
      - $ref: '#/components/parameters/AuthorizationParam'
      - $ref: '#/components/parameters/x-customer-user-agent-Param'
      responses:
        '200':
          $ref: '#/components/responses/200AccountsAccountIdBalancesRead'
        '400':
          $ref: '#/components/responses/400ErrorResponse'
        '401':
          $ref: '#/components/responses/401ErrorResponse'
        '403':
          $ref: '#/components/responses/403ErrorResponse'
        '405':
          $ref: '#/components/responses/405ErrorResponse'
        '406':
          $ref: '#/components/responses/406ErrorResponse'
        '429':
          $ref: '#/components/responses/429ErrorResponse'
        '500':
          $ref: '#/components/responses/500ErrorResponse'
      security:
      - PSUOAuth2Security:
        - accounts
components:
  parameters:
    x-fapi-interaction-id-Param:
      in: header
      name: x-fapi-interaction-id
      required: false
      description: An RFC4122 UID used as a correlation id.
      schema:
        type: string
    x-customer-user-agent-Param:
      in: header
      name: x-customer-user-agent
      description: Indicates the user-agent that the PSU is using.
      required: false
      schema:
        type: string
    AuthorizationParam:
      in: header
      name: Authorization
      required: false
      description: An Authorisation Token as per https://tools.ietf.org/html/rfc6750 - required for API calls but may be ommited when using Swagger UI where the "Authorize" function has been operated
      schema:
        type: string
    AccountId:
      name: AccountId
      in: path
      description: AccountId
      required: true
      schema:
        type: string
    x-fapi-customer-ip-address-Param:
      in: header
      name: x-fapi-customer-ip-address
      required: false
      description: The PSU's IP address if the PSU is currently logged in with the TPP.
      schema:
        type: string
    x-fapi-customer-last-logged-time-Param:
      in: header
      name: x-fapi-customer-last-logged-time
      required: false
      description: "The time when the PSU last logged in with the TPP. \nAll dates in the HTTP headers are represented as RFC 7231 Full Dates. An example is below: \nSun, 10 Sep 2017 19:43:31 UTC"
      schema:
        type: string
        pattern: ^(Mon|Tue|Wed|Thu|Fri|Sat|Sun), \d{2} (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) \d{4} \d{2}:\d{2}:\d{2} (GMT|UTC)$
    x-fapi-financial-id-Param:
      in: header
      name: x-fapi-financial-id
      required: true
      description: The unique id of the ASPSP to which the request is issued. The unique id will be issued by OB.
      schema:
        type: string
        default: ea01566d-f21d-49af-9d0c-b74fbe36911f
  responses:
    500ErrorResponse:
      description: Internal Server Error
      content:
        application/json; charset=utf-8:
          schema:
            $ref: '#/components/schemas/OBErrorResponse1'
    403ErrorResponse:
      description: Forbidden
    429ErrorResponse:
      description: Too Many Requests
      headers:
        Retry-After:
          description: Number in seconds to wait
          schema:
            type: integer
    406ErrorResponse:
      description: Not Acceptable
    405ErrorResponse:
      description: Method Not Allowed
    401ErrorResponse:
      description: Unauthorized
    400ErrorResponse:
      description: Bad request
      content:
        application/json; charset=utf-8:
          schema:
            $ref: '#/components/schemas/OBErrorResponse1'
    200AccountsAccountIdBalancesRead:
      description: Balances Read
      headers:
        x-fapi-interaction-id:
          description: An RFC4122 UID used as a correlation id.
          schema:
            type: string
      content:
        application/json; charset=utf-8:
          schema:
            $ref: '#/components/schemas/OBReadBalance1'
  schemas:
    OBError1:
      type: object
      properties:
        ErrorCode:
          description: Low level textual error code, e.g., UK.OBIE.Field.Missing
          type: string
          minLength: 1
          maxLength: 128
        Message:
          description: 'A description of the error that occurred. e.g., ''A mandatory field isn''t supplied'' or ''RequestedExecutionDateTime must be in future''

            OBIE doesn''t standardise this field'
          type: string
          minLength: 1
          maxLength: 500
        Path:
          description: Recommended but optional reference to the JSON Path of the field with error, e.g., Data.Initiation.InstructedAmount.Currency
          type: string
          minLength: 1
          maxLength: 500
        Url:
          description: URL to help remediate the problem, or provide more information, or to API Reference, or help etc
          type: string
      required:
      - ErrorCode
      - Message
      additionalProperties: false
      minProperties: 1
    AccountId:
      description: A unique and immutable identifier used to identify the account resource. This identifier has no meaning to the account owner.
      type: string
      minLength: 1
      maxLength: 40
    ISODateTime:
      description: "All dates in the JSON payloads are represented in ISO 8601 date-time format. \nAll date-time fields in responses must include the timezone. An example is below:\n2017-04-05T10:43:07+00:00"
      type: string
      format: date-time
    OBActiveOrHistoricCurrencyAndAmount:
      description: Amount of money of the cash balance after a transaction entry is applied to the account..
      type: object
      properties:
        Amount:
          $ref: '#/components/schemas/OBActiveCurrencyAndAmount_SimpleType'
        Currency:
          description: 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
          pattern: ^[A-Z]{3,3}$
      required:
      - Amount
      - Currency
      additionalProperties: false
    Meta:
      title: MetaData
      type: object
      description: Meta Data relevant to the payload
      properties:
        TotalPages:
          type: integer
          format: int32
        FirstAvailableDateTime:
          $ref: '#/components/schemas/ISODateTime'
        LastAvailableDateTime:
          $ref: '#/components/schemas/ISODateTime'
      additionalProperties: false
    OBExternalLimitType1Code:
      description: Limit type, in a coded form.
      type: string
      enum:
      - Available
      - Credit
      - Emergency
      - Pre-Agreed
      - Temporary
    OBErrorResponse1:
      description: An array of detail error codes, and messages, and URLs to documentation to help remediation.
      type: object
      properties:
        Code:
          description: High level textual error code, to help categorize the errors.
          type: string
          minLength: 1
          maxLength: 40
        Id:
          description: A unique reference for the error instance, for audit purposes, in case of unknown/unclassified errors.
          type: string
          minLength: 1
          maxLength: 40
        Message:
          description: Brief Error message, e.g., 'There is something wrong with the request parameters provided'
          type: string
          minLength: 1
          maxLength: 500
        Errors:
          items:
            $ref: '#/components/schemas/OBError1'
          type: array
          minItems: 1
      required:
      - Code
      - Message
      - Errors
      additionalProperties: false
    OBReadBalance1:
      type: object
      properties:
        Data:
          type: object
          properties:
            Balance:
              items:
                $ref: '#/components/schemas/OBCashBalance1'
              type: array
              description: Set of elements used to define the balance details.
              minItems: 1
          required:
          - Balance
          additionalProperties: false
        Links:
          $ref: '#/components/schemas/Links'
        Meta:
          $ref: '#/components/schemas/Meta'
      required:
      - Data
      - Links
      - Meta
      additionalProperties: false
    Links:
      type: object
      description: Links relevant to the payload
      properties:
        Self:
          type: string
          format: uri
        First:
          type: string
          format: uri
        Prev:
          type: string
          format: uri
        Next:
          type: string
          format: uri
        Last:
          type: string
          format: uri
      additionalProperties: false
      required:
      - Self
    OBBalanceType1Code:
      description: Balance type, in a coded form.
      type: string
      enum:
      - ClosingAvailable
      - ClosingBooked
      - ClosingCleared
      - Expected
      - ForwardAvailable
      - Information
      - InterimAvailable
      - InterimBooked
      - InterimCleared
      - OpeningAvailable
      - OpeningBooked
      - OpeningCleared
      - PreviouslyClosedBooked
    OBCreditLine1:
      description: Set of elements used to provide details on the credit line.
      type: object
      properties:
        Included:
          description: '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.'
          type: boolean
        Type:
          $ref: '#/components/schemas/OBExternalLimitType1Code'
        Amount:
          $ref: '#/components/schemas/OBActiveOrHistoricCurrencyAndAmount'
      required:
      - Included
      additionalProperties: false
    OBActiveCurrencyAndAmount_SimpleType:
      description: A number of monetary units specified in an active currency where the unit of currency is explicit and compliant with ISO 4217.
      type: string
      pattern: ^\d{1,13}\.\d{1,5}$
    OBCashBalance1:
      description: Set of elements used to define the balance details.
      type: object
      properties:
        AccountId:
          $ref: '#/components/schemas/AccountId'
        CreditDebitIndicator:
          type: string
          enum:
          - Credit
          - Debit
          description: "Indicates whether the balance is a credit or a debit balance. \nUsage: A zero balance is considered to be a credit balance."
        Type:
          $ref: '#/components/schemas/OBBalanceType1Code'
        DateTime:
          description: "Indicates the date (and time) of the balance.\nAll dates in the JSON payloads are represented in ISO 8601 date-time format. \nAll date-time fields in responses must include the timezone. An example is below:\n2017-04-05T10:43:07+00:00"
          type: string
          format: date-time
        Amount:
          $ref: '#/components/schemas/OBActiveOrHistoricCurrencyAndAmount'
        CreditLine:
          items:
            $ref: '#/components/schemas/OBCreditLine1'
          type: array
          description: Set of elements used to provide details on the credit line.
      required:
      - AccountId
      - CreditDebitIndicator
      - Type
      - DateTime
      - Amount
      additionalProperties: false
      minProperties: 1
  securitySchemes:
    PSUOAuth2Security:
      type: oauth2
      flows:
        authorizationCode:
          scopes:
            accounts: Ability to read Accounts information
          authorizationUrl: https://secure.tell.systems/algbra/auth/oidc/authorize
          tokenUrl: https://secure.tell.systems/algbra/auth/oidc/token
      description: OAuth flow, it is required when the PSU needs to perform SCA with the ASPSP when a TPP wants to access an ASPSP resource owned by the PSU
    TPPOAuth2Security:
      type: oauth2
      flows:
        clientCredentials:
          scopes:
            accounts: Ability to read Accounts information
          tokenUrl: https://secure.tell.systems/algbra/auth/oidc/token
      description: TPP client credential authorisation flow with the ASPSP