Minor Release of AIS v5.1

July 1, 2025 · 5 min read

Product Manager

AIS Minor Version 5.1

We are releasing AIS API Version 5.1, a mandatory minor update that fully replaces Version 5.0 as the new baseline for implementation.

This release includes critical bug fixes and a series of refinements to descriptions and behavior clarifications across the API. It ensures correct usage of key endpoints and provides clearer guidance for implementation.

Explore the details in the SFTI GitHub Changelog.

Release

XE: 07/2025
XP: 08/2025
Prod: 09/2025

Key Changes

Added

External documentation reference added:
- GET/transactions now links to the Transaction Endpoint Factsheet to support correct implementation and usage.

Changed

Schema and structure updates:
- Response structure of GET/transactions adjusted:
  - Removed outer transactions array to enable consistent pagination handling and schema reusability.
- Field amount in schema BalanceCurrencyAmount updated:
  - Changed from $ref to inline definition with corrected regex pattern to support negative values and enforce valid formatting.
Description improvements:
- Clarified behavior of GET/balance and GET/transactions retrieval
- Defined the scope of GET/statements and GET/reports coverage
- Specified expected response codes for unavailable data (202, 204).
- Mapping recommendations specified:
  - Field entryId in schema AccountTransactionEntry should contain the accountServicerReference (C-level).
  - Field transactionId in schema AccountTransactionItem should contain the accountServicerReference (D-level).

Changes in YAML

...
  /accounts/{accountId}/balance:
    get:
      tags:
        - accounts
      summary: Retrieve account balance information
      operationId: requestAccountBalance
      description: |
+       Returns account balance information of the specified account.
+       * Returns the interim booked balance (ISO20022 Balance Type ITBD) for the current day, if called without a date. The balance is
+       calculated in the course of the service provider's business day, at the time specified, and subject to further changes during the
+       business day. The interim balance is calculated on the basis of booked credit and debit items during the calculation time/period
+       specified.
+       * Returns the closing booked balance (ISO20022 Balance Type CLBD) for a specific day, if called for a past date. It is the sum of
+       the opening booked balance at the beginning of that day and all entries booked to the account during that day. In case the specified
+       day has not yet been finalized, the response code will be 202.
-       Returns account balance information of the specified account.
-       * Returns the interim booked balance (ISO20022 Balance Type ITBD) for the current day, if called without a date. The balance is
-       calculated
-       in the course of the service provider's business day, at the time specified, and subject to further changes during the business day.
-       The
-       interim balance is calculated on the basis of booked credit and debit items during the calculation time/period specified.
-       * Returns the closing booked balance (ISO20022 Balance Type CLBD) for a specific day, if called for a past date. It is the sum of
-       the opening
-       booked balance at the beginning of that day and all entries booked to the account during that day. In case the specified day has not
-       yet been
-       finalized, the response code will be 202.
      parameters:
      ...
  /accounts/{accountId}/transactions:
    get:
      tags:
        - accounts
      summary: Retrieve transactions of a specific account
      operationId: requestAccountTransactions
+     externalDocs:
+       description: A detailed description of how this endpoint is used is available in the wiki.
+       url: https://github.com/swissfintechinnovations/ca-payment/wiki/Transaction-Endpoint-Factsheet
      description: |
        Returns the transaction list of the specified account.
+       * When called without a date, it returns all transactions since the last completed booking day. Both "pending" and "booked" entries
+       may be included based on the entryStatus parameter.
-       * When called without a date, it returns transactions for the current day. Both "pending" and "booked" entries may be included based
-       on the entryStatus parameter.
        * When called with a date range, only "booked" transactions from completed booking days are returned. For days not yet finalized, a
        202 response code is returned.
+
+       Results are sorted by bookingDate in descending order. Additional sorting logic is provider-specific but all providers must ensure
+       stable and consistent pagination behavior. If pagination is required, the server includes an opaque cursor in the `X-Next-Cursor`
+       header. This cursor identifies a specific position in the sorted result set and is internally derived from the sorting criteria.
+       Clients must pass this value unchanged in the `cursor` parameter of the next request to retrieve subsequent pages.
+
+       Transaction details are optional in the schema, but all available information must be included if present for a given transaction.
      parameters:
      ...
      responses:
        '200':
          description: Transaction data of the specified account.
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/X-Correlation-ID'
            X-CorAPI-Source:
              $ref: '#/components/headers/X-CorAPI-Source'
            X-Next-Cursor:
              $ref: '#/components/headers/X-Next-Cursor'
          content:
            application/json:
              schema:
+               $ref: '#/components/schemas/AccountTransactionReport'
-               type: object
-               required:
-                 - transactions
-               properties:
-                 transactions:
-                   type: array
-                   items:
-                     $ref: '#/components/schemas/AccountTransactionReport'
        '202':
+         #description: |
+         #  Accepted - The request is valid, but the requested data is not yet available because the associated booking day is still
+         #  in progress or not finalized. The request can be repeated at a later time once the data has been finalized.
          $ref: '#/components/responses/standard202'
        '204':
+         #description: |
+         #  No Content - The request was successful, but no data is available for the requested date or parameters. No data is expected to become
+         #  available in the future. This may occur if the requested period is outside the retention scope or if no entries exist for the given
+         #  account and criteria.
          $ref: '#/components/responses/standard204'
          ...
  /iso20022/statements:
    get:
      tags:
        - iso20022
      summary: Retrieve a list of resource links to account statements (camt.053)
      description: |
+       Get a list of resource links to available account statements (camt.053) for all accounts covered by the eBanking contract delivered.
+       The returned account statements must be conform to the XML schema and implementation guidelines defined by Swiss Payment Standards.
+       If the call covers a period of several days, then an account statement is returned for each day and account, if available.
-       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.
      operationId: retrieveIso20022AccountStatementIds
      parameters:
      ...
  /iso20022/reports:
    get:
      tags:
        - iso20022
      summary: Retrieve a list of resource links to account reports (camt.052)
      description: |
+       Get a list of resource links to available account reports (camt.052) generated since the last End-of-Day (EOD) processing.
+       Only intraday reports created after the most recent EOD cycle are included.
+       The returned account reports must conform to the XML schema and implementation guidelines defined by Swiss Payment Standards.
-       Get the resources links to available account reports (camt.052) generated since the last End-of-Day (EOD) processing. Only intraday
-       reports created after the most recent EOD cycle are included. The returned account reports must conform to the XML schema and
-       implementation guidelines defined by Swiss Payment Standards.
      parameters:
      ...

components:
  schemas:
    ...
    AccountTransactionEntry:
      ...
        entryId:
          type: string
          description: |
+           Unique bank-defined ID for the transaction. Corresponds to the attribute _Ntry ⇾ AddtlInfInd ⇾ MsgId_ in SPS/ISO-20022.
+           With the new elements accountServicerReference (in C level) the usage recommendation of this element is as follows:
+           For new onboarding banks / financial institutions starting with V5.1 this element shall contain accountServicerReference
+           (entries, C-level) from camt.
+           For banks / financial institutions already using V4 the content mapping can be kept to be consistent with V4. The description
+           in V4 is following: Unique bank-defined ID for the transaction. Corresponds to the attribute _Ntry ⇾ AddtlInfInd ⇾ MsgId_ in
+           SPS/ISO-20022.
+           Important note: With V6 this element will be removed.
-         description: Unique bank-defined ID for the transaction. Corresponds to the attribute _Ntry ⇾ AddtlInfInd ⇾ MsgId_ in SPS/ISO-20022.
-         example: ENTRY123456789
          ...
    AccountTransactionItem:
      ...
        transactionId:
          type: string
          maxLength: 35
          description: |
+           The unique identifier to the listed transaction. Defined by the client. Corresponds to the attribute _TxDtls ⇾ Refs ⇾ PmtInfId_ in
+           SPS/ISO-20022.
+           With the new elements ServiceAccounterReference (in D level) the usage recommendation of this element is as follows:
+           For new onboarding banks / financial institutions starting with V5 this element shall contain accountServicerReference
+           (transactions, D-level) from camt.
+           For banks / financial institutions already using V4 the content mapping can be kept to be consistent with V4.
+           Importan note: With V6 in November 2026 this element will be removed.
-           The unique identifier to the listed transaction. Defined by the bank. Corresponds to the attribute _TxDtls ⇾ Refs ⇾ PmtInfId_ in
-           SPS/ISO-20022.
          example: TX12345A987
          ...
    BalanceCurrencyAmount:
      title: Balance Currency-Amount
      description: Specifies the requested account balance. Corresponds to the attribute _Bal_ in SPS/ISO-20022.
      type: object
      required:
        - amount
        - currency
      properties:
        amount:
+         type: string
+         pattern: ^-?[0-9]{1,12}([.][0-9]{1,5})?$
+         maxLength: 18
+         description: The amount of the requested account balance.
+         example: '10.25'
-         $ref: '#/components/schemas/Amount'

AIS Minor Version 5.1​

Release​

Key Changes​

Added​

Changed​

Changes in YAML​