...
To provide clarity to ASPSPs to enable them to design effective and high-performing dedicated interfaces while fulfilling their regulatory obligations.
To ensure that AISPs and PISPs have access to consistently well-designed, well-functioning and high performing dedicated interfaces.
To provide the CBB with insights into the availability and performance of key ecosystem APIs and identify issues which may impact adoption and experience.
In addition, adherence to these Operational Guidelines will provide the following benefits:
Improve efficiencies: Minimize the potential impact to a business when systems or supporting networks are down (including instances where they have not been tested appropriately).
Reduced Reputational Risk: Protect the reputation of ASPSPs/AISPs/PISPs and the Open Banking ecosystem as a whole.
3. Availability and Performance
...
Guidelines to explain how these should be calculated by ASPSPs for the dedicated interface.
A recommended benchmark for the dedicated interface on the basis of global best practices.
ASPSPs should ensure that the APIs/dedicated interfaces offered to AISPs/PISPs should at all times have the same level of availability and performance as the interfaces made available to the users/customers via the ASPSPs online environment.
...
Without error messages and
That have received a successful response from the ASPSP, for example returning the data required to be provided to AISPs.
This section sets out a minimum of two KPIs for availability that an ASPSP should have in place for each API. The following table explains these KPIs in detail and provides guidance on how they should be calculated. (The downtime mentioned is set for initial implementation of Bahrain OBF and may be revised on periodic basis).
...
Title | Requirement | Calculation Guidelines | Recommended Benchmark |
The uptime per day of all interfaces | For the purpose of calculating the availability indicators, the ASPSP should: a) calculate the percentage uptime as 100% minus the percentage downtime. | For each 24 hour period, uptime is calculated as 100% minus the total percentage downtime in that period. | A quarterly uptime of 99.5%[1] |
The downtime per day of all interfaces | For the purpose of calculating the availability indicators, the ASPSP should: a) calculate the percentage downtime using the total number of seconds the API was down in a 24 hour period, starting and ending at midnight.
b) count the interface as ‘down’ when five consecutive requests for access to information for the provision of payment initiation services, account information services are not replied to within a total timeframe of 30 seconds, irrespective of whether these requests originate from one or multiple PISPs/AISPs. In such a case, the ASPSP should calculate downtime from the moment it has received the first request in the series of five consecutive requests that were not replied to within 30 seconds, provided that there is no successful request in between those five requests to which a reply has been provided. | Downtime should be calculated as follows:
At a minimum, downtime should be measured if:
This should include any vendor/supplier failures in the case where the ASPSP has contracted the vendor/supplier to deliver a related service. However, this should exclude errors resulting from issues outside of the ASPSP's direct control, such as issues with AISP/PISP software, infrastructure or connectivity. | A quarterly downtime of 0.5%. (approx. 11 hours per quarter, or just under four hours per month, to allow for planned releases, updates, and also any unplanned downtime). |
...
Title | Requirement | Calculation Guidelines | Recommended Benchmark |
PISP response time | For the purpose of calculating the performance indicators, the ASPSP should: a) calculate the daily average time (in milliseconds) taken, per request, for the ASPSP to PISP with all the information requested. | The "time taken per request" should be calculated for each day using the mean value of Time to Last Byte (TTLB) measured in milliseconds, starting from the time that each endpoint request has been fully received by the ASPSP and stopping when the last byte of the response message has been transmitted to the PISP. The following API endpoints should be included when calculating PISP response times, for each endpoint supported by the ASPSP:
The ASPSPs signed response to the POST will inherently act as proof of receipt of the payment order by the ASPSP, which will enable the PISP to log a reference and the date of this receipt. Both the POST and the GET endpoints contain all information relating to the payment, which, depending on the payment type, should include reference, amount, exchange rate, charges, and status (which may change between POST and any subsequent GET). The POST endpoints above cater for the ASPSP to make the information available to the PISP immediately after receipt of the payment order, and the provision of all information on the initiation of the payment transaction and all information accessible to the ASPSP regarding the execution of the payment transaction. The GET endpoints cater for the ASPSP to provide confirmation to the PISP that payment initiation has been successful, in order to enable the PISP to provide this information to the user/customer. Since different endpoints will have different payload sizes for request and response (especially relevant for bulk/batch payment endpoints involving large files), and in order to facilitate a 'like for like' comparison with user/customer interfaces, ASPSPs should report on the average time per megabyte (MB). This can be calculated by dividing the total response time in milliseconds by the total payload response size in MB, across all API calls for all API endpoints for each day. | An average TTLB of 750 milliseconds per response for all but bulk/batch payments. |
AISP response time | For the purpose of calculating the performance indicators, the ASPSP should: a) calculate the daily average time (in milliseconds) taken, per request, for the ASPSP to provide the AISP with all the information requested. | The "time taken per request" should be calculated for each day using the mean value of Time to Last Byte (TTLB) measured in milliseconds, starting from the time that each endpoint request has been fully received by the ASPSP and stopping when the last byte of the response message has been transmitted to the AISP. The following API endpoints should be included when calculating AISP response time, for each endpoint supported by the ASPSP:
Since different endpoints will have different payload sizes for request and response, and in order to facilitate a 'like for like' comparison with user/customer interfaces, it is recommended that ASPSPs also report on the average time per megabyte (MB). This can be calculated by dividing the total response time in milliseconds by the total payload response size in MB, across all API calls for all API endpoints for each day. | An Average TTLB of 750 milliseconds per response, or per page of results for up to 100 records for larger payloads. In practice, all but transactions and statements are likely to be small payloads without pagination. |
Confirmation of Funds (CoF) response time (PISP) | For the purpose of calculating the performance indicators, the ASPSP should:
a) calculate the daily average time (in milliseconds) taken, per request, for the ASPSP to provide the PISP with a ‘yes/no’ confirmation.
| The "time taken per request" should be calculated for each day using the mean value of Time to Last Byte (TTLB) measured in milliseconds, starting from the time that each endpoint request has been fully received by the ASPSP and stopping when the last byte of the response message (i.e. the 'yes/no' confirmation) has been transmitted to the PISP. The following API endpoints should be included when calculating CoF response times for PISP:
| An average TTLB of 300 and a max of 500 ms per response. |
Daily error response rate | For the purpose of calculating the performance indicators, the ASPSP should: a) Calculate the daily error response rate – calculated as the number of error messages concerning errors attributable to the ASPSP sent by the ASPSP to the PISPs, or AISPs per day, divided by the number of requests received by the ASPSP from PISPs or AISPs in the same day.
| It is not possible for ASPSPs to respond to AISPs/PISPs with an error message where no TLS (Transport layer security) session has been established. However, ASPSPs should still be able to respond, measure and report on errors relating to endpoint calls and all functional API calls. The error response rate should be calculated as the total number of all 5xx HTTP status codes from all API endpoints per day, divided by the total number of AISP/PISP API requests received across all of these endpoints in the same day, and expressed as a percentage. Errors based on 4xx HTTP status codes are largely attributable to AISP/PISP or user/customer actions or failures, and hence should not be included here. | An average of 0.5% across all endpoints. |
...
Functionality: The facility should include all functionality of the production interface relating to AISP and PISP use cases. This functionality should work in an equivalent or representative way to the production interface including negative use cases and error codes.
Security: The facility should use the same security profile/model and be configured in the same way as that which protects the production APIs.
On-boarding: The facility should replicate the on-boarding process of the ASPSP's production facility, including AISP/PISP on boarding.
Test data: The facility must not include any real user/customer data. The volume and variance of data should be sufficient to support all technical and functional testing including pagination (where this is supported in the dedicated interface).
Test accounts: The facility should provide AISPs/PISPs with a number of test accounts that enable the functionality and access to data that real users/customers will experience in production.
Authentication: The facility should enable AISPs/PISPs to use 'headless authentication', i.e. authentication which does not require a user/customer to be present, therefore enabling multiple tests to be run in succession via automated scripts. Additionally, ASPSPs to allow AISPs/PISPs to test all authentication procedures provided to its users/customers, but ideally ASPSPs should not prevent 'headless authentication' testing to be conducted by the AISP/PISP as well. This may be catered for by ASPSPs either:
o allowing AISPs/PISPs to test both headless and user/customer authentication procedures in the same facility;
o providing a separate testing facility in order to test all authentication procedures; or
o allowing AISPs/PISPs to test user/customer authentication procedures in a production environment using their own and/or test accounts.
Availability and performance: The facility is not expected to handle production volumes (i.e. is not expected to be used by ASPSPs or AISPs/PISPs for stress testing), however, it should have sufficient availability, capacity, performance and other characteristics to facilitate effective and realistic connection and functional AISP/PISP testing.
Ongoing access: The facility should remain as an ongoing facility and to support future development or changes to the dedicated interface at least 3 months prior to implementation of such changes.
Support: The facility should have an appropriate level of support to enable communication of problems or issues by AISPs/PISPs to ASPSPs and to provide efficient and effective solutions.
Documentation: ASPSPs must publish externally a summary of the specification of the testing facility on their website including access details and test coverage.
The testing facility should thereby enable AISPs/PISPs to successfully execute full API journeys to support their proposition with the expectation that they will be able to use the same code base when connecting to the ASPSP’s production interface. In particular, this facility must ensure the API interface meets the requirements of a stable and secure connection, and the ability to exchange production and testing certificates.
...
Connection details (including all technical and business processes required to connect).
Methods of authentication available to users/customers (e.g. OTP via SMS, Fingerprint etc. and how this varies by device).
Authentication flows supported (e.g. redirect, decoupled).
Functionality and data elements for each AISP and PISP endpoint, including which optional elements are/are not provided.
5. Change and Communication Management
...
ASPSPs must be compliant with the latest version of Bahrain OBF in order to meet both regulatory and commercial requirements.
ASPSPs must publish technical specification documentation for their dedicated interface, well in advance before the target date of the market launch of the dedicated interface.
ASPSPs must give AISPs/PISPs at least three months’ notice of any change to the technical specifications, unless the changes can be rolled out sooner, in which case ASPSPs must notify AISPs/PISPs on the change as soon as possible . In practice, this means that ASPSPs must give such notice if they are planning to introduce any updates to any component of the dedicated interfaces, Any change may be implemented in an emergency situation (e.g. in the case where there is a security issue) without such notice, and in such situations ASPSPs must document emergency situations where changes are implemented and make the documentation available to competent authorities on request.
ASPSPs must also make available a testing facility (sandbox) well in advance before the target date of the market launch of the dedicated interface. ASPSPs should ensure that any changes are made available in the testing facility as soon as possible to allow AISPs/PISPs to test against the updated technical specifications. In practice, this means that ASPSPs should consider the impact of proposed changes on their testing facility in order to ensure that the testing facility enables the same functionality as the dedicated interface, in the context of such changes. As such, ASPSPs should endeavor to make any changes to the testing facility available to AISPs/PISPs at least three months before changes are implemented to ensure AISPs/PISPs, can continue to effectively test.
ASPSPs should maintain multiple live/active versions of each interface (e.g. one for each supported release).
Where an ASPSP decides to implement a new version of any component of the Bahrain OBF they should implement each new major version within six months, and each new minor version within three months of the Bahrain OBF being published.
Together with the requirements for ASPSPs to notify AISPs/PISPs of any changes any AISP/PISP will, except in an emergency, always have at least three months’ notice before being required to update their systems.
5.2.2 Considerations
5.2.2.1 Dual Running and Depreciation
...
A long-lived consent (e.g. for access to AISP resources) created using an older version of the APIs can be used for read operations in newer versions of the API.
A short-lived consent (e.g. for a payment initiation request) can only be used within the same version of the API for creating resources.
If an ASPSP is planning to release a new API version that does not follow the expectations above (e.g. does not support forward compatibility for AISP resources) this should be communicated to AISPs/PISPs.
...
For example, if the ASPSP has implemented a new authorization server, AISPs/PISPs will need to ask their users/customers to re-authenticate with the ASPSPs. Users/Customers may lose service entirely if there is any delay in an AISP/PISP re-connecting to the ASPSP. Users/customers may have to re-authenticate to renew long-lived consent (e.g. for the AISP/PISP to continue to access the user/customer's data).
...
When informing AISPs/PISPs of an anticipated change, an ASPSP should confirm:
Date notice is given.
Details of the change that will be made (e.g. implementation of new version).
Reason for the change (e.g. new version to be implemented, old version to be deprecated, etc.).
Details of ASPSP system(s) affected (e.g. test facility, production interface).
Details of how any change will be made available in the test facility in advance of the production interface.
Indication of the likely impact for an AISP/PISP, including any action required by AISPs/PISPs (e.g. requiring users/customers to re-authenticate).
Start time/date the change is anticipated to take effect and the end date/time (if applicable).
6. Exemptions to Protect Service
...
Periods of time when the digital channels for the ASPSP are the target for a distributed denial of service or equivalent form of attack (this should result in http error “429 Too Many Requests” being returned).
A significant increase in traffic from a poorly designed or misbehaving AISP/PISP (this should result in http error “429 Too Many Requests” being returned).
If the ASPSP identifies a situation where there is the potential for physical or financial harm or abuse (this should result in http error “403 Forbidden” being returned).
In the event of a cyber-threat or risk of fraud/ phishing attack where the user/customer data may be at risk.
CENTRAL BANK OF BAHRAIN © 2020