openapi: 3.2.0
info:
  version: 1.0.3
  title: Get Corporate Account Balances API
  description: As a corporate or business customer of the bank, I need to be able to retrieve balance information for my account(s) for a date or date range so that I can make informed cash management decisions.
  contact:
    email: info@afinis.org
    url: https://www.afinis.org
servers:
- url: https://api.afinis.org/accounts/v1
tags:
- name: Get Corporate Account Balances
paths:
  /balance:
    post:
      operationId: Get Corporate Account Balances
      tags:
      - Get Corporate Account Balances
      description: Retrieve balance information for my account(s) for a date or date range
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/badRequest'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unauthorized'
        '403':
          description: Access denied, the operation is not allowed
        '404':
          description: Not Found
        '500':
          description: Internal Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/internalServerError'
        '503':
          description: Service unavailable
      security:
      - APIKeyQueryParam: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - searchCriteria
              properties:
                agent:
                  $ref: '#/components/schemas/agent'
                searchCriteria:
                  type: array
                  items:
                    $ref: '#/components/schemas/searchCriteria'
        required: true
components:
  schemas:
    searchCriteria:
      title: SearchCriteria
      description: Defines the criteria on which the information is extracted
      type: object
      required:
      - accountIdentification
      properties:
        accountIdentification:
          $ref: '#/components/schemas/accountIdentification'
        fromDate:
          type: string
          description: Start date of the range
          example: '2020-04-29'
          minLength: 10
          maxLength: 10
        toDate:
          type: string
          description: End date of the range
          example: '2020-05-19'
          minLength: 10
          maxLength: 10
    accountIdentification:
      title: accountIdentification
      description: Unique and unambiguous identification for the account between the account owner and the account servicer.
      type: object
      required:
      - identification
      properties:
        identification:
          type: string
          description: Identification assigned by an institution
          example: '12345678'
          maxLength: 34
        isToken:
          type: string
          example: N
          default: N
          enum:
          - Y
          - N
          description: "Specifies whether the account identification is tokenized:\n  * `Y` - Account is tokenized\n  * `N` - Account is not tokenized\n"
    unauthorized:
      title: Unauthorized
      type: object
      description: 401 - Unauthorized
      required:
      - details
      properties:
        details:
          description: error details
          type: array
          items:
            $ref: '#/components/schemas/unauthorizedErrorDetails'
    internalServerErrorDetails:
      title: Internal Server Error Details
      type: object
      required:
      - errorCode
      - message
      properties:
        errorCode:
          example: 3001
          type: number
          enum:
          - 3001
          description: "A programmatic error code:\n  * `3001` - Internal Server error.\n"
        message:
          description: A human readable description of the problem
          example: Internal Server error
          type: string
    balance:
      title: Balance
      type: object
      description: Set of elements used to define the balance as a numerical representation of the net increases and decreases in an account at a specific point in time
      required:
      - amount
      - currency
      - creditDebitIndicator
      - type
      properties:
        amount:
          type: number
          example: 1.01
          maxLength: 11
        currency:
          type: string
          example: USD
          maxLength: 3
          minLength: 3
        creditDebitIndicator:
          example: CRDT
          enum:
          - CRDT
          - DBIT
          description: "Definition: Indicates whether the balance is a credit or a debit balance. A zero balance is considered to be a credit balance\n * `CRDT` - Credit\n * `DBIT` - Debit\n"
        type:
          example: OPNG
          enum:
          - CRDT
          - DBIT
          - CLSG
          - OPNG
          - CLDG
          - 1DFL
          - 2DFL
          - CCOL
          description: "Definition: Specifies the system balance type, as published in an external system balance type code set\n   * `CRDT` - Total Credits\n   * `DBIT` - Total Debits\n   * `CLSG` - Closing Available\n   * `OPNG` - Opening Available\n   * `CLDG` - Closing Ledger\n   * `1DFL` - One Day Float\n   * `2DFL` - Two Days Float\n   * `CCOL` - Closing Collected Balance\n"
    unauthorizedErrorDetails:
      title: Unauthorized Error Details
      type: object
      required:
      - errorCode
      - message
      properties:
        errorCode:
          example: 1000
          type: number
          enum:
          - 1000
          - 1001
          description: "A programmatic error code:\n  * `1000` - API key is missing, invalid or expired. \n  * `1001` - API token is invalid, expired, or account associated with key does not have access to that API.\n"
        message:
          description: A human readable description of the problem
          example: API key is missing, invalid or expired.
          type: string
    badRequestErrorDetails:
      title: Bad Request Error Details
      type: object
      required:
      - errorCode
      - message
      properties:
        errorCode:
          description: "A programmatic error code:\n  * `2000` - Invalid JSON structure.\n  * `2001` - '[Field name] is missing or invalid.'\n  * `2002` - Invalid date.\n  * `2003` - Invalid combination of fields submitted. Check the API specification for eligible combinations. \n  * `2004` - '[Field name] cannot be more than [max number] characters.'\n"
          example: 2000
          type: number
          enum:
          - 2000
          - 2001
          - 2002
          - 2003
          - 2004
        message:
          description: A human readable description of the problem
          example: Invalid JSON structure.
          type: string
    internalServerError:
      title: Internal Server Error
      description: 500 - Internal Server Error
      type: object
      required:
      - details
      properties:
        detail:
          description: error details
          type: array
          items:
            $ref: '#/components/schemas/internalServerErrorDetails'
    response:
      title: Response
      type: object
      description: 200 - Response
      required:
      - accountReport
      properties:
        agent:
          $ref: '#/components/schemas/agent'
        accountReport:
          type: array
          items:
            $ref: '#/components/schemas/accountReport'
    badRequest:
      title: Bad Request
      type: object
      description: 400 - Bad Request
      required:
      - details
      properties:
        details:
          description: error details
          type: array
          items:
            $ref: '#/components/schemas/badRequestErrorDetails'
    accountReport:
      title: Account Report
      type: object
      description: Account information
      required:
      - account
      properties:
        accountIdentification:
          $ref: '#/components/schemas/accountIdentification'
        account:
          $ref: '#/components/schemas/account'
    agent:
      title: Agent
      description: Identification of a financial institution.
      type: object
      required:
      - clearingSystemIdentification
      - memberIdentification
      properties:
        clearingSystemIdentification:
          type: string
          example: USABA
          enum:
          - USABA
          description: "Specification of a pre-agreed offering between clearing agents or the channel through which the payment instruction is processed: \n * `USABA` - Routing Transit number assigned by the ABA for US financial Institutions. \n"
        memberIdentification:
          type: string
          maxLength: 35
          example: 061103852
    account:
      title: Account
      type: object
      description: Requested information on the account.
      required:
      - currency
      - balance
      properties:
        type:
          type: string
          example: CASH
          enum:
          - CACC
          - CASH
          - CHAR
          - CISH
          - COMM
          - CPAC
          - LLSV
          - LOAN
          - MGLD
          - MOMA
          - NREX
          - ODFT
          - ONDP
          - OTHR
          - SACC
          - SLRY
          - SVGS
          - TAXE
          - TRAN
          - TRAS
          description: "Specifies the nature, or use, of the cash account:\n   * `CACC` -   Account used to post debits and credits when no specific account has been nominated.\n   * `CASH` -   Account used for the payment of cash.\n   * `CHAR` -   Account used for charges if different from the account for\n   payment.\n   * `CISH` -   Account used for payment of income if different from the current cash account\n   * `COMM` -   Account used for commission if different from the account\n   for payment.\n   * `CPAC` -   Account used to post settlement debit and credit entries on behalf of a designated Clearing Participant.\n   * `LLSV` -   Account used for savings with special interest and withdrawal terms.  \n   * `LOAN` -   Account used for loans.\n   * `MGLD` -   Account used for a marginal lending facility.\n   * `MOMA` -   Account used for money markets if different from the cash\n   account.\n   * `NREX` -   Account used for non-resident external.\n   * `ODFT` -   Account is used for overdrafts.\n   * `ONDP` -   Account used for overnight deposits.\n   * `OTHR` -   Account not otherwise specified. \n   * `SACC` -   Account used to post debit and credit entries, as a result of transactions cleared and settled through a specific clearing and settlement system.\n   * `SLRY` -   Accounts used for salary payments.\n   * `SVGS` -   Account used for savings.\n   * `TAXE` -   Account used for taxes if different from the account for\n   payment.\n   * `TRAN` -   A transacting account is the most basic type of bank account that you can get. The main difference between transaction and cheque accounts is that you usually do not get a cheque book with your transacting account and neither are you offered an overdraft facility.\n   * `TRAS` -   Account used for trading if different from the current cash\n   account.\n"
        name:
          description: Name of the account.
          type: string
          maxLength: 70
          example: Example account
        currency:
          type: string
          example: USD
          maxLength: 3
          minLength: 3
        balance:
          type: array
          items:
            $ref: '#/components/schemas/balance'
        date:
          type: string
          description: Date at which the balance is or will be available.
          example: '2020-04-29'
          minLength: 10
          maxLength: 10
  securitySchemes:
    APIKeyQueryParam:
      type: apiKey
      in: query
      name: apikey