swissfintechinnovations / ca-payment Goto Github PK

Due to the fact that the element for related booking information in camt message and JSON is specified as optional and not mandatory the relevant booking information are missing.

In order to visualize the issue I have taken a print screen from the ZKB eBanking (Multibanking via bLink) from UBS bank accounts. There is the wide empty space where the valuable booking information of merchant and payment method should be filled with.
The information on the right prints screen (UBS eBanking) need to be exchanged for Multibanking via bLink as to provide this information as booking text.

We consider this issue as critical for the market acceptance of Multibanking service and are convinced that it needs to be solved in timely manner in order to provide the excellent user experience that we strive for our Multibanking service.
--> Printscreen with visualization of missing booking informaiton attached

The booking information is captured in the element Additional Entry Information. This element is specified as optional. Please look at the SIX specification under folder blink-api-docs-1.1.0.7\handbook\Account_Information_Service_(AIS).html:
--> Printscreen with related element attached

We suggest that this topic will be taken up on our next meeting as to

1. inform about this issue and create awareness in the community
2. clarify when the SIX specs can be adjusted in other to put this element as mandatory

IS

• Probably this endpoint is not used at all, as the "Service User" knows the payment he has submitted.

SHOULD

• Remove this endpoint in a future version (breaking change)

As agreed with the implementation of issue #28 the property designation in the accountIem object shall be set to mandatory with the next major release.

Contact Details

[email protected]

Issue category

Enhancement

Issue description

The query parameter "bookingStatus" has already been added to the API with the filter values "booked, pending, both".
However, several issues and adjustments need to be addressed to fully support the functionality.

Parameter
The "bookingStatus" is currently defined as followed:

        - in: query
          name: bookingStatus
          required: true
          schema:
            type: string
            enum:
              - booked
              - pending
              - both

Response
The "bookingStatus" of transactions should be reflected in the response to identify the status. This status is only applicable for intraday data.

Balance
The usage of the bookingStatus should be reflected in the retrievable balance of the accounts.
To be conform with the Swiss Payment Standard guidelines, the following values are used and could be enhanced with:

ITAV - Interim Available

• Definition according to ISO20022: Available balance calculated in the course of the account servicer'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.
• Purpose: Provides a real-time snapshot of available funds, subject to change as transactions are processed throughout the day.
• Use Case: Useful for real-time decision-making and managing immediate cash flow needs.

ITBD - Interim Booked:

• Definition according to ISO20022: Balance calculated in the course of the account servicer'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.
• Purpose: Offers a static and historical view of the account's balance, considering only completed and recorded transactions.
• Use Case: Useful for reconciling the account and understanding the confirmed and cleared transactions at a specific point in time

XPCD - Expected:

• Definition according to ISO20022: Balance, composed of booked entries and pending items known at the time of calculation, which projects the end of day balance if everything is booked on the account and no other entry is posted.
• Purpose: Provides a forecast of the balance at the end of the business day, assuming all pending transactions are processed.
• Use Case: Useful for financial planning and anticipating end-of-day balances for operational purposes.

Issue reasoning

Requirement that was brought up within the bLink Multibanking initiative to improve the user experience.
Users should have access to real time data, ideally the same in the Service User application as in the e-Banking of the Service Provider. The API currently only supports the request of booked transactions. Users should have access to all bookings and be able to identify and filter them accordingly to better manage their finances.

Request

To include the bookingStatus in the current API, the following items and questions must be clarified.

Query Parameter
The query parameter is already integrated in the specification. However, the definition should be adjusted.
Should the bookingState be required?
Should a default value be set and if so, which?

Response
The bookingStatus should be reflected in the "Account Transaction Entry" object of the response, even though it is only applicable for Intraday Transactions

Balance Types
The balanceType in the /balance endpoint should be extended with ITAV and/or XPCD

Proposed change

There are two possibilities to realize the adjustments:

1. Enhance the existing endpoints

• Adjust the existing endpoints to include the bookingStatus parameter and update the response schema accordingly.

2. Add new endpoints for intraday data

• Create new endpoints specifically for intraday data, either combining balance and transactions according to camt.052 or dividing them into separate endpoints.

Affected API's

AIS

Code of Conduct

• I agree to follow this project's Contribution Guidelines

IS:

1. The media-type of XML messages is currently defined as application/xml.
2. In the example request <?xml version="1.0" encoding="UTF-8"?> is declared inside the file as text, but not mandatory.
   ... so the content-type negotiation would be up to the SU / SP ...
3. One Service User sent us XML without any encoding.
4. We expected for historic reason "ISO-8859-1" as default.

PROPOSAL

1. Let's change the media-type from application/xml to application/xml; charset=utf-8 in Release 5.0 and never talk about the issue again :-).

Here the location in the specification:

One of the sections affected - PAIN.001 upoad in PSS:

  /iso20022/payments:
    post:
      tags:
        - iso20022
      summary: Submit an ISO20022 XML payment instruction (PAIN.001)
      description: >
        Submit an ISO20022 XML PAIN.001 payment instruction.

        The submitted payment instruction must conform to the XML Schema and
        Implementation Guidelines defined by Swiss Payment Standards;

        see:
        https://www.six-interbank-clearing.com/en/home/standardization/iso-payments/customer-bank/implementation-guidelines.html
      operationId: submitIso20022PaymentInstruction
      parameters:
        - $ref: '#/components/parameters/permissionid_in_header'
        - $ref: '#/components/parameters/correlation_in_header'
        - $ref: '#/components/parameters/agent_in_header'
        - $ref: '#/components/parameters/targetid_in_header'
        - $ref: '#/components/parameters/psu_ip_in_header'
        - $ref: '#/components/parameters/psu_user_agent_in_header'
        - $ref: '#/components/parameters/optional_authorization_in_header'
        - $ref: '#/components/parameters/optional_instance_id_in_header'
      requestBody:
        required: true
        description: Payment instruction details as defined by data model.
        content:
          application/xml:
            schema:
              type: string

In order to be able to display all transactions for an account in a user-friendly manner in a multibanking solution, the question arises as to whether the existing GET /accounts/{accountId}/transactions functionality is sufficient (keyword provisional bookings).
From my point of view, the same list of transactions to an account must be delivered via the corresponding functionality in the AIS API as when I browse the transactions in the eBanking/Mobile Banking solution of the bank to which the account belongs.

1. So far, all healthcheck endpoints respond with an HTTP response code and a JSON object which indicates whether a healthcheck is failed or succeeded. All other endpoints of the ca-payment API use the problem detail object (RFC7801), which is a standard JSON object using specific values and can be extended with arbitrary values and data. So it is easy to transform the current JSON structure into an RFC aligned structure. This improvement would unify all endpoints using the same (error) response.

2. As done by SIX bLink add another endpoint, which supports the POST method. Right now there are only GET endpoints implemented.

In AIS in the 200 responses, lists are returned as non-extendable array e.g. in get /iso20022/statements endpoint.

Shouldn't extensible objects be used there and shouldn't pagination be added?

In PSS the implementation seems to be correct.

Implement all non-breaking changes related to the naming conventions. For all details regarding the applied naming conventions please see here: https://github.com/swissfintechinnovations/.github/wiki/Naming-Conventions.

Proposal:

• https://open-banking.pass-consulting.com/json_ExternalCashAccountType1Code.html

This language independant code list (CashAccountType from ISO20022) is an idea to be used as a formal list of account type to be normalized over all banks.

The AIS specification is interpreted differently by the service providers, which leads to inconsistency in returning errors.
Consumers of the API need to implement specific rules for each service provider individually. This is contradictory to the standardized approach of the common API.
According to the feedback of the Service Providers, SIX created a first draft with a recommendation of how to handle different business cases of the AIS API Endpoints:

/account/{accountId}/balances

• Must always be returned
• Non-Business Days: Return balance of last available day

/account/{accountId}/transactions

• Non-Business Days: 404 - RESOURCE_DOES_NOT_EXIST
• No Bookings for requested day: 404 - RESOURCE_DOES_NOT_EXIST (To be clarified)

General JSON Endpoint responses:
Intraday - Supported

• Returns the intraday data (booked balance (ITBD) or transactions), if called without a date.
• Returns the closing data (booked balance (CLBD) or transactions), if called for a past date.
  - In case the specified day has not yet been finalized, the response will be a 404 - RESOURCE_NOT_READY.

Intraday - Not Supported

• 404 - NOT_IMPLEMENTED

/iso20022/statements/{reportId}

• Ressource not yet generated: 404 - RESOURCE_NOT_READY

The goal should be that the community agrees on a standard that would be documented within the API specification itself or on the SFTI Website.

To be more specific about Intraday- Data:
Intraday Data are only completed as of Day-End-Processing of the next day. To avoid confusion with the specific date, intraday data must be requested with date parameter = empty.

To be clarified:
Unified Error Handling requires CommonErrorReponse - Type as mandatory in order to ensure that the issue can be identified.
-> Change Type in CommonErrorResponse to required for AIS and Payment API

The values in the CommonErrorType enum are not valid URI's as specified in RFC 3986.

Shall we correct the URI's to valid URI's as specified in RFC 3986?

URI syntax according to RFC 3986:
The generic URI syntax consists of a hierarchical sequence of components referred to as the scheme, authority, path, query, and fragment. The scheme and path components are required, though the path may be empty (no characters).

The SIX API version includes the GET /consent endpoint. The content of this endpoint is very similar to the GET /accounts/{accountID} endpoint but it contains two additional attributes "accountOwner" and "allowedCurrencies". Which leads to the following questions:

• Why are there two different endpoints which provide almost the same information? Wouldn't one be enough?
• How are the attributes "accountOwner" and "allowedCurrencies" specified from a business point of view? Who is "accountOwner" in a joint account? What does "allowedCurrencies" actually mean?
• For what reason are these two additional attributes needed?

Right now, the limit parameter type is defined by an int32. This allows to request up to 2^32 list entries which are way more than would ever exist for a single user (e.g. payments of last year). This potentially inserts a security flaw like Heartbleed, if the API's backend is not able to handle that big numbers.
To avoid this (theoretic) risk one could strip this parameter to a usable max value. For example, the limit parameter could be extended by a maximum: 1000 value, which prevents this kind of attack.
The specific usable value, that is aligned to everyday use case, needs to be discussed with @six and other TPPs.

Contact Details

[email protected]

Issue category

Enhancement

Issue description

Currently, the API requires separate requests for each day of transaction data. This approach leads to excessive API calls and increased server load. In order to improve the API, the requests should be enabled for a specific date range and supported by an appropriate pagination method to limit processing time.
Although, the query parameter and pagination of the transaction endpoint have been already adjusted, the exact behavior should be defined and open questions clarified.

Issue reasoning

This Requirement was brought up within the bLink Multibanking initiative and by several existing and new participants to improve efficiency and performance. Using date-range requests reduces the number of API calls, making interactions more efficient and reducing server load.

Request

Date Parameter

• The query parameters are already adjusted to "dateFrom" and "dateTo". However, the usage of the parameter and sorting of data should be more concise. Therefore, either the description of the parameter or the example value should be adjusted.

Pagination
The current pagination used is a combination of cursor-based and offset-limit pagination with links in the response that require the server to process all data.
Cursor-based pagination would be appropriate for the API and the following adjustments could be agreed on:

• Query Parameter "cursor": Define in the description, which attribute should be used as cursor
• Query Parameter "limit": Define a maximum and default number of entries to be returned
• "linksPagination" in Response: Remove the Pagination-Links in the response and add a link to the next page as Response-Header

Open Questions

• Currently, transaction list of the current day is requested, by sending the request without a date. Should intraday data be included, when querying date ranges or clearly excluded?
• Status Code 204 would not be required anymore for the transaction endpoint as a list of transactions should always be returned?
• Status Code 202 would still be used, in case data is requested for a booking day, that is not completed yet?

Proposed change

Date Parameters
- Change "dateFrom" example value from 2018-04-13 to 01.01.2023
- Change "dateTo" example value from 2018-04-13 to 31.12.2023

Pagination
- Change "cursor" description from "Optional parameter for pagination. An opaque string value used for pagination" 
to 
"Optional parameter for pagination. An opaque string value used for pagination.
Use EntryId as the cursor reference"
- Change "limit" value to max. 50 and default 20
- Add Response-Header "X-Next-Cursor" with description "An opaque string value, or an empty string if there are no more results."

Affected API's

AIS

Code of Conduct

• I agree to follow this project's Contribution Guidelines

Date parameter in the /balance endpoint is missing. How could the balance for a specific day be requested?
balance - blink AIS

balance - common-API

The exchangeRate on the /transactions endpoint in AccountAPI need to be adjusted. The pattern was initially wrongly defined and causes issues on bLink production environment.

The pattern should be changed as followed:
Old: [0-9][.][0-9]{1,10}
New: ^\d{1,11}$|^(?=\d+[.]\d+$).{3,12}$

With the new pattern we would comply to the definition in the camt.053 schema:

The definition in camt.053 does not imply how many digits before the decimal point are required, whereas the current pattern on the JSON endpoint does.

In the standard responses, e.g. standard503, the content type is defined several times: once by the header, once by the content in the openapi construct.

Should we remove the double header definition?

Currently the attributes 'title' and 'status' in the CommonErrorResponse object are all optional although the RFC 7807 identifies these as required.

Should we change our specification in order to be compliant with RFC 7807?

There should be a time table / schedule available where a consumer of a service provider can check, when the services are available or not.

• In case of "same day" payments - so that the service user can automatically/dynamically display to the end user, when the payment will be executed and/or adjust execution date

• When the services are "open for business" - there are cases when the services of the service provider are not available (scheduled). So a schedule would be nice so that a call to a service provider can only be made, if it's according to the schedule

• When there is an unexpected outage - for example if a service user has a outage, that this information can also be obtained by bLink. Currently a service user realizes this and the issue gets spread across the bLink community by "word of mouth"

IS

• The SIX- and SFTI-API versions have some gaps.

SHOULD

• Could you to add the "SIX" versions as informative branches the repository?
• So we could compare the remaining gaps more easily

Would it makes sense to order the Headers, Paths and Queries in a defined order for all APIs?

bLink suggestion would be to arrange it alphabetically with:

• Headers required
• Headers optional
• Paths required
• Paths optional
• Queries required
• Queries optional

For bLink the order would look like this:

• bLink Headers required
• bLink Headers optional
• General Headers required
• General Headers optional
• Paths required
• Paths optional
• Queries required
• Queries optional

In accordance with the reply scheme, several transactions can be returned (transactions is defined as array). However, this makes little sense if a transactionId is provided in the input parameter.

The question now is what would be correct:

1. should transactions not be defined as an array
2. should only the Account Transaction Item be returned (instead of the Account Transaction Entry), or
3. should the entryId be passed instead of the transactionId (the Account Transaction Entry object is not defined as an array)

Subsequent entry of issue for existing pull request to ensure traceability.

Content of issue: Just a little more strict definition of the input for "X-PSU-IP-Address".

As agreed with the implementation of issue #61 the property accountTypeCode in the accountIem object shall be set to mandatory with the next major release.

According to RFC specification, the status code 204 cannot contain a content in the response.
To be compliant to the RFC specification, the definition in the account specification need to be adjusted as follows:

standard204:
headers:
Content-Type:
$ref: '#/components/headers/Content-Type'
Content-Language:
$ref: '#/components/headers/Content-Language'
description: |
No content - The server has successfully fulfilled the request. There is no content to return and never will be.
X-Correlation-ID:
$ref: '#/components/headers/X-Correlation-ID'
X-CorAPI-Source:
$ref: '#/components/headers/X-CorAPI-Source'
content:
application/json:
schema:
type: object
# properties: ??

Issue below was already raised in summer 22 during a discussion between SIX and Finnova but so far no definitive answer has been provided.

When submitting an payment order to the Finnova core banking system, this payment order is placed in a queue and, depending on the system load, it may take a few seconds before we know whether the order is fully accepted (ACCP), partially accepted (PART) or rejected (RJCT). If, during this few seconds, the GET /payments/{submissionID}/status endpoint is called, the status RCVD (received) will be returned because the payment order is not yet processed (but received). But this is not in line with the OpenAPI specification of the PSS module where statusCode has to be either ACCP, PART or RJCT.

According to the bLink handbook the FI should respond with an error code. In our opinion an error code is not the right answer because there's no technical error. The payment order is just not yet processed but from a technical point of view everything is fine. Therefore we would suggest to add an additional statusCode RCVD (received) for this situation.

IS

• We are currently using the OpenAPI v3.0.1

SHOULD

• The OpenAPI version v3.1.0 would enable more possibilities, e.g. base64 encoded XML can be defined precisly.
• https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0

IS

• The payment-id is returned in this strange format as (relative) URL in the response Header

Location: /payments/41341234

SHOULD

• A simple body with one field would be way easier.

{
  "submissionId": "41341234"
}

With regard to the Kaspar& use case on bLink we got and get a lot of questions about what "kind" of balance will be returned by the GET /accounts/{accountId}/balance endpoint when called without a date. The current description seems to be not clear enough.

Proposal would be to adapt the description along the ISO20022 descriptions below.

The type of the properties 'amount' and 'exchangeRate' shall be changed from 'number' to 'string' in order to be more precise what format/pattern is expected.

IS situation

amount:
type: number
minimum: 0.00000
maximum: 999999999999.99999
description: The payment amount.
example: 10.25

exchangeRate:
type: number
minimum: 0.000
maximum: 99999999.999
description: The applied exchange rate if source currency is not equal to target currency.
example: 0.957

TO-BE situation

amount:
type: string
pattern: '[0-9]{1,12}([.][0-9]{1,5})?'
maxLength: 18
description: The payment amount.
example: 10.25

exchangeRate:
type: string
pattern: '^\d{1,11}$|^(?=\d+[.]\d+$).{3,12}$'
maxLength: 12
description: The applied exchange rate if source currency is not equal to target currency.
example: 0.957

As agreed with the implementation of issue #22 the following adjustments to the properties shall be implemented:

To delete:

• name
• description
• type

Set as required:

• schemaVersion
• account
• dateFrom
• dateTo

Besides the regular parameters (as for payments), there are some special standing order parameters needed for standing orders.

IS

• According to issue CON-1197 at SIX, the handling of the "header field" is different between the parties.
• Variants:
• Bank A: Absolut path
• Bank B: /payments/{submissionId}
• SIX-SIM: /payments/{submissionId}
• According to IETF: https://datatracker.ietf.org/doc/html/rfc7231#section-7.1.2 both is valid (absolute or relativ path)

SHOULD

• It would be easier for everyone, if we handle the topic in a uniform way
• Recommendation: /payments/{submissionId}
• Clarify the specification & add an example to the specification.

IS

• Statements cannot be requested by accountor or by date ranges.

SHOULD

• Add an endpoint similar to "/accounts/{iban}/transaction" to query statements.
• Allow dateFrom / dateTo query parameters.
• Use the same result parameters as the existing "/iso20022/statements".

accountAPI.yaml contains very long tag names like Account data of the specified account. Please shorten these names for clarity reasons. More details should be provided in the summary or description tag.

Do you agree @rolfwagner?

It is proposed to provide a static list of values for this entity, comparable to what has been done at the OpenWealth API for the corresponding transaction code.

For payments, SIX has already published a corresponding list in the context of ISO20022

At the bLink side, domain, subdomain and family code is present, but no list is yet defined. This could be addressed by bLink, if it makes sense from bLink's point of view.

The current descriptions of the usage for /balance and /transactions should be adjusted, as the error code for not finalized day is deprecated and description is not precise enough.
Here my suggestions:

/transactions

• Retrieves the list of transactions for the current day, if called without a date.
• Retrieves the transaction list for a specific day, if called for a past date. In case the specified day is not yet finalized, the response code will be 202.

/balance

• Retrieves the intraday booked balance (ITBD) for the current day, if called without a date.
• Retrieves the closing booked balance (CLBD) for a specific day, if called for a past date. In case the specified day is not yet finalized, the response code will be 202.

Although there is a common usage of HTTP response codes defined by the RFC, there is a necessity to adjust their definitions for API as they were designed to inform about webpage request states. These adaptions leave uncertainties of the usage of http status codes in the context of APIs. So, the SFTI community also has slightly different understanding of the detailed usage of status codes for specific use and business cases.

To overcome this issue I would recommend to gather a comprehensive set of examples, how to implement HTTP response codes in a SFTI compliant way. These exemplary code pieces should guide implementers and establish a common understanding of the whole community, even for cases that will only appear in the further development of the API.

So far, all examples are documented in the YAML API specifications. Unfortunately, these examples are overwritten by the response reference object and thus only visible in the source file but not in the SwaggerUI or other documentation tools. For this reason, there is perhaps a more appropriate place for documenting the examples.

Problem Description
Since the designation field in the bLink API is specified as optional and a Service Provider might choose not to send this information, a Service User would only receive the IBAN and currency as information per account to display in the front-end of their Multibanking offering. Especially Retail clients might struggle to differentiate their accounts only based on these information.

Request
Make the designation field mandatory, so that a Service User for sure receives this information from any Service Provider and is able to display it to their clients in the front-end.

Remark
This issue was raised on behalf of Majurikka Sivanantham ([email protected]), who is not allowed to register on GitHub due to access restrictions imposed by her employer.

IS

• The SP (Bank) has no knowledge about the security level of the TPP-User
• It would be helpful for fraud detection, to asses the End-2-End login risks.

SHOULD

• It should be optionally possibly to transmit the quality of the PSU-Login
• X-PSU-Auth-Level (Values: 1FA, 2FA) - More values may be discussed.

IS

• The TPP/Service Users has to parse filenames per bank to know the camt.053 period affected.

SHOULD

• Extend "iso20022ReportReference" with "date" and "iban" to carry the information in a structured way

Proposal: Mapping

Proposal: Response

      {
      "name": "CH1100790016123456029_2023-01-16",
      "description": "Kontoauszug von CH1100790016123456029 am 16.01.2023",
      "type": "CAMT53",
      "id": "8265333",
      "account": {
         "type": "IBAN",
         "identification": "CH9300762011623852957"
      },
      "dateFrom" : "2023-01-16",
      "dateTo:" : "2023-01-16"
   },

Proposal: Swagger

        account:
          $ref: '#/components/schemas/paymentIbanAccount'
        dateFrom:
          type: string
          format: date
          example: "2018-10-29"
        dateTo:
          type: string
          format: date
          example: "2018-10-29"