TietoEVRY Card account information service API

openapi: 3.2.0
info:
  title: Tieto OpenBanking XS2A apis - Card Card account information…
  version: 1.3.4
  description: Operations for managing card account information.
servers:
- url: http://openbanking.api.tieto.com
- url: https://openbanking.api.tieto.com
tags:
- name: Card account information service
  description: Operations for managing card account information.
paths:
  /{sandbox|live}/xs2a-premium/v1.3/card-accounts:
    get:
      tags:
      - Card account information service
      summary: 'Account info: Read Account List'
      description: Reads a list of bank accounts, with balances where required.
      operationId: getCardAccounts
      parameters:
      - $ref: '#/components/parameters/envParam'
      - name: X-API-Key
        in: header
        description: Authorisation key that can be acquired in TPP developer portal.
        required: true
        schema:
          type: string
      - name: Consent-ID
        in: header
        description: Shall be contained since “Establish Consent Transaction” was performed via this API before.
        required: true
        schema:
          type: string
          format: uuid
      - name: X-Request-ID
        in: header
        description: ID of the request, unique to the call, as determined by the initiating party.
        required: true
        schema:
          type: string
          format: uuid
      - name: PSU-IP-Address
        in: header
        description: The forwarded IP Address header field consists of the corresponding HTTP request IP Address field between PSU and TPP. If PSU presence (currently IP address) is provided with recurring consent then recurring consent counter is not incremented. Therefore account data can be gathered without limits.
        required: false
        schema:
          type: string
      - name: withBalance
        in: query
        description: If contained, this function reads the list of accessible payment accounts including the booking balance. This call will be rejected if the withBalance parameter is used in a case, where the access right on balances is not granted in the related consent
        required: false
        schema:
          type: boolean
      - name: Authorization
        in: header
        description: Is contained only, if an OAuth2 based SCA was performed in the related consent authorisation.
        required: false
        schema:
          type: string
      - name: PSU-ID
        in: header
        description: Client ID of the PSU in the bank.
        required: false
        schema:
          type: string
      - name: PSU-Corporate-ID
        in: header
        description: Corporate client ID of the PSU in the bank.
        required: false
        schema:
          type: string
      responses:
        200:
          description: No errors occurred. Return a list of card accounts. Each account's _links section is using viewBalances and viewTransactions links.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonGetCardAccountsResponse'
        400:
          description: One of mandatory parameters(headers, request body or query parameters) missing or in incorrect format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonErrorResponse'
        401:
          description: Consent expired; Consent is not valid for requested resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonErrorResponse'
        403:
          description: Consent not found; Consent not authorized by user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonErrorResponse'
        429:
          description: Consent access exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonErrorResponse'
  /{sandbox|live}/xs2a-premium/v1.3/card-accounts/{account-id}:
    get:
      tags:
      - Card account information service
      summary: 'Card account info: Read Card Account Details'
      description: Reads details about a card account, with balances where required.
      operationId: getCardAccount
      parameters:
      - $ref: '#/components/parameters/envParam'
      - name: account-id
        in: path
        description: This identification is denoting the addressed account. The account-id is retrieved by using a “Read Account List” call. The account-id is the “id” attribute of the account structure. Its value is constant at least throughout the lifecycle of a given consent.
        required: true
        schema:
          type: string
      - name: X-API-Key
        in: header
        description: Authorisation key that can be acquired in TPP developer portal.
        required: true
        schema:
          type: string
      - name: Consent-ID
        in: header
        description: Shall be contained since “Establish Consent Transaction” was performed via this API before.
        required: true
        schema:
          type: string
          format: uuid
      - name: X-Request-ID
        in: header
        description: ID of the request, unique to the call, as determined by the initiating party.
        required: true
        schema:
          type: string
          format: uuid
      - name: PSU-IP-Address
        in: header
        description: The forwarded IP Address header field consists of the corresponding HTTP request IP Address field between PSU and TPP. If PSU presence (currently IP address) is provided with recurring consent then recurring consent counter is not incremented. Therefore account data can be gathered without limits.
        required: false
        schema:
          type: string
      - name: withBalance
        in: query
        description: If contained, this function reads the list of accessible card accounts including the booking balance. This call will be rejected if the withBalance parameter is used in a case, where the access right on balances is not granted in the related consent
        required: false
        schema:
          type: boolean
      - name: Authorization
        in: header
        description: Is contained only, if an OAuth2 based SCA was performed in the related consent authorisation.
        required: false
        schema:
          type: string
      - name: PSU-ID
        in: header
        description: Client ID of the PSU in the bank.
        required: false
        schema:
          type: string
      - name: PSU-Corporate-ID
        in: header
        description: Corporate client ID of the PSU in the bank.
        required: false
        schema:
          type: string
      responses:
        200:
          description: No errors occurred. Returns a card account. In _links section viewBalances and viewTransactions links will be used
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonGetCardAccountResponse'
        400:
          description: One of mandatory parameters(headers, request body or query parameters) missing or in incorrect format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonErrorResponse'
        401:
          description: Consent expired, consent is not valid for requested resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonErrorResponse'
        403:
          description: Consent absent, consent not authorized by user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonErrorResponse'
        404:
          description: Card account not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonErrorResponse'
        429:
          description: Consent access exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonErrorResponse'
  /{sandbox|live}/xs2a-premium/v1.3/card-accounts/{account-id}/balances:
    get:
      tags:
      - Card account information service
      summary: 'Card account info: Read Balance'
      description: Reads card account data from a given card account addressed by 'account-id'.
      operationId: getCardAccountBalances
      parameters:
      - $ref: '#/components/parameters/envParam'
      - name: account-id
        in: path
        description: This identification is denoting the addressed card account. The account-id is retrieved by using a “Read Card account List” call. The account-id is the “id” attribute of the card account structure. Its value is constant at least throughout the lifecycle of a given consent.
        required: true
        schema:
          type: string
      - name: X-API-Key
        in: header
        description: Authorisation key that can be acquired in TPP developer portal.
        required: true
        schema:
          type: string
      - name: Consent-ID
        in: header
        description: Shall be contained since “Establish Consent Transaction” was performed via this API before.
        required: true
        schema:
          type: string
          format: uuid
      - name: X-Request-ID
        in: header
        description: ID of the request, unique to the call, as determined by the initiating party.
        required: true
        schema:
          type: string
          format: uuid
      - name: PSU-IP-Address
        in: header
        description: The forwarded IP Address header field consists of the corresponding HTTP request IP Address field between PSU and TPP. If PSU presence (currently IP address) is provided with recurring consent then recurring consent counter is not incremented. Therefore card account data can be gathered without limits.
        required: false
        schema:
          type: string
      - name: Authorization
        in: header
        description: Is contained only, if an OAuth2 based SCA was performed in the related consent authorisation.
        required: false
        schema:
          type: string
      - name: PSU-ID
        in: header
        description: Client ID of the PSU in the bank.
        required: false
        schema:
          type: string
      - name: PSU-Corporate-ID
        in: header
        description: Corporate client ID of the PSU in the bank.
        required: false
        schema:
          type: string
      responses:
        200:
          description: No errors occurred. Returns the card account's balances
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonGetCardAccountBalancesResponse'
        400:
          description: One of mandatory parameters(headers, request body or query parameters) missing or in incorrect format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonErrorResponse'
        401:
          description: Consent expired, consent is not valid for requested resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonErrorResponse'
        403:
          description: Consent absent, consent not authorized by user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonErrorResponse'
        404:
          description: Card account not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonErrorResponse'
        429:
          description: Consent access exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonErrorResponse'
  /{sandbox|live}/xs2a-premium/v1.3/card-accounts/{account-id}/transactions:
    get:
      tags:
      - Card account information service
      summary: 'Card account info: Read Transaction List'
      description: Reads card account data from a given card account addressed by 'account-id'.
      operationId: getCardAccountTransactions
      parameters:
      - $ref: '#/components/parameters/envParam'
      - name: account-id
        in: path
        description: This identification is denoting the addressed card account. The account-id is retrieved by using a “Read Card Account List” call. The account-id is the “id” attribute of the card account structure. Its value is constant at least throughout the lifecycle of a given consent.
        required: true
        schema:
          type: string
      - name: X-API-Key
        in: header
        description: Authorisation key that can be acquired in TPP developer portal.
        required: true
        schema:
          type: string
      - name: Consent-ID
        in: header
        description: Shall be contained since “Establish Consent Transaction” was performed via this API before.
        required: true
        schema:
          type: string
          format: uuid
      - name: X-Request-ID
        in: header
        description: ID of the request, unique to the call, as determined by the initiating party.
        required: true
        schema:
          type: string
          format: uuid
      - name: PSU-IP-Address
        in: header
        description: The forwarded IP Address header field consists of the corresponding HTTP request IP Address field between PSU and TPP. If PSU presence (currently IP address) is provided with recurring consent then recurring consent counter is not incremented. Therefore account data can be gathered without limits.
        required: false
        schema:
          type: string
      - name: dateFrom
        in: query
        description: 'ISODate

          Starting date of the transaction list

          Must not be farther then 90 days in past for recurring consent.

          Must not be farther then 7 years in past for non-recurring consent.'
        required: true
        schema:
          type: string
          format: date-time
      - name: dateTo
        in: query
        description: 'ISODate

          End date of the transaction list, default is now if not given

          Must not be farther then 90 days in past for recurring consent.

          Must not be farther then 7 years in past for non-recurring consent.'
        required: false
        schema:
          type: string
          format: date-time
      - name: bookingStatus
        in: query
        description: Filter by transaction booking status
        required: true
        schema:
          type: string
          enum:
          - booked
          - pending
          - both
      - name: withBalance
        in: query
        description: If contained, this function reads the list of accessible card accounts including the booking balance. This call will be rejected if the withBalance parameter is used in a case, where the access right on balances is not granted in the related consent
        required: false
        schema:
          type: boolean
      - name: Authorization
        in: header
        description: Is contained only, if an OAuth2 based SCA was performed in the related consent authorisation.
        required: false
        schema:
          type: string
      - name: PSU-ID
        in: header
        description: Client ID of the PSU in the bank.
        required: false
        schema:
          type: string
      - name: PSU-Corporate-ID
        in: header
        description: Corporate client ID of the PSU in the bank.
        required: false
        schema:
          type: string
      responses:
        200:
          description: No errors occurred. Returns card account's transactions. In _links section viewCardAccount link will be used.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonGetCardAccountTransactionsResponse'
        400:
          description: One of mandatory parameters(headers, request body or query parameters) missing or in incorrect format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonErrorResponse'
        401:
          description: Consent expired, consent is not valid for requested resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonErrorResponse'
        403:
          description: Consent absent, consent not authorized by user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonErrorResponse'
        404:
          description: Card account not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonErrorResponse'
        429:
          description: Consent access exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonErrorResponse'
  /{sandbox|live}/xs2a-premium/v1.3/card-accounts/{account-id}/transactions/{transactionId}:
    get:
      tags:
      - Card account information service
      summary: 'Card account info: Read Transaction details'
      description: Reads transaction data from a given card account addressed by 'account-id' and 'transactionId'. This call is only available on transactions as reported in a JSON format.
      operationId: getCardAccountTransaction
      parameters:
      - $ref: '#/components/parameters/envParam'
      - name: account-id
        in: path
        description: This identification is denoting the addressed card account. The account-id is retrieved by using a “Read Card Account List” call. The account-id is the “id” attribute of the card account structure. Its value is constant at least throughout the lifecycle of a given consent.
        required: true
        schema:
          type: string
      - name: transactionId
        in: path
        description: This identification is denoting the addressed transaction. The transactionId is retrieved by using a “Read Transaction List” call. The transactionId is the “id” attribute of the transaction structure. Its value is constant at least throughout the lifecycle of a given consent.
        required: true
        schema:
          type: string
      - name: X-API-Key
        in: header
        description: Authorisation key that can be acquired in TPP developer portal.
        required: true
        schema:
          type: string
      - name: Consent-ID
        in: header
        description: Shall be contained since “Establish Consent Transaction” was performed via this API before.
        required: true
        schema:
          type: string
          format: uuid
      - name: X-Request-ID
        in: header
        description: ID of the request, unique to the call, as determined by the initiating party.
        required: true
        schema:
          type: string
          format: uuid
      - name: PSU-IP-Address
        in: header
        description: The forwarded IP Address header field consists of the corresponding HTTP request IP Address field between PSU and TPP. If PSU presence (currently IP address) is provided with recurring consent then recurring consent counter is not incremented. Therefore account data can be gathered without limits.
        required: false
        schema:
          type: string
      - name: Authorization
        in: header
        description: Is contained only, if an OAuth2 based SCA was performed in the related consent authorisation.
        required: false
        schema:
          type: string
      - name: PSU-ID
        in: header
        description: Client ID of the PSU in the bank.
        required: false
        schema:
          type: string
      - name: PSU-Corporate-ID
        in: header
        description: Corporate client ID of the PSU in the bank.
        required: false
        schema:
          type: string
      responses:
        200:
          description: No errors occurred. Returns transaction details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonGetCardAccountTransactionDetailsResponse'
        400:
          description: One of mandatory parameters(headers, request body or query parameters) missing or in incorrect format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonErrorResponse'
        401:
          description: Consent expired, consent is not valid for requested resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonErrorResponse'
        403:
          description: Consent absent, consent not authorized by user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonErrorResponse'
        404:
          description: Card account not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonErrorResponse'
        429:
          description: Consent access exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonErrorResponse'
components:
  schemas:
    JsonAddress:
      type: object
      required:
      - country
      properties:
        streetName:
          type: string
        buildingNumber:
          type: string
        townName:
          type: string
        postCode:
          type: string
        country:
          type: string
          description: Country Code
    JsonGetCardAccountResponse:
      type: object
      required:
      - cardAccount
      properties:
        cardAccount:
          $ref: '#/components/schemas/JsonCardAccountDetails'
    BalanceType:
      type: string
      enum:
      - closingBooked
      - expected
      - openingBooked
      - interimAvailable
      - interimBooked
      - forwardAvailable
      - nonInvoiced
    CashAccountType:
      type: string
      enum:
      - CACC
      - CARD
    JsonGetCardAccountsResponse:
      type: object
      required:
      - cardAccounts
      properties:
        cardAccounts:
          type: array
          items:
            $ref: '#/components/schemas/JsonCardAccountDetails'
    JsonErrorResponse:
      type: object
      required:
      - transactionStatus
      properties:
        psuMessage:
          type: string
        tppMessages:
          type: array
          items:
            $ref: '#/components/schemas/JsonMessage'
        transactionStatus:
          $ref: '#/components/schemas/TransactionStatus'
    JsonAccountReference:
      type: object
      properties:
        iban:
          type: string
        bban:
          type: string
        pan:
          type: string
        maskedPan:
          type: string
        msisdn:
          type: string
        currency:
          type: string
        cashAccountType:
          $ref: '#/components/schemas/CashAccountType'
      description: Must contain one of iban,bban,maskedPan,msisdn or pan field
    JsonGetCardAccountTransactionsResponse:
      type: object
      properties:
        cardAccount:
          $ref: '#/components/schemas/JsonAccountReference'
        cardTransactions:
          $ref: '#/components/schemas/JsonCardAccountReport'
        balances:
          type: array
          items:
            $ref: '#/components/schemas/JsonBalance'
        _links:
          $ref: '#/components/schemas/JsonLinks'
    AccountUsage:
      type: string
      enum:
      - PRIV
      - ORGA
    JsonGetCardAccountBalancesResponse:
      type: object
      required:
      - balances
      properties:
        cardAccount:
          $ref: '#/components/schemas/JsonAccountReference'
        balances:
          type: array
          items:
            $ref: '#/components/schemas/JsonBalance'
    JsonCardAccountDetails:
      type: object
      required:
      - maskedPan
      - currency
      properties:
        maskedPan:
          type: string
        currency:
          type: string
        resourceId:
          type: string
        ownerName:
          type: string
        name:
          type: string
        displayName:
          type: string
        balances:
          type: array
          items:
            $ref: '#/components/schemas/JsonBalance'
        product:
          type: string
        status:
          $ref: '#/components/schemas/AccountStatus'
        usage:
          $ref: '#/components/schemas/AccountUsage'
        details:
          type: string
        creditLimit:
          $ref: '#/components/schemas/JsonAmount'
        _links:
          $ref: '#/components/schemas/JsonLinks'
      description: JsonCardAccountDetails must contain maskedPan field
    JsonBalance:
      type: object
      required:
      - balanceAmount
      - balanceType
      properties:
        balanceAmount:
          $ref: '#/components/schemas/JsonAmount'
        balanceType:
          $ref: '#/components/schemas/BalanceType'
        referenceDate:
          type: string
        lastChangeDateTime:
          type: string
        lastCommittedTransaction:
          type: string
    JsonHref:
      type: object
      properties:
        href:
          type: string
    JsonCardAccountReport:
      type: object
      required:
      - booked
      - _links
      properties:
        booked:
          type: array
          items:
            $ref: '#/components/schemas/JsonCardTransaction'
        pending:
          type: array
          items:
            $ref: '#/components/schemas/JsonCardTransaction'
        _links:
          $ref: '#/components/schemas/JsonLinks'
    TransactionStatus:
      type: string
      enum:
      - ACCC
      - ACCP
      - ACSC
      - ACSP
      - ACTC
      - ACWC
      - ACWP
      - RCVD
      - PDNG
      - RJCT
      - CANC
      - ACFC
      - PATC
      - PART
    JsonReportExchangeRate:
      type: object
      required:
      - sourceCurrency
      - exchangeRate
      - unitCurrency
      properties:
        sourceCurrency:
          type: string
        exchangeRate:
          type: string
        unitCurrency:
          type: string
    JsonMessage:
      type: object
      required:
      - category
      - code
      properties:
        category:
          type: string
        code:
          type: string
        path:
          type: string
        text:
          type: string
    JsonCardTransaction:
      type: object
      required:
      - transactionAmount
      properties:
        cardTransactionId:
          type: string
        terminalId:
          type: string
        transactionDate:
          type: string
        acceptorTransactionDateTime:
          type: string
        bookingDate:
          type: string
        transactionAmount:
          $ref: '#/components/schemas/JsonAmount'
        currencyExchange:
          type: array
          items:
            $ref: '#/components/schemas/JsonReportExchangeRate'
        originalAmount:
          $ref: '#/components/schemas/JsonAmount'
        markupFee:
          $ref: '#/components/schemas/JsonAmount'
        markupFeePercentage:
          type: string
        cardAcceptorId:
          type: string
        cardAcceptorAddress:
          $ref: '#/components/schemas/JsonAddress'
        cardAcceptorPhone:
          type: string
        merchantCategoryCode:
          type: string
        maskedPAN:
          type: string
        transactionDetails:
          type: string
        invoiced:
          type: boolean
        proprietaryBankTransactionCode:
          type: string
    JsonLinks:
      type: object
      properties:
        scaRedirect:
          $ref: '#/components/schemas/JsonHref'
        scaOAuth:
          $ref: '#/components/schemas/JsonHref'
        self:
          $ref: '#/components/schemas/JsonHref'
        status:
          $ref: '#/components/schemas/JsonHref'
        account:
          $ref: '#/components/schemas/JsonHref'
        balances:
          $ref: '#/components/schemas/JsonHref'
        transactions:
          $ref: '#/components/schemas/JsonHref'
        transactionDetails:
          $ref: '#/components/schemas/JsonHref'
        first:
          $ref: '#/components/schemas/JsonHref'
        next:
          $ref: '#/components/schemas/JsonHref'
        previous:
          $ref: '#/components/schemas/JsonHref'
        last:
          $ref: '#/components/schemas/JsonHref'
        download:
          $ref: '#/components/schemas/JsonHref'
        updatePsuIdentification:
          $ref: '#/components/schemas/JsonHref'
        startAuthorisation:
          $ref: '#/components/schemas/JsonHref'
        scaStatus:
          $ref: '#/components/schemas/JsonHref'
    JsonGetCardAccountTransactionDetailsResponse:
      type: object
      properties:
        transactionsDetails:
          $ref: '#/components/schemas/JsonCardTransaction'
    AccountStatus:
      type: string
      enum:
      - enabled
      - deleted
      - blocked
    JsonAmount:
      type: object
      required:
      - amount
      - currency
      properties:
        currency:
          type: string
        amount:
          type: string
  parameters:
    envParam:
      name: sandbox|live
      in: path
      description: The addressed environment
      required: true
      schema:
        type: string
        enum:
        - sandbox
        - live