openapi: 3.0.0
info:
  title: Cash Queries PoC API
  description: >
    T2S Cash Queries API provides NCBs, settlement banks and payment banks, with the possibility to access cash services information.
  version: 1.0.0
tags:
  - name: Cash Account Balances
    description: >
      Cash Account Balances queries provides NCBs, settlement banks and payment banks,
      in accordance with their access rights, with the possibility to query
      the balances of T2S dedicated cash accounts.
servers:
  - description: URL for PoC in the Swift Pilot environment.
    url: https://api-test.swiftnet.sipn.swift.com/ecb-cashqueries/v1

security:
  - oauthBearerToken: []
paths:
  /cash-account-balance/{account-number}:
    get:
      tags:
        - Cash Account Balances
      description: |
        Detailed information on the cash balances for a T2S Dedicated Cash Account (DCA) owner, i.e. a party which is a payment or central bank.
        
        During the Start of Day, when the CRDM data is being replicated in the Settlement domain, only the cash balance data available at the End-of-Day of the previous business day is returned. The cash balance data for the new business day is available as of the end of the CRDM data replication.

        This operation is not relevant for CSD or CSD participant users.
      summary: Get Dedicated Cash Account Balances 
      operationId: getDCACashBalances
      parameters:
        - name: x-userContext
          in: header
          description: User context is in base64 format. It will include the institution BIC. Participants do not need to send this value. This will be populated at Network Level.
          required: false
          schema:
            type: string
            format: byte
          example: eyJhbGciOiJSUzI1NiIsImtpZCI6ImN1cmwgLXYgbGRhcDovL0RJUkwwMS5zd2lmdG5ldC5zaXBuLnN3aWZ0LmNvbTozODkvY249dHNzY2hhbm5lbCxvPXN3bGliZWIzLG89c3dpZnQ/dXNlckNlcnRpZmljYXRlIiwidHlwIjoiSldUIn0=
        - name: X-T2S-UserRef
          in: header
          description: Party or User as base64Url format
          required: true
          style: simple
          explode: false
          schema:
            type: string      
        - name: account-number
          in: path
          description: Dedicated Cash Account Number
          required: true
          schema:
            type: string
        - name: business-date
          in: query
          description: |
            Business date of the balance.
            If no business date is provided, the current business date of T2S is used.
          required: false
          schema:
            type: string
            format: date
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CashAccountBalances'
        "404":
          description: Account Not Found
        "401":
          description: User Not Authorized
        default:
          description: Payload Error
components:
  schemas:
    CashAccount:
      description: >
        Cash Account basic information.
      properties:
        accountTechId:
          type: integer
          description: Account Technical Id, as assigned by T2S
        accountNumber:
          type: string
          minLength: 1
          maxLength: 34
          description: Account Number
        accountType:
          type: string
          enum: ["CSHA", "NCBA", "RTGS"]
          description: |
            Account Type
            - CSHA: T2S Dedicated Cash Account
            - NCBA: T2S Central Bank Account
            - RTGS: RTGS Dedicated Transit Account
        currency:
          type: string
          description: Account Currency
          pattern: "[A-Z]{3,3}"
        ownerParentBic:
          type: string
          description: Account Owner Parent BIC
        ownerPartyBic:
          type: string
          description: Account Owner Party BIC
    CashBalance:
      description: >
        Cash Account Balance, per restriction type
      properties:
        restrictionTypeCode:
          type: string
          description: Code of the restriction type of the cash balance.
        restrictionTypeName:
          type: string
          description: Name of the restriction type of the cash bal-ance.
#Account Balance amount per Restriction Type
        amount:
          type: integer
          description: Amount of the cash balance.
        dateTime:
          type: string
          format: date-time
          description: Date and time of the last movement related to the cash balance.
    CashAccountBalances:
      type: object
      description: Cash Account Balances Info, including basic account info, and basic details for each balance, per restriction type.
      properties:
        accountInfo:
          description: Account Information
          $ref: '#/components/schemas/CashAccount'
        businessDate:
          type: string
          format: date
          description: Business date of the balance.
        totalAmount:
          type: integer
          description: Total amount of cash for the aggregated cash balances
        balances:
          type: array
          items:
            description: Balance info by type
            $ref: '#/components/schemas/CashBalance'

###########################
#  Security Definition    #
###########################
  securitySchemes:
    oauthBearerToken:
      type: http
      scheme: bearer
      bearerFormat: opaque OAuth 2.0
      description: |
        The access token obtained as a result of OAuth 2.0 flows. SWIFT supports two OAuth grant types for consumption depending on the environment where the API is exposed.

        * MV-SIPN - jwt-bearer grant type [RFC 7523](https://tools.ietf.org/html/rfc7523) with Signed JWT assertion
        * Internet - Password grant type with license credentials.

        This API uses JWT-Bearer grant type.

        Please visit [SWIFT OAuth Token API](https://developer.swift.com/swift-oauth-token-api) page for more information and examples on how to generate an OAuth token.

        In this declaration only the basic security element to transport the bearer token of an OAuth2 process is declared.