swissfintechinnovations / ca-payment Goto Github PK
View Code? Open in Web Editor NEWCommon APIs for AIS and PIS
Home Page: https://www.common-api.ch
License: Apache License 2.0
Common APIs for AIS and PIS
Home Page: https://www.common-api.ch
License: Apache License 2.0
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
IS
SHOULD
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.
Enhancement
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
ITBD - Interim Booked:
XPCD - Expected:
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.
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
There are two possibilities to realize the adjustments:
AIS
IS:
application/xml
.<?xml version="1.0" encoding="UTF-8"?>
is declared inside the file as text, but not mandatory.PROPOSAL
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.
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.
As done by SIX bLink add another endpoint, which supports the POST method. Right now there are only GET endpoints implemented.
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:
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
/account/{accountId}/transactions
General JSON Endpoint responses:
Intraday - Supported
Intraday - Not Supported
/iso20022/statements/{reportId}
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:
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.
Enhancement
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.
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.
Date Parameter
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:
Open Questions
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."
AIS
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.
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
SHOULD
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:
For bLink the order would look like this:
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:
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
SHOULD
IS
Location: /payments/41341234
SHOULD
{
"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:
Set as required:
Besides the regular parameters (as for payments), there are some special standing order parameters needed for standing orders.
What | Comments | Common API | NextGenPSD2 |
---|---|---|---|
endToEndId | Specific end to end ID | yes | yes |
executionMode | The code of execution mode defines when or how standing order will be cancelled, processed the last time.UNTIL_DATE - standing order is valid until specific date - field lastExecutionDate.UNTIL_CANCELLATION - standing order is valid forever and must be cancelled by client. | yes | no |
executionRule | "following" or "preceding" supported as values.This data attribute defines the behaviour when recurring payment dates falls on a weekend or bank holiday.The payment is then executed either the "preceding" or "following" working day.ASPSP might reject the request due to the communicated value, if rules in Online-Banking are not supportingthis execution rule. | yes | yes |
frequencyCode | The following codes from the "EventFrequency7Code" of ISO 20022 are supported. "Daily", "Weekly", "EveryTwoWeeks", "Monthly", "EveryTwoMonths", "Quarterly", "SemiAnnual", "Annual" | yes | yes |
dayOfExecution | Day of execution as string. This string consists of up two characters. Leading zeroes are not allowed. 31 is ultimo of the month. | yes | yes |
startDate | The first applicable day of execution starting from this date is the first payment. | yes | yes |
endDate | Date when the last order will be processed. Null value responds to ending by the user. | yes | yes |
executionBreaksArray ofvalidFromDate*: datevalidToDate*: date | List of break periods.Start date of one break period. Standing order will not be processed from this date. Date format YYYY-MM-DD.End date of one break period. Standing order will not be processed to this date. Date format YYYY-MM-DD. | yes | no |
IS
SHOULD
IS
SHOULD
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
/balance
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
SHOULD
IS
SHOULD
Proposal: Mapping
Field JSON | Source (camt.053) | Example |
---|---|---|
fromDate | //Stmt/FrToDt/FrDtTm | 2023-04-01T00:00:00 |
fromDate | //Stmt/FrToDt/ToDtTm | 2023-04-03T23:59:59 |
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"
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.