openapi: 3.0.0
info:
  version: 4.0.1
  title: Common Account API
  description: >
    This specification defines a simple API to access information about bank accounts.
    The API is supposed to be used by customers who want to get information about their
    accounts such as current balance or transactions.
    This specification uses schema definitions from the Common Data Model v1.2.1.
  termsOfService: tbd
  contact:
    email: info@common-api.ch
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
servers:
  - url: account.common-api.ch
externalDocs:
  description: Find out more about SFTI API specifications
  url: https://www.common-api.ch
security:
  - OAuth2:
      - read
      - write

tags:
  - name: accounts
    description: Third party access to bank account service considering account information and transaction data operations (JSON).
  - name: iso20022
    description: Third party access to bank account service considering camt.053 operations (XML).

paths:
  /accounts:
    get:
      tags:
        - accounts
      summary: Retrieve list of authorized accounts
      description: Return the list of all accounts accessible for the logged in user.
      parameters:
        - $ref: '#/components/parameters/authorization_in_header'
        - $ref: '#/components/parameters/clientid_in_header'
        - $ref: '#/components/parameters/correlation_in_header'
        - $ref: '#/components/parameters/agent_in_header'
        - $ref: '#/components/parameters/optional_targetid_in_header'
        - $ref: '#/components/parameters/optional_psu_ip_in_header'
        - $ref: '#/components/parameters/optional_psu_user_agent_in_header'
      responses:
        '200':
          description: Paginated list of all accounts.
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/X-Correlation-ID'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/accountItem'
        '400':
          $ref: '#/components/responses/standard400'
        '401':
          $ref: '#/components/responses/standard401'
        '403':
          $ref: '#/components/responses/standard403'
        '404':
          $ref: '#/components/responses/standard404'
        '405':
          $ref: '#/components/responses/standard405'
        '500':
          $ref: '#/components/responses/standard500'
        '501':
          $ref: '#/components/responses/standard501'
        '503':
          $ref: '#/components/responses/standard503'

  /accounts/{accountId}:
    get:
      tags:
        - accounts
      summary: Retrieve information about a single specific account
      description: Returns the accounts details of the specified account.
      parameters:
        - $ref: '#/components/parameters/path_accountId'
        - $ref: '#/components/parameters/authorization_in_header'
        - $ref: '#/components/parameters/clientid_in_header'
        - $ref: '#/components/parameters/correlation_in_header'
        - $ref: '#/components/parameters/agent_in_header'
        - $ref: '#/components/parameters/optional_targetid_in_header'
        - $ref: '#/components/parameters/optional_psu_ip_in_header'
        - $ref: '#/components/parameters/optional_psu_user_agent_in_header'
      responses:
        '200':
          description: Account details of the specified account.
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/X-Correlation-ID'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/accountItem'
        '400':
          $ref: '#/components/responses/standard400'
        '401':
          $ref: '#/components/responses/standard401'
        '403':
          $ref: '#/components/responses/standard403'
        '404':
          $ref: '#/components/responses/standard404'
        '405':
          $ref: '#/components/responses/standard405'
        '500':
          $ref: '#/components/responses/standard500'
        '501':
          $ref: '#/components/responses/standard501'
        '503':
          $ref: '#/components/responses/standard503'

  /accounts/{accountId}/balance:
    get:
      tags:
        - accounts
      summary: Retrieve account balance information
      description: |
        Returns account balance information of the specified account.
        * Returns the intraday booked balance (ITBD) for the current day, if called without a date.
        * Returns the closing booked balance (CLBD) for a specific day, if called for a past date (i.e. the closing booked balance (CLBD) of that day). In case the specified day has not yet been finalized, the response code will be 202.
      parameters:
        - $ref: '#/components/parameters/authorization_in_header'
        - $ref: '#/components/parameters/path_accountId'
        - $ref: '#/components/parameters/query_date'
        - $ref: '#/components/parameters/clientid_in_header'
        - $ref: '#/components/parameters/correlation_in_header'
        - $ref: '#/components/parameters/agent_in_header'
        - $ref: '#/components/parameters/optional_targetid_in_header'
        - $ref: '#/components/parameters/optional_psu_ip_in_header'
        - $ref: '#/components/parameters/optional_psu_user_agent_in_header'
      responses:
        '200':
          description: Account balance information of the specified account.
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/X-Correlation-ID'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/accountBalanceItem'
        '202':
          $ref: '#/components/responses/standard202'
        '204':
          $ref: '#/components/responses/standard204'
        '400':
          $ref: '#/components/responses/standard400'
        '401':
          $ref: '#/components/responses/standard401'
        '403':
          $ref: '#/components/responses/standard403'
        '404':
          $ref: '#/components/responses/standard404'
        '405':
          $ref: '#/components/responses/standard405'
        '500':
          $ref: '#/components/responses/standard500'
        '501':
          $ref: '#/components/responses/standard501'
        '503':
          $ref: '#/components/responses/standard503'

  /accounts/{accountId}/transactions:
    get:
      tags:
        - accounts
      summary: Retrieve transactions of a specific account
      description: |
        Returns the transaction list of the specified account. Only postings with status booked will be returned.
        * Returns the transaction list of the current day, if called without a date.
        * Returns the transaction list for a specific day, if called for a past date (i.e. all transactions from that day). In case the specified day is not yet finalized, the response code will be 202.
      parameters:
        - $ref: '#/components/parameters/authorization_in_header'
        - $ref: '#/components/parameters/path_accountId'
        - in: query
          name: dateFrom
          schema:
            $ref: '#/components/schemas/date'
        - in: query
          name: dateTo
          schema:
            $ref: '#/components/schemas/date'
        - in: query
          name: bookingStatus
          required: true
          schema:
            type: string
            enum:
              - booked
              - pending
              - both
        - $ref: '#/components/parameters/cursor'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/clientid_in_header'
        - $ref: '#/components/parameters/correlation_in_header'
        - $ref: '#/components/parameters/agent_in_header'
        - $ref: '#/components/parameters/optional_targetid_in_header'
        - $ref: '#/components/parameters/optional_psu_ip_in_header'
        - $ref: '#/components/parameters/optional_psu_user_agent_in_header'
      responses:
        '200':
          description: Account details of the requested account.
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/X-Correlation-ID'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/accountTransactionReport'
        '202':
          $ref: '#/components/responses/standard202'
        '204':
          $ref: '#/components/responses/standard204'
        '400':
          $ref: '#/components/responses/standard400'
        '401':
          $ref: '#/components/responses/standard401'
        '403':
          $ref: '#/components/responses/standard403'
        '404':
          $ref: '#/components/responses/standard404'
        '405':
          $ref: '#/components/responses/standard405'
        '500':
          $ref: '#/components/responses/standard500'
        '501':
          $ref: '#/components/responses/standard501'
        '503':
          $ref: '#/components/responses/standard503'

  /accounts/{accountId}/transactions/{transactionId}:
    get:
      tags:
        - accounts
      summary: Retrieve details of a specific transaction
      description: Details of the specified transaction.
      parameters:
        - $ref: '#/components/parameters/path_accountId'
        - $ref: '#/components/parameters/path_transactionId'
        - $ref: '#/components/parameters/authorization_in_header'
        - $ref: '#/components/parameters/clientid_in_header'
        - $ref: '#/components/parameters/correlation_in_header'
        - $ref: '#/components/parameters/agent_in_header'
        - $ref: '#/components/parameters/optional_targetid_in_header'
        - $ref: '#/components/parameters/optional_psu_ip_in_header'
        - $ref: '#/components/parameters/optional_psu_user_agent_in_header'
      responses:
        '200':
          description: Account details of the requested account.
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/X-Correlation-ID'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/accountTransactionEntry'
        '400':
          $ref: '#/components/responses/standard400'
        '401':
          $ref: '#/components/responses/standard401'
        '403':
          $ref: '#/components/responses/standard403'
        '404':
          $ref: '#/components/responses/standard404'
        '405':
          $ref: '#/components/responses/standard405'
        '500':
          $ref: '#/components/responses/standard500'
        '501':
          $ref: '#/components/responses/standard501'
        '503':
          $ref: '#/components/responses/standard503'

  /iso20022/statements:
    get:
      tags:
        - iso20022
      summary: Retrieve a list of resource links to account statements (camt.053)
      description: >
        Get the resources links to available account statements (camt.053).
        The returned account statements must be conform to the XML schema and
        implementation guidelines defined by Swiss Payment Standards.
      parameters:
        - $ref: '#/components/parameters/authorization_in_header'
        - $ref: '#/components/parameters/clientid_in_header'
        - $ref: '#/components/parameters/correlation_in_header'
        - $ref: '#/components/parameters/agent_in_header'
        - $ref: '#/components/parameters/optional_targetid_in_header'
        - $ref: '#/components/parameters/optional_psu_ip_in_header'
        - $ref: '#/components/parameters/optional_psu_user_agent_in_header'
      responses:
        '200':
          description: Returns a list of resource links to ISO20022 XML camt.053 messages.
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/X-Correlation-ID'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/iso20022ReportReference'
        '400':
          $ref: '#/components/responses/standard400'
        '401':
          $ref: '#/components/responses/standard401'
        '403':
          $ref: '#/components/responses/standard403'
        '404':
          $ref: '#/components/responses/standard404'
        '405':
          $ref: '#/components/responses/standard405'
        '500':
          $ref: '#/components/responses/standard500'
        '501':
          $ref: '#/components/responses/standard501'
        '503':
          $ref: '#/components/responses/standard503'

  /iso20022/statements/{reportId}:
    get:
      tags:
        - iso20022
      summary: Retrieves the designated ISO20022 XML camt.053 document.
      parameters:
        - $ref: '#/components/parameters/path_reportId'
        - $ref: '#/components/parameters/authorization_in_header'
        - $ref: '#/components/parameters/clientid_in_header'
        - $ref: '#/components/parameters/correlation_in_header'
        - $ref: '#/components/parameters/agent_in_header'
        - $ref: '#/components/parameters/optional_targetid_in_header'
        - $ref: '#/components/parameters/optional_psu_ip_in_header'
        - $ref: '#/components/parameters/optional_psu_user_agent_in_header'
      responses:
        '200':
          description: Returns the requested ISO20022 XML camt.053 message.
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/X-Correlation-ID'
          content:
            application/xml:
              schema:
                type: string
        '400':
          $ref: '#/components/responses/standard400'
        '401':
          $ref: '#/components/responses/standard401'
        '403':
          $ref: '#/components/responses/standard403'
        '404':
          $ref: '#/components/responses/standard404'
        '405':
          $ref: '#/components/responses/standard405'
        '500':
          $ref: '#/components/responses/standard500'
        '501':
          $ref: '#/components/responses/standard501'
        '503':
          $ref: '#/components/responses/standard503'

# -------------------------
# -------- Models ---------
# -------------------------
components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://example.com/oauth/authorize
          tokenUrl: https://example.com/oauth/token
          scopes:
            read: Grants read access
            write: Grants write access

  schemas:
    # /accounts
    accountItem:
      title: Account Information Item
      type: object
      required:
        - accountOwner
        - id
        - account
        - currency
      properties:
        id:
          $ref: '#/components/schemas/commonAccountId'
        account:
          $ref: '#/components/schemas/paymentIbanAccount'
        accountOwner:
          maxLength: 140
          type: string
          example: Account Owner XYZ
        currency:
          type: string
          minLength: 3
          maxLength: 3
          example: CHF
        allowedCurrencies:
          type: array
          items:
            type: string
            example: CHF
        designation:
          type: string
          maxLength: 140
          description: This element shall always be populated with the account alias, if defined, otherwise with specific bank account name (e.g. bank saving account).
          example: Firmenkonto
        accountTypeCode:
          type: string
          description: |
            Contains the account type code according to the ISO external cash account type code list. It is strongly recommended to use only the 5 codes below as follows:
            LOAN: Account used for loans (loan and mortgage accounts) - DE: Darlehenskonto, Kreditkonto, Baukreditkonto, Hypothekarkonto
            LLSV: Account used for savings with special interest and withdrawal terms (pension provision and vested benefits accounts) - DE: Vorsorge- und Freizügigkeitskonten
            SVGS: Account used for savings (all types of saving accounts)
            TRAN: Account used for transactions (all types of personal, current and payment accounts) - DE: Privat-, Kontokorent- und Zahlungsverkehrskonten
            OTHR: Account not otherwise specified (gathering pool for all other accounts)
          example: TRAN
          enum:
            - CACC
            - CARD
            - CASH
            - CHAR
            - CISH
            - COMM
            - CPAC
            - LLSV
            - LOAN
            - MGLD
            - MOMA
            - NFCA
            - NREX
            - ODFT
            - ONDP
            - OTHR
            - SACC
            - SLRY
            - SVGS
            - TAXE
            - TRAN
            - TRAS
            - VACC
        _links:
          type: object
          description: Contains the paths to additional resources for specific account (e.g. path to transactions resource).
          properties:
            self:
              type: string
              example: /accounts/550e8400-e29b-11d4-a716-446655440000
            balance:
              type: string
              example: /accounts/550e8400-e29b-11d4-a716-446655440000/balance
            transactions:
              type: string
              example: /accounts/550e8400-e29b-11d4-a716-446655440000/transactions

    commonAccountId:
      type: string
      pattern: '[A-Za-z0-9](([A-Za-z0-9._]|-){0,254}[A-Za-z0-9]){0,1}'
      maxLength: 256
      example: abc123_abcxyz.123789.abcxyz.abcxyz_abcxyz_abcxyz_abcxyz_ccccc_123abc

    accountBalanceItem:
      title: Account Balance Item
      type: object
      required:
        - date
        - balanceType
        - balance
      properties:
        date:
          $ref: '#/components/schemas/date'
        balanceType:
          type: string
          enum:
            - ITBD
            - CLBD
          example: CLBD
        balance:
          $ref: '#/components/schemas/balanceCurrencyAmount'
        _links:
          type: object
          description: Contains the paths to additional resources for specific account (e.g. path to transactions resource).
          properties:
            self:
              type: string
              example: /accounts/550e8400-e29b-11d4-a716-446655440000/balance
            account:
              type: string
              example: /accounts/550e8400-e29b-11d4-a716-446655440000
            transactions:
              type: string
              example: /accounts/550e8400-e29b-11d4-a716-446655440000/transactions

    accountTransactionReport:
      title: Account Transaction Report
      type: object
      required:
        - iban
        - entries
      properties:
        iban:
          type: string
          maxLength: 34
          pattern: '[A-Z]{2,2}[0-9]{2,2}[a-zA-Z0-9]{1,30}'
          example: CH5481230000001998736
        designation:
          type: string
          maxLength: 140
          example: Checking Account
        entries:
          type: array
          items:
            $ref: '#/components/schemas/accountTransactionEntry'
        linksPagination:
          $ref: '#/components/schemas/linksPagination'
        _links:
          type: object
          properties:
            self:
              type: string
              example: /accounts/550e8400e29b11d4a716446655440000/statements
            account:
              type: string
              example: /accounts/550e8400e29b11d4a716446655440000
            balance:
              type: string
              example: /accounts/550e8400e29b11d4a716446655440000/balance

    accountTransactionEntry:
      title: Account Transaction Entry
      type: object
      required:
        - entryId
        - transactionType
        - bookingDate
        - valueDate
        - amount
        - bankTransactionCode
        - additionalEntryInformation
      properties:
        entryId:
          type: string
          example: ENTRY123456789
        transactionType:
          $ref: '#/components/schemas/accountTransactionTransactionType'
        entryReference:
          type: string
          example: 010001628
          maxLength: 35
        entryReferenceInternalId:
          type: string
          maxLength: 35
          example: 010001628
        reversalIndicator:
          type: boolean
        bookingDate:
          $ref: '#/components/schemas/date'
        valueDate:
          $ref: '#/components/schemas/date'
        amount:
          $ref: '#/components/schemas/paymentCurrencyAmount'
        instructedAmount:
          $ref: '#/components/schemas/accountTransactionInstructedAmount'
        totalChargesAmount:
          $ref: '#/components/schemas/accountTransactionItemCharges'
        bankTransactionCode:
          $ref: '#/components/schemas/accountTransactionBankTransactionCode'
        additionalEntryInformation:
          type: string
        transactions:
          type: array
          items:
            $ref: '#/components/schemas/accountTransactionItem'

    accountTransactionItem:
      title: Account Transaction Item
      type: object
      required:
        - transactionId
        - transactionType
        - amount
      properties:
        transactionId:
          type: string
          maxLength: 35
          example: TX12345A987
        transactionType:
          $ref: '#/components/schemas/accountTransactionTransactionType'
        endToEndId:
          type: string
          maxLength: 35
          example: ENDTOENDID-01
        bankTransactionCode:
          $ref: '#/components/schemas/accountTransactionBankTransactionCode'
        amount:
          $ref: '#/components/schemas/paymentCurrencyAmount'
        instructedAmount:
          $ref: '#/components/schemas/accountTransactionInstructedAmount'
        totalChargesAmount:
          $ref: '#/components/schemas/accountTransactionItemCharges'
        counterparty:
          $ref: '#/components/schemas/accountTransactionCounterparty'
        remittanceInformation:
          $ref: '#/components/schemas/paymentRemittanceInformation'
        remittanceReference:
          $ref: '#/components/schemas/accountTransactionRemittanceReference'
        additionalTransactionInformation:
          type: string
          maxLength: 140

    linksPagination:
      title: Pagination Links
      description: Links (or cursors) returned in the answer of an API call.
      type: object
      properties:
        self:
          type: string
          description: Link / cursor to the current result set (based on the submitted pagination approach)
          example: /payment-app/api/v1/accounts/accountIDXY/transactions?offset=75&limit=25
        first:
          type: string
          description: Link / cursor to the first result set (based on the submitted pagination approach)
          example: /payment-app/api/v1/accounts/accountIDXY/transactions?offset=0&limit=25
        previous:
          type: string
          description: Link / cursor to the previous result set (based on the submitted pagination approach)
          example: /payment-app/api/v1/accounts/accountIDXY/transactions?offset=50&limit=25
        next:
          type: string
          description: Link / cursor to the next result set (based on the submitted pagination approach)
          example: /payment-app/api/v1/accounts/accountIDXY/transactions?offset=100&limit=25
        last:
          type: string
          description: Link / cursor to the last result set (based on the submitted pagination approach)
          example: /payment-app/api/v1/accounts/accountIDXY/transactions?offset=150&limit=25

    accountTransactionItemCharges:
      title: Account Transaction Item Charges
      type: object
      required:
        - amount
        - currency
      properties:
        amount:
          type: string
          pattern: '[0-9]{1,12}([.][0-9]{1,5})?'
          maxLength: 18
          example: 10.25
        currency:
          type: string
          maxLength: 3
          minLength: 3
          example: CHF
        chargeRecords:
          type: array
          items:
            $ref: '#/components/schemas/accountTransactionItemChargesRecord'

    accountTransactionItemChargesRecord:
      title: Account Transaction Item Charges Record
      type: object
      properties:
        amount:
          type: string
          pattern: '[0-9]{1,12}([.][0-9]{1,5})?'
          maxLength: 18
          example: 10.25
        currency:
          type: string
          minLength: 3
          maxLength: 3
          example: CHF
        type:
          type: string
          maxLength: 35
          example: Some type of charge
        chargesIncludedIndicator:
          type: boolean

    accountTransactionCounterparty:
      title: Account Transaction Counterparty
      type: object
      properties:
        name:
          type: string
          maxLength: 140
          example: Hans Muster
        postalAddress:
          $ref: '#/components/schemas/accountTransactionStructuredOrUnstructuredAddress'
        account:
          $ref: '#/components/schemas/accountTransactionCounterpartyAccount'
        agent:
          $ref: '#/components/schemas/accountTransactionCounterpartyAgent'

    accountTransactionCounterpartyAgent:
      title: Account Transaction Counterparty Agent
      type: object
      properties:
        bic:
          type: string
          maxLength: 11
        clearingSystemMemberIdentification:
          $ref: '#/components/schemas/commonClearingSystemMemberIdentification'

    accountTransactionInstructedAmount:
      title: Account Transaction Instructed Amount
      type: object
      required:
        - amount
        - sourceCurrency
        - targetCurrency
      properties:
        amount:
          type: string
          pattern: '[0-9]{1,12}([.][0-9]{1,5})?'
          maxLength: 18
          example: 10.25
        sourceCurrency:
          type: string
          minLength: 3
          maxLength: 3
          example: CHF
        targetCurrency:
          type: string
          minLength: 3
          maxLength: 3
          example: USD
        exchangeRate:
          type: string
          example: 0.957
          pattern: '^\d{1,11}$|^(?=\d+[.]\d+$).{3,12}$'
          maxLength: 12
        exchangeIndicator:
          type: string
          maxLength: 4
          example: MULT

    accountTransactionBankTransactionCode:
      title: Account Transaction Bank Transaction Code
      type: object
      required:
        - domainCode
        - familyCode
        - subFamilyCode
      properties:
        domainCode:
          type: string
          maxLength: 4
          example: PMNT
        familyCode:
          type: string
          maxLength: 4
          example: RCDT
        subFamilyCode:
          type: string
          maxLength: 4
          example: DMCT

    accountTransactionTransactionType:
      title: Account Transaction Transaction Type
      type: string
      enum:
        - CRDT
        - DBIT
      example: CRDT

    accountTransactionCounterpartyAccount:
      title: Account Transaction Counterparty Account
      type: object
      required:
        - type
        - identification
      properties:
        type:
          type: string
          enum:
            - IBAN
            - OTHER
        identification:
          type: string
          maxLength: 35
          example: CH9300762011623852957

    accountTransactionRemittanceReference:
      title: Account Transaction Remittance Reference
      type: object
      properties:
        type:
          type: string
          enum:
            - SCOR
            - ISR
            - QRR
        reference:
          type: string
          maxLength: 35
          example: 210000000003139471430009017

    accountTransactionStructuredAddress:
      title: Structured Postal Address for Transactions
      type: object
      required:
        - streetName
        - postCode
        - townName
      properties:
        streetName:
          type: string
          maxLength: 70
          example: Rue de la gare
        buildingNumber:
          type: string
          maxLength: 16
          example: 24
        postCode:
          type: string
          maxLength: 16
          example: 2501
        townName:
          type: string
          maxLength: 35
          example: Biel
        country:
          type: string
          maxLength: 2
          example: CH

    accountTransactionUnstructuredAddress:
      title: Unstructured Address for Transactions
      type: object
      required:
        - addressLines
      properties:
        addressLines:
          type: array
          description: max 4 lines of 70 characters
          maxItems: 4
          example:
            - Robert Schneider SA
            - Rue de la gare 24
          items:
            type: string
            maxLength: 70
        country:
          type: string
          maxLength: 2
          example: CH

    accountTransactionStructuredOrUnstructuredAddress:
      title: Common Structured or Unstructured Address
      type: object
      properties:
        structured:
          $ref: '#/components/schemas/accountTransactionStructuredAddress'
        unstructured:
          $ref: '#/components/schemas/accountTransactionUnstructuredAddress'

    balanceCurrencyAmount:
      title: Balance Currency-Amount
      type: object
      required:
        - currency
        - amount
      properties:
        currency:
          type: string
          minLength: 3
          maxLength: 3
          example: CHF
        amount:
          type: string
          pattern: '-?[0-9]{1,12}([.][0-9]{1,5})?'
          maxLength: 18
          example: 10.25

    iso20022ReportReference:
      title: ISO 20022 Report Reference
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        type:
          type: string
          enum:
            - CAMT53
        schemaVersion:
          type: string
          example: camt.053.001.01
          description: Indicates the delivered camt.053 schema version.
          pattern: camt\.053\.[0-9]{3}\.[0-9]{2}
        id:
          type: string
        account:
          $ref: '#/components/schemas/paymentIbanAccount'
        dateFrom:
          $ref: '#/components/schemas/date'
        dateTo:
          $ref: '#/components/schemas/date'

    # Shared with payments module
    paymentIbanAccount:
      title: Payment IBAN Account
      type: object
      required:
        - type
        - identification
      properties:
        type:
          type: string
          description: The allowed account identification type for the creditor account depends on the payment type. The debtor account must always be an IBAN.
          enum:
            - IBAN
        identification:
          type: string
          maxLength: 34
          pattern: '[A-Z]{2,2}[0-9]{2,2}[a-zA-Z0-9]{1,30}'
          example: CH9300762011623852957

    paymentCurrencyAmount:
      title: Payment Currency-Amount
      type: object
      required:
        - currency
        - amount
      properties:
        currency:
          type: string
          maxLength: 3
          minLength: 3
          example: CHF
        amount:
          type: string
          pattern: '[0-9]{1,12}([.][0-9]{1,5})?'
          maxLength: 18
          example: 10.25

    paymentRemittanceInformation:
      title: Payment Remittance Information
      description: Either remittanceReference or remittanceInformation must be set.
      type: string
      maxLength: 140
      example: Rechnung Nr. 408

    commonClearingSystemMemberIdentification:
      title: Common Clearing System Member Identification
      type: object
      required:
        - code
        - memberId
      properties:
        code:
          type: string
          maxLength: 5
          example: CHBCC
        memberId:
          type: string
          maxLength: 35
          example: 00230

    # ---- Common Error Response ----
    commonErrorResponse:
      title: Common Error Response
      type: object
      properties:
        type:
          $ref: '#/components/schemas/commonErrorType'
        title:
          type: string
          example: This is the general problem description
        detail:
          type: string
          example: Detailed problem description with respect to the current request, e.g., invalid account number format
        instance:
          type: string
          example: path/to/corresponding/resource

    commonErrorType:
      title: Common Error Type
      type: string
      description: Error Types for commonErrorResponse.
      enum:
        - /problems/INVALID_PAYLOAD
        - /problems/MALFORMED_PAYLOAD
        - /problems/INVALID_TOKEN
        - /problems/EXPIRED_TOKEN
        - /problems/INSUFFICIENT_PRIVILEGES
        - /problems/NO_ACCESS_TO_RESOURCE
        - /problems/RESOURCE_DOES_NOT_EXIST
        - /problems/RESOURCE_NOT_READY
        - /problems/RESOURCE_TOO_LARGE
        - /problems/WRONG_METHOD
        - /problems/OPERATION_NOT_ALLOWED
        - /problems/TECHNICAL_ERROR
        - /problems/NOT_IMPLEMENTED
        - /problems/SERVICE_UNAVAILABLE
      example: /problems/TECHNICAL_ERROR

    # ---- Date Formats ----
    date:
      type: string
      format: date
      example: 2018-04-13

    dateTime:
      type: string
      format: date-time
      example: 2018-04-13T11:11:11Z

  # ---- Global Common Header Parameters ----
  parameters:
    path_accountId:
      name: accountId
      in: path
      description: id of account
      required: true
      schema:
        maxLength: 256
        pattern: '[A-Za-z0-9](([A-Za-z0-9._]|-){0,254}[A-Za-z0-9]){0,1}'
        type: string
        example: accountId

    path_transactionId:
      name: transactionId
      in: path
      required: true
      schema:
        type: string

    path_reportId:
      name: reportId
      in: path
      description: Unique ID of the requested ISO20022 XML camt.053 document.
      required: true
      schema:
        maxLength: 35
        type: string

    query_date:
      name: date
      in: query
      description: 'The date to query, formatted as yyyy-mm-dd. Default value: current date'
      schema:
        $ref: '#/components/schemas/date'

    clientid_in_header:
      name: X-CorAPI-Client-ID
      in: header
      schema:
        type: string
      description: 'ID of the client forwarded to the provider. (SCOPE: FI)'
      required: true

    authorization_in_header:
      name: Authorization
      in: header
      description: Bearer followed by a base64 encoded OAuth access token
      required: true
      schema:
        type: string

    correlation_in_header:
      name: X-Correlation-ID
      in: header
      schema:
        type: string
      description: Unique ID (defined by the caller) which will be reflected back in the response.
      required: true

    agent_in_header:
      name: User-Agent
      in: header
      schema:
        type: string
      description: Name and version of the of the Client software.
      required: true

    optional_targetid_in_header:
      name: X-CorAPI-Target-ID
      in: header
      description: 'ID of the target, e.g., a financial institution. (SCOPE: FI - optional)'
      required: false
      schema:
        type: string

    optional_psu_ip_in_header:
      name: X-PSU-IP-Address
      in: header
      description: 'IP address of the user initiating the operation (SCOPE: FI - optional)'
      required: false
      schema:
        type: string

    optional_psu_user_agent_in_header:
      name: X-PSU-User-Agent
      in: header
      description: 'User of the client software (SCOPE: FI - optional)'
      required: false
      schema:
        type: string

    offset:
      name: offset
      in: query
      description: Optional parameter for pagination. The number of items to skip before starting to collect the result set.
      required: false
      schema:
        type: integer
        format: int32
        example: 25
        minimum: 0

    limit:
      name: limit
      in: query
      description: Optional parameter for pagination. Maximum number of entries to be returned.
      required: false
      schema:
        type: integer
        format: int32
        example: 25
        minimum: 1

    cursor:
      name: cursor
      in: query
      description: Optional parameter for pagination. An opaque string value used for pagination.
      required: false
      schema:
        type: string
        example: cursorIDxyz

  # ---- Response Headers - used by Standard Responses ----
  headers:
    Content-Language:
      description: Response language - always en
      schema:
        type: string

    Content-Type:
      description: application/problem+json; charset=utf-8 according to RFC7807
      schema:
        type: string

    X-Correlation-ID:
      description: Client defined ID from request to correlates HTTP requests between a client and server
      schema:
        type: string
        example: f058ebd6-02f7-4d3f-942e-904344e8cde5

  # ---- Responses - Standard Errors Common Data Model ----
  responses:
    standard202:
      headers:
        X-Correlation-ID:
          $ref: '#/components/headers/X-Correlation-ID'
      description: |
        Accepted - Valid request, requested data not available yet. The request may be attempted at a later time.
      content:
        application/json:
          schema:
            type: object
            # properties: ??

    standard204:
      headers:
        X-Correlation-ID:
          $ref: '#/components/headers/X-Correlation-ID'
      description: |
        No content - The server has successfully fulfilled the request. There is no content to return and never will be.

    standard400:
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
        Content-Language:
          $ref: '#/components/headers/Content-Language'
        X-Correlation-ID:
          $ref: '#/components/headers/X-Correlation-ID'
      description: |
        Bad Request - The format of the request was invalid.

        Examples:
        - InvalidPayload:
        type: /problems/INVALID_PAYLOAD
        title: Payload does not comply with API specification
        detail: Malformed JSON
        instance: path/to/corresponding/resource

        - InvalidParameter:
        type: /problems/INVALID_PAYLOAD
        title: Invalid parameter values have been detected
        detail: Sent data could not processed
        instance: path/to/corresponding/resource

        - MissingId:
        type: /problems/INVALID_PAYLOAD
        title: The payload was not valid
        detail: ID is missing
        instance: path/to/corresponding/resource
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/commonErrorResponse'

    standard401:
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
        Content-Language:
          $ref: '#/components/headers/Content-Language'
        X-Correlation-ID:
          $ref: '#/components/headers/X-Correlation-ID'
      description: |
        Unauthorized - The request has not been applied because it provides no valid authentication credentials for the target resource.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/commonErrorResponse'

    standard403:
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
        Content-Language:
          $ref: '#/components/headers/Content-Language'
        X-Correlation-ID:
          $ref: '#/components/headers/X-Correlation-ID'
      description: |
        Forbidden - A valid OAuth Token was received, but access was denied. (Depending on the security requirements, providers can return 404 instead)

        Examples:
        - InsufficientPrivileges:
        type: /problems/INSUFFICIENT_PRIVILEGES
        title: No privileges for the requested operation
        detail: Insufficient privileges for the requested operation
        instance: path/to/corresponding/resource

        - ExpiredToken:
        type: /problems/EXPIRED_TOKEN
        title: The OAuth Token is expired
        detail: The token is no longer valid
        instance: path/to/corresponding/resource

        - NoFutureDateSupported:
        type: /problems/MALFORMED_PAYLOAD
        title: Invalid parameter values have been detected
        detail: Data for date in the future cannot be requested
        instance: path/to/corresponding/resource
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/commonErrorResponse'

    standard404:
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
        Content-Language:
          $ref: '#/components/headers/Content-Language'
        X-Correlation-ID:
          $ref: '#/components/headers/X-Correlation-ID'
      description: |
        Not Found - Either the endpoint does not exist or a requested resource is not yet available (e.g., account statements)

        Examples:
        - InvalidAccounts:
        type: /problems/INSUFFICIENT_PRIVILEGES
        title: Insufficient privileges to access resource
        detail: The provided token does not grant access to the requested account
        instance: path/to/corresponding/resource

        - InvalidToken:
        type: /problems/INSUFFICIENT_PRIVILEGES
        title: Insufficient privileges to access resource
        detail: The provided token is not valid
        instance: path/to/corresponding/resource

        - WrongEndpointUrl:
        type: /problems/TECHNICAL_ERROR
        title: URL not found
        detail: The requested endpoint does not exist
        instance: path/to/corresponding/resource

        - NoIntradayDataSupported:
        type: /problems/NOT_IMPLEMENTED
        title: Feature is not implemented
        detail: This interface does not support intraday data
        instance: path/to/corresponding/resource
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/commonErrorResponse'

    standard405:
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
        Content-Language:
          $ref: '#/components/headers/Content-Language'
        X-Correlation-ID:
          $ref: '#/components/headers/X-Correlation-ID'
      description: |
        Method Not Allowed - The method received in the request-line is known by the origin server but not supported by the target resource.

        Examples:
        - NotSupportedOperation:
        type: /problems/WRONG_METHOD
        title: This HTTP operation is not allowed on this endpoint
        detail: Only GET operations are allowed
        instance: path/to/corresponding/resource
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/commonErrorResponse'

    standard500:
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
        Content-Language:
          $ref: '#/components/headers/Content-Language'
        X-Correlation-ID:
          $ref: '#/components/headers/X-Correlation-ID'
      description: |
        Internal Server Error - The server encountered an unexpected condition that prevented it from fulfilling the request.

        Examples:
        - TechnicalServerError:
        type: /problems/TECHNICAL_ERROR
        title: Technical error on server side
        detail: Processing yielded a technical error
        instance: path/to/corresponding/resource

        - ResourceTooLarge:
        type: /problems/RESOURCE_TOO_LARGE
        title: Generated resource was too large
        detail: The generated resource exceeded the size limit
        instance: path/to/corresponding/resource
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/commonErrorResponse'

    standard501:
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
        Content-Language:
          $ref: '#/components/headers/Content-Language'
        X-Correlation-ID:
          $ref: '#/components/headers/X-Correlation-ID'
      description: |
        Not Implemented - The server does not support the functionality required to fulfill the request.

        Examples:
        - EndpointNotImplemented:
        type: /problems/NOT_IMPLEMENTED
        title: Target endpoint is not implemented
        detail: This endpoint is not implemented
        instance: path/to/corresponding/resource
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/commonErrorResponse'

    standard503:
      headers:
        Content-Type:
          $ref: '#/components/headers/Content-Type'
        Content-Language:
          $ref: '#/components/headers/Content-Language'
        X-Correlation-ID:
          $ref: '#/components/headers/X-Correlation-ID'
      description: |
        Service Unavailable - The server is currently unable to handle the request due to a temporary overload or scheduled maintenance.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/commonErrorResponse'