swissfintechinnovations / ca-payment Goto Github PK

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

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.

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.

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)

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

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"

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?

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.

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

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.

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.

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

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.

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.

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 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.

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.

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".

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.

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

balance - common-API

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"

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

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?

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: ??

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.

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.