Operational Guidelines
1. Version Control
Version | Date | Description of Changes |
Bahrain OBF v1.0.0 | 28th Oct 2020 | Initial Release |
2. Overview
The Operational Guidelines set out criteria, guidance and requirements for Account Servicing Payment Service Providers (“ASPSPs”) to deliver an effective Open Banking ecosystem and meet the needs of Account Information Service Providers (“AISPs”) and Payment Initiation Service Providers (“PISPs”) in providing services to users/customers.
These guidelines provide recommended benchmarks to support ASPSPs in complying with Open Banking guidelines and help track availability and performance of data generating APIs. On adoption of the Operational Guidelines, ASPSPs will be in a better position to successfully demonstrate the availability and performance of APIs and their active interactions with AISPs and PISPs in the market.
The Operational Guidelines have the following objectives:
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)
Reduce Reputational Risk: Protect the reputation of ASPSPs/AISPs/PISPs and the Open Banking ecosystem as a whole
3. Availability and Performance
This section outlines various API availability and performance requirements and recommendations for ASPSPs in Bahrain. AISPs and PISPs are dependent on the well-established interfaces provided by ASPSPs so that they can in turn provide reliable services to their users/customers.
3.1 Key Indicators for Availability and Performance
The following tables set out, for each requirement:
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.
For an effective Open Banking ecosystem to thrive, there is a need for industry-wide benchmarks, referred to as the "Recommended Benchmarks". Since these guidelines are based on global best practices, these will be reviewed on a regular basis in consultation with industry stakeholders. ASPSPs should refer to the recommended best practices for their interfaces.
Additionally, the guiding principle of these benchmarks is that ASPSPs must ensure (at least) parity between the availability and performance of the best performing interface (that they own and maintain to interact directly with customers) and that of their Open Banking interface which may be leveraged by AISP/PISPs.
3.1.1 Availability
The definition of a period of availability is a period of time when any of the API end points defined in the Bahrain Open Banking Framework (Bahrain OBF) are able to reliably provide a successful response to an appropriately constructed request.
AISPs/PISPs may consider that an API is only available if it is responding to all valid AISP/PISP requests:
Without error messages
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).
Table 1 – Key Indicators based on best practices for Availability
Title | Requirement | Calculation Guidelines | Recommended Benchmark |
The uptime per day of all interfaces | For the purpose of calculating the availability indicators, the ASPSP should:
| 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 not directly attributable to the ASPSP, 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). |
[1] This is the benchmark for business as usual/normal conditions and not in cases of force majeure events such as natural calamities, war, cyber threats etc.
3.1.2 Performance
The Bahrain OBF defines a number of endpoints which should be made available by ASPSPs. The Performance of API end points should be measured in response time of individual API requests from receipt of request to delivery of response. While all supported endpoints should be included by ASPSPs when calculating error rates, for reporting response times the consent endpoints should be ignored, as these are not considered part of the process of 'providing the information requested' to the AISP/ PISP for account information or payment initiation.
This section sets out a minimum of four KPIs for performance that an ASPSP should have in place for each of its API. The following table explains these KPIs in detail and provides guidance on how they should be calculated.
Table 2 – Key Indicators based on best practices for Performance
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. |
3.2 Traffic Thresholds
The CBB may leverage the monitoring reports submitted by the ASPSPs and other parties, to decide on the traffic thresholds. Basis the usage and adoption of these APIs, the related structures for threshold limits may be established on a future date.
Until the CBB decides on these thresholds, ASPSPs must provide data access to AISPs/PISPs through API calls without any limits or charges.
3.3 Publication of Statistics
ASPSPs must publish to the CBB, statistics on the availability and performance of APIs on a monthly basis as set out in these guidelines.
These statistics should be completed for every API. In case where an ASPSP maintains different versions of their APIs in parallel, then these should be considered as separate APIs and published separately, as they may have different levels of availability and performance.
3.3.1 ASPSP Reporting
The table below provided description/guidance for calculating each element in regard to user/customer interface availability and performance:
Table 3 – Description of ASPSP Reporting elements
# | Field Name | Description/ Definition |
1 | Performance and Availability | |
1.1 | Report Date | The reported date for each calendar day. |
1.2 | Entity Name | Reporting entity’s name. |
1.3 | Endpoint ID | Reported EndPoint ID as defined in the API Endpoint List of the Reporting Template. ASPSPs/ AISPs/ PISPs must only report endpoints that have gone live in their systems. |
1.4 | Uptime | Uptime per each individual endpoint in hours and minutes. (Elapsed time) Calculated as 100% minus the total percentage downtime for each day. |
1.5 | Planned Downtime | Any planned duration that the API endpoints become unavailable. For the avoidance of doubt, this extends to include all systems that are required for the relevant endpoint to be fully functional. |
1.6 | Unplanned Downtime | Any unplanned duration that the API endpoints become unavailable due to technical faults or any other reasons. For the avoidance of doubt, this extends to include all systems that are required for the relevant endpoint to be fully functional. |
1.7 | Max Payment Initiations Per Second (PIPS) | This field is only applicable to Payment Initiation Service (PIS) endpoints. For Account Information Service (AIS) endpoints it should be populated with NULL. The maximum number of successful payment initiations per second (PIPS) for the payment order POST API calls. The PIPS must be reported as whole numbers. |
1.8 | Average TTLB Response Time (Time to Last Byte) | The average (mean) value across all values of Time to Last Byte (TTLB) response time for each API endpoint. The response time clock should start at the point the endpoint call is fully received by the ASPSP and should stop at the point the last byte of the response message is transmitted to the AISP or PISP. |
1.9 | Highest TTLB Response Time (Time to Last Byte) | The highest value of Time to Last Byte (TTLB) response time for each API endpoint. The response time clock should start at the point the endpoint call is fully received by the ASPSP and should stop at the point the last byte of the response message is transmitted to the AISP or PISP. The response time must be reported in milliseconds. |
1.10 | Lowest TTLB Response Time (Time to Last Byte) | The lowest value of Time to Last Byte (TTLB) response time for each API endpoint. The response time clock should start at the point the endpoint call is fully received by the ASPSP and should stop at the point the last byte of the response message is transmitted to the AISP or PISP. The response time must be reported in milliseconds. |
1.11 | Average TTFB Response Time (Time to First Byte) | The average (mean) value across all values of Time to First Byte (TTFB) response time for each API endpoint. The response time clock should start at the point the endpoint call is fully received by the ASPSP. The response time must be reported in milliseconds. |
1.12 | Highest TTFB Response Time (Time to First Byte) | The highest value of Time to First Byte (TTFB) response time for each API endpoint. The response time clock should start at the point the endpoint call is fully received by the ASPSP. The response time must be reported in milliseconds. |
1.13 | Lowest TTFB Response Time (Time to First Byte) | The lowest value of Time to First Byte (TTFB) response time for each API endpoint. The response time clock should start at the point the endpoint call is fully received by the ASPSP. The response time must be reported in milliseconds. |
1.14 | Total Number of API calls | This is the total number of API calls per day per endpoint. |
1.15 | Total TTLB Response Time (Time to Last Byte) | This is the sum of all the TTLB responses of all endpoint calls of each endpoint type. For the avoidance of doubt, this is the sum of all the TTLB response times generated by the total number of API calls for each endpoint. |
1.16 | Total TTFB Response Time (Time to First Byte) | This is the sum of all the TTFB responses of all endpoint calls of each endpoint type. For the avoidance of doubt, this is the sum of all the TTFB response times generated by the total number of API calls for each endpoint. |
1.17 | Total ResponsePayload Size | This is the sum of the payload of all the response messages for all endpoint calls of each endpoint type. For the avoidance of doubt, this is the sum of all the payloads of the response messages generated by the total number of API calls for each endpoint. |
2 | Authentication | |
2.1 | Report Month | Reported calendar month and year (from 1st day of the month starting from 00:00:00 till last day of the month 23:59:59). |
2.2 | Entity Name | Reporting entity’s name. |
2.3 | Authentication Type | This is the type of authentication journeys provided by the ASPSP. It will include 'redirection' and where implemented 'decoupled' model. |
2.4 | API Type | This is the type of services that are being reported for the efficacy of the authentication journey. It includes Account Information Services (AIS) and Payment Initiation Services (PIS). |
2.5 | API Request AISP/PISP Channel | This is the reported AISP/PISP channel for initiating the AIS or PIS consent. This may be provided by AISP/PISPs in the endpoint Request Header under the field 'x-customer-user-agent'. If the string cannot be mapped to a browser, then it will be a mobile app. |
2.6 | ASPSP Authentication Channel | This is the reported ASPSP Authentication channel. It can be web-based (Web) or using the mobile banking app (App). |
2.7 | Consents requiring Authentication | The total number of user/customer consents to require authentication at the ASPSP for the particular combination of authentication type, API type, AISP/PISP channel and ASPSP authentication channel. |
2.8 | Authentications Attempted by users/customers | The total number of authentications that have been attempted by the users/customers (not abandoned). This means that the Users/ Customers have tried to authenticate according to the authentication method required providing biometrics, username, passwords etc. |
2.9 | Authentications Abandoned by users/customers | The total number of user/customer consents to require authentication that has been abandoned by the users/customers. |
2.10 | Authentications Succeeded | The total number of consents requiring authentication that have completed authentications by users/customers and the authentications have succeeded. |
2.11 | Authentications Failed | The total number of consents requiring authentication that have completed authentications by users/customers and the authentications have failed. |
2.12 | Confirmations Required | The total number of consents requiring authorization, that after successful authentication, required a confirmation step. |
2.13 | Confirmations Accepted by user/customer | The total number of successful authentications that required a confirmation step and have been accepted by users/customers. This means that the users/customers proceeded with the access request or the payment order submission and did not cancel the process. |
2.14 | Confirmations Rejected by users/customers | The total number of successful authentications that required a confirmation step and have been rejected by users/customers. This means that the users/customers cancelled the process and did not proceed with the access request or the payment order submission. |
2.15 | Average Authentication Response Time | The average (mean) value across all values of authentication response time for each API endpoint. The response time clock should start when the authentication process has started and should stop when the authentication process has completed/ended. The response time must be reported in milliseconds. |
3 | User/Customer Volumes | |
3.1 | Report Month | Reported calendar month and year (from 1st day of the month starting from 00:00:00 till last day of the month 23:59:59). |
3.2 | Entity Name | Reporting entity’s name. |
3.3 | Retail/Business user/customer | This identifies Retail and Business users/customers for separate reporting. |
3.4 | User/Customer used AIS for the first time | The number of unique users/customers who have authorised access to their account(s) to one or more AISPs for account information services for the first time during the reporting period. For the avoidance of doubt, this refers to new consent/authorisations and not re-authorisations. |
3.5 | User/Customer re-authorised for using AIS | The total number of unique users/customers who have previously authorised access to their account(s) to one or more AISPs for account information services and had to re-authenticate to refresh the account access at least for one of the AISPs during the reporting period. |
3.6 | Total users/customers used AIS | The total number of unique users/customers who: a. have authorised access to their account(s) to one or more AISPs for account information services during the reporting period for the first time. b. have previously authorised access to their account(s) to one or more AISPs for account information services and had their account accessed at least once by any of the AISPs during the reporting period. c. have previously authorised access to their account(s) to one or more AISPs for account information services and had to re-authenticate to refresh the account access at least for one of the AISPs during the reporting period. |
3.7 | User/Customer used PIS for the first time | The number of unique user/customer who have authorised a payment initiation of any type from any of their account(s) via one or more PISPs for the first time during the reporting period. For the avoidance of doubt, a user/customer initiating a payment (e.g. single domestic) using a PISP A and then initiating another payment of different type (e.g. international) using a PISP B within the same ASPSP , should not be double-counted. For business customers, unique users/customers should refer to all employees of the business who have separate authentication credentials and can be identified separately. Multi-banked users/customers cannot be identified so they may be double-counted by different ASPSPs. |
3.8 | Total users/customers used PIS | The total number of unique users/customers who: a. have authorised a payment initiation of any type from any of their account(s) via one or more PISPs for the first time during the reporting period. b. have authorised a payment initiation of any type from any of their account(s) via one or more PISPs during the reporting period and have initiated payments using PIS services before. |
3.9 | Unique users/customers used both AIS and PIS for the first time | Users/Customers accessing both AIS and PIS using the same authentication credentials. |
3.10 | Total unique users/customers used both AIS and PIS | Total users/customers accessing both AIS and PIS using the same authentication credentials. |
3.11 | Total new users/customers for Online Banking | The number of unique users/customers who have been granted access to Online Banking for the first time. |
3.12 | Total new users/customers for Mobile Banking | The number of unique users/customers who have been granted access to Mobile Banking for the first time. |
3.13 | Total number of users/customers used Online Banking | The total number of unique users/customers who have used the Online Banking service for either accessing account information or initiating a payment. |
3.14 | Total number of users/customers used Mobile Banking | The total number of unique users/customers who have used the Mobile Banking service for either accessing account information or initiating a payment. |
4 | AISP/PISP Volumes | |
4.1 | Report Month | Reported calendar month and year (from 1st day of the month starting from 00:00:00 till last day of the month 23:59:59). |
4.2 | Entity Name | Reporting entity’s name. |
4.3 | Total AISPs Registered (at 1st of the month) | This is the cumulative total number of AISP’s, that have been already been on-boarded into the live environment (i.e. production environment) with the ASPSP as at the 1st of the reported month. |
4.4 | AISP Additions | This is the number of AISPs that have been on-boarded into the live environment (i.e. production environment) during the reported month. |
4.5 | AISP Deregistrations | This is the number of AISPs, that have been deregistered with the ASPSP during the reported month. |
4.6 | Cumulative Monthly number of AISPs | This is the cumulative total number of AISP’s, that have been already been on-boarded into the live environment (i.e. production environment) with the ASPSP as at the end of the reported month. |
4.7 | Total PISPs Registered (at 1st of the month) | This is the cumulative total number of PISP’s, that have been already been on-boarded into the live environment (i.e. production environment) with the ASPSP as at the 1st of the reported month. |
4.8 | PISP Additions | This is the number of PISPs that have been on-boarded into the live environment (i.e. production environment) during the reported month. |
4.9 | PISP Deregistrations | This is the number of PISPs, that have been deregistered with the ASPSP during the reported month. |
4.10 | Cumulative Monthly number of PISPs | This is the cumulative total number of PISP’s, that have been already been on-boarded into the live environment (i.e. production environment) with the ASPSP as at the end of the reported month. |
5 | Daily Volumes | |
5.1 | Report Date | The reported date for each calendar day. |
5.2 | Entity Name | Reporting entity’s name. |
5.3 | Endpoint ID | Reported EndPoint ID as defined in the API endpoint list of the Reporting Template. ASPSPs must only report endpoints that have gone live in their systems. |
5.4 | Successful API Calls (200, 201 or 204 codes) | This is the total number of successful endpoint calls for each endpoint that has been received successfully by the ASPSP and generated an AISP/PISP Status Code of 200, 201 or 204 depending on the HTTP method of the endpoints. |
5.5 | Failed API Calls Business Reasons (4xx Codes) | This is the total number of failed endpoint calls for each endpoint that have been received by the ASPSP and failed due to business rules reasons generating an HTPP Status Code of 4xx). Kindly refer to the global standards of HTTPS Status Code Registry (https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml) for the individual type of error codes/messages. |
5.6 | Failed API Technical Calls Reasons (5xx Codes) | This is the total number of failed endpoint calls for each endpoint that have been received by the ASPSP and failed due to technical reasons (generating an HTPP Status Code of 500-599). Kindly refer to the global standards of HTTPS Status Code Registry (https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml) for the individual type of error codes/messages. |
5.7 | API Calls Rejected Status | This is the total number of rejected endpoint calls that have been rejected for each defined endpoint which might be due payment/account consent being rejected due to authorisation failing or consent authorisation being rejected, payment initiation being rejected as part of proceeding checks such as technical validation and customer profile. |
3.3.1.1 Reporting Template
A reporting template has been provided by the CBB that ASPSPs might find useful in preparing their information for publication and reporting to the CBB. Please refer – Operational Guidelines Reporting Template v1.0.0 for the template.
ASPSPs must publish their statistics using this template to the CBB on a monthly basis. Additionally, the CBB may request ASPSPs to publish their statistics using the template along with the calculation methodology as and when needed. This will enable the CBB to track the overall health and growth of the Open Banking ecosystem.
Where ASPSPs support more than one API version in production, each version must be reported separately. For example, v3.0 and v3.1 must be reported separately.
In the absence of any relevant information, the ASPSPs must return with a “NIL” response.
3.3.2 AISP/PISP Reporting
AISPs and PISPs should report statistics on availability and performance to the CBB (leveraging the same template as ASPSPs) on a quarterly basis.
4. Dedicated Interface Requirements
This section provides guidance for ASPSPs to demonstrate that their dedicated interface has been designed and tested in line with the requirements laid out in the Security Standards and Guidelines and the CBB Rulebook.
This is deemed essential in order for ASPSPs to successfully deliver the necessary functionality for the Open Banking ecosystem and to facilitate the creation of seamless customer experiences, which do not constitute obstacles for the provision of AISP/PISP services.
The ASPSPs must ensure consistent engagement with AISPs/PISPs within their design and testing processes so that issues are identified and rectified as early as possible. Wide usage of the dedicated interface is required to show that it is capable of supporting a diverse set of AISP/PISP business models and use cases.
The Bahrain OBF has outlined customer experience requirements and considerations for ASPSPs to consider supporting the adoption of Open Banking in Bahrain.
4.1 Testing
4.1.1 Testing Facility
ASPSPs are required to provide a Testing Facility or sandbox to allow AISPs/PISPs to undertake connection and functional testing of their products and services using non-user/customer (i.e. “dummy”) data. The issues and problems which are identified within this testing process, as well as feedback and engagement from the AISP/PISP community, are useful for ASPSPs in alerting them to potential issues within testing that may also be encountered within the production environment. This can be used to identify and address issues early on.
This facility should[2] provide an accurate reflection of the live environment, and give AISP/PISP developers access to the following:
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 onboarding
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:
allowing AISPs/PISPs to test both headless and user/customer authentication procedures in the same facility
providing a separate testing facility in order to test all authentication procedures
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.
[2] For the avoidance of doubt, the following are all recommendations only and optional for ASPSPs, unless referring to direct regulatory guidance.
4.1.2 Publishing Specification Details
ASPSPs should publish the details of the specifications on their website well in advance before the ASPSP’s dedicated interface is launched.
Implementations of the specifications must be machine readable, so that AISPs/PISPs can automate discovery, and include the following details by product:
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
This section outlines various change scenarios that may impact AISPs/PISPs and provides guidance for an ASPSP to consider when implementing a change and communicating to AISPs/PISPs.
Any change that may impact an AISP’s/PISP's ability to deliver its services has the potential to cause a loss of business, reputational risk or to add additional resource cost to the AISP/PISP and result in a negative outcome for their users/customers. The ability to identify the potential impact that proposed changes by an ASPSP may have and to communicate those changes to AISPs/PISPs, is key to a successful Open Banking ecosystem.
The information that an ASPSP should include in its communication to an AISP/PISP is listed at 5.4 Notification of a change.
5.1 Downtime
Downtime is defined in Section 3.
Planned downtime, by its nature, is something that an ASPSP anticipates and therefore is able to give advance notice to AISPs/PISPs. It is not generally possible to give advanced notice of unplanned downtime, but ASPSPs should give notice as soon as they are aware of the downtime.
The impact of any downtime can be minimized by an ASPSP informing AISPs/PISPs as soon as the downtime is anticipated, when it takes effect and as soon as the service is reinstated. ASPSPs should therefore provide notice of downtime notifications which should be published on their own website or developer portal and the CBB’s central notice board.
When providing notifications, ASPSPs should provide a specific time period, so AISPs/PISPs are aware that the dedicated interface will be unavailable for that time, or upon a subsequent notification to confirm that the service has been reinstated sooner than anticipated.
These guidelines do not distinguish between planned and unplanned downtime. As such, when an ASPSP engages in planned downtime activities, these must be considered within the context of their obligations to ensure that their dedicated interface targeted levels of availability are at least as stringent as those for the user/customer interface, including maintenance, problem resolution, out of hours support, monitoring and contingency plans. Planned downtime should not therefore be implemented in a way that it may impact the required target service levels for the dedicated interface.
ASPSPs can provide advance notice for future planned downtime and submit real time updates related to downtime (planned or unplanned) that currently impact AISPs/PISPs and the subsequent reinstatement of service.
Based on global best practices, notification for planned downtime should be given with at least five business days’ prior to the event. Apart from cancelling the planned downtime, no changes should be made to the planned downtime notification within the five business day period. Where practical, ASPSPs should give advance notice via their own website, developer portal and to the CBB of any planned downtime one calendar month in advance.
In the event that the interface does not offer at least the same level of availability and performance as the user/customer interface(s), if there is unplanned downtime, or if there is a system breakdown, ASPSPs are required to have 'contingency measures' in place which include a strategy and communication plan to inform the AISPs/PISPs of measures being undertaken to restore the system and a description of immediately available alternate options that AISPs/PISPs may have during this time.
ASPSPs should make this plan available to AISPs/PISPs (e.g. on their website or developer portal) so that they know in advance what to do in the event of unplanned downtime.
5.2 Implementing changes to the Bahrain Open Banking Framework
The Bahrain Open Banking Framework (Bahrain OBF) will continue to evolve over time to cater for potential improvements/clarifications, agreed Open Banking roadmap requirements and approved changes (which may include adding new functionality, fixing defects, and errata). Where possible, new versions of the Bahrain OBF will be scheduled with sufficient time for change so that ASPSPs can plan ahead and build new APIs to this plan, this will therefore reduce development and support costs for all participants and increase adoption.
5.2.1 Introducing Change
This section details out the guidelines for ASPSPs to communicate the change in their interface to an AISP/PISP and the following conditions are recommended:
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
This section details out the requirements to be followed by the ASPSPs during the instance of new API version migration. ASPSPs should support a minimum of two API versions in a production context if both versions were previously supported by the ASPSP. Dual running for at least six months for a major version, and three months for a minor version. This is to ensure that AISPs/PISPs have had sufficient time to successfully test the new version of ASPSPs and migrate their applications and customers. An ASPSP implementing an API for the first time will only need to support one version to start with.
The ability to support two API versions allows AISPs/PISPs to maintain existing integrations with the older version, and benefit from features and enhancements offered by the new version. Over time, AISPs/PISPs will migrate all their applications to consume the new API version. Once migrated, AISPs/PISPs should not access resources via the old API version (including creating, reading, updating or deleting).
Dual running of APIs requires a pragmatic approach to ensure that ASPSPs expose and support both API versions and to ensure that AISPs/PISPs use these to migrate applications as intended, without unnecessary conflict.
The deprecation of unsupported versions is at the ASPSP's discretion - based on usage metrics. However, the CBB may recommend that any specified version should be deprecated at any time, and this should be implemented within a fixed period of time as notified.
5.2.2.2 API Credentials, Consent and Authorization
API Credentials associated to an API should be version agnostic. Therefore, an AISP/PISP accessing v1.0, v1.1 or v2.0 should be able to use the same API Credentials across all available API endpoints.
It is in the domain of the AISPs/PISPs to manage users/customers consent and ASPSPs to manage user/customer authentication in compliance with relevant regulations.
In the event of a breaking change (e.g. where a permission/cluster is added, removed or changed) or a non-breaking change (e.g. an additional field is added to a permission/cluster), then the user/customer may be required to re-consent with the AISP/PISP and to re-authenticate with the ASPSP.
5.2.2.3 Backward and Forward Compatibility
The API specifications will include details on which operations or resources are expected to be backward and forward compatible across versions. It is expected that:
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.
5.3 Changes to an ASPSP’s Infrastructure, Configuration or Software
At any time, an ASPSP may need to make changes to any element of their system, including implementation of a new version (as described above). This includes the adding/removing of functionality or fields within an existing version. This may or may not require downtime.
In such cases, AISPs/PISPs may need to update and re-onboard their application, and then re-test it in order to continue offering services via the ASPSP. This may result in increased costs, reduced revenue, and potentially customer loss, since services that users/customers rely on may be interrupted without prior warning.
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).
Where ASPSPs make such changes they should:
Give AISPs/PISPs a minimum of three months’ notice of any such change, unless this is an emergency situation
Document emergency situations where changes were made and make the documentation available to the CBB
To facilitate this, ASPSPs should report all changes to the CBB that require AISPs/PISPs to update/edit their code, where notice of any change may be added by the CBB to its website to inform the ecosystem.
5.4 Notification of a change
ASPSPs should provide notice to AISPs/PISPs of a change (within the time frames outlined above) via the ASPSP's own website or developer portal and through the CBB’s central notice board.
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
In the event of the following extreme circumstances, ASPSPs will be able to obtain relief from non-functional requirements:
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