Glossary

Account Information Services Provider or ‘AISP’ refers to a person licensed by the CBB to provide account information services using an online portal, mobile or smartphone application, device or other electronic media which a consenting customer can use to obtain aggregate or consolidated information about his/her account balances with ASPSP. The role of an AISP is restricted to providing the technology or other means in order to provide account information to the customer and the handling of communication or electronic documents between the customer and the licensees should the terms of the offer include such services. AISPs must not receive or otherwise handle customer funds in the course of providing account information services.

An Application Programming Interface or ‘API’ is a set of routines, protocols, and tools for building software applications. An API specifies how software components should interact.

Account Servicing Payment Service Providers or ‘ASPSP’ refers to the CBB licensees (include conventional retail bank licensees and Islamic retail bank licensees) who provide and maintain a payment account for a user/customer and, in the context of the Open Banking Ecosystem are entities that publish Read/Write APIs to permit, with customer consent, payments initiated by third party providers and/or make their customers’ account transaction data available to third party providers via their API endpoints.

Bahrain Open Banking Framework or ‘Bahrain OBF’ has been developed considering the relevant use cases (payments as well as account information sharing) that has several business opportunities for the banks and third party providers (TPPs) and caters to the customer’s unique needs in Bahrain. The framework covers both technical as well as non-technical aspects of Open Banking.

Consumer Device Cardholder Verification Method or ‘CDCVM’ is a card network supported verification process performed by the customer and is applicable when the customer assesses transactions originating from mobile devices. CDCVM helps evaluate the legitimate owner of the payment instrument.

The API requests and responses must use a UTF-8 character encoding. This is the default character encoding for JSON (RFC 7158 - https://tools.ietf.org/html/rfc7158#section-8.1)
However, an ASPSP's downstream system may not accept some UTF-8 characters, such as emoji characters (e.g. "J" may not be an acceptable Payment Reference). If the ASPSP rejects the message with a UTF-8 character that cannot be processed, the ASPSP must respond with an HTTP 400 (Bad Request) status code.

Client-Initiated Backchannel Authentication or ‘CIBA’ is an authentication flow in which AISPs/PISPs, that can obtain a valid identifier for the user they want to authenticate, will be able to initiate an interaction flow to authenticate their users without having end-user interaction from the consumption device. The flow involves direct communication from the Client to the ASPSPs without redirection through the user's browser (consumption device).

Functionality, endpoints and fields marked as Conditional may be required in some cases for regulatory compliance (for example, if these are made available to the user/customer in the ASPSP's existing Online Channel, or if ASPSPs (or a subset of ASPSPs) have been mandated by a regulatory requirement).
For functionalities and endpoints:

• An ASPSP must implement functionality and endpoints marked as Conditional if these are required for regulatory compliance

For fields:

• All fields that are not marked as Mandatory are Conditional

• An AISP/PISP may specify the value of a Conditional field

• An ASPSP must process a Conditional field when provided by the AISP/PISP in an API request and must respond with an error if it cannot support a particular value of a Conditional field

An ASPSP must include meaningful values for Conditional fields in an API response if these are required for regulatory compliance.

Kindly refer to https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml for the HTTP response codes for different HTTP methods, across all Read/Write API endpoints.

An idempotency key is used to guard against the creation of duplicate resources when using the POST API endpoints (where indicated).
If an idempotency key is required for an API endpoint:
The x-idempotency-key provided in the header must be at most 40 characters in size. If a larger x-idempotency-key length is provided, the ASPSP must reject the request with a status code is 400 (Bad Request).

• The AISP/PISP must not change the request body while using the same x-idempotency-key. If the AISP/PISP changes the request body, the ASPSP must not modify the end resource. The ASPSP may treat this as a fraudulent action.

• The ASPSP must treat a request as idempotent if it had received the first request with the same x-idempotency-key from the same AISP/PISP in the preceding 24 hours.

• The ASPSP must not create a new resource for a POST request if it is determined to be an idempotent request.

• The ASPSP must respond to the request with the current status of the resource (or a status which is at least as current as what is available on existing online channels) and an HTTP status code of 201 (Created).

• The ASPSP may use the message signature, along with the x-idempotency-key to ensure that the request body has not changed.

If an idempotency key is not required for an API endpoint:

• The ASPSP must ignore the idempotency key if provided.

JavaScript Object Notation or ‘JSON’ is a lightweight data-interchange format. It is easy for humans to read and write. It is easy for machines to parse and generate. JSON is a text format that is completely language independent but uses conventions that are familiar to programmers of the C-family of languages, including C, C++, C#, Java, JavaScript, Perl, Python, and many others.

Functionality, endpoints and fields marked as Mandatory are required in all cases for regulatory compliance and/or for the API to function and deliver essential customer outcomes.
For functionalities and endpoints:

• An ASPSP must implement an endpoint that is marked Mandatory

• An ASPSP must implement functionality that is marked Mandatory

For fields:

• An AISP/PISP must specify the value of a Mandatory field

• An ASPSP must process a Mandatory field when provided by the AISP/PISP in an API request

• An ASPSP must include meaningful values for Mandatory fields in an API response

This is an informed suggestion but that the point is optional.

Message encryption is implemented through JSON Web Encryption (JWE).
The approach differs from message signing in that:

• The entire request or response payload is delivered in the form of an encrypted JWT.

• The definition of a given request or response in the Swagger specification represents the decrypted payload.

• The JWE will not be represented in its encrypted form in the Swagger specifications.

• Sending or expecting to receive an encrypted payload is denoted by setting the Accept or Content-type header to application/jose+jwe.

If an ASPSP does not support message encryption then should reject any requests with a Content-type or Accept headers that indicate that message encryption is required.

The APIs require TLS 1.2 Mutual Authentication and this may be used as a means of non-repudiation. However, it would be difficult to maintain digital records and evidence of non-repudiation if the API only relied on TLS 1.2.
A solution for non-repudiation that does not rely on TLS, would be achieved by providing a JWS with detached content (as defined in RFC 7515 - Appendix F) in the HTTP header of each API request.
The HTTP body would form an un-encoded payload as defined in RFC 7797.
The JWS would be signed using an algorithm that supports asymmetric keys.
A request would be signed by an AISP/PISP's private key and a response would be signed by the ASPSP's private key.
Not all API requests and responses are signed. Whether message signing is mandatory, supported or not supported is documented along with each API.

This is an absolute requirement as per Bahrain OBF.

This is an absolute prohibition as per Bahrain OBF.

Open Banking is the secure way to give providers access to customer’s financial information. It opens the way to new products and services that could help customers and small to medium-sized businesses get a better deal. It could also give you a more detailed understanding of customer’s accounts, and help customers find new ways to make the most of their money.
Open banking also refers to sharing and leveraging of data (for which customer has consented) by banks with third party developers and firms to build applications and services. For example, third party providers (TPPs) provide real-time payments, greater financial transparency options for account holders, marketing and cross-selling opportunities.

Functionality and endpoints marked as Optional are not necessarily required for regulatory compliance but may be implemented to enable desired customer outcomes.

For functionalities and endpoints:

• An ASPSP may implement an Optional endpoint

• An ASPSP may implement Optional functionality

For fields:

• There are no Optional fields

For any endpoints which are implemented by an ASPSP, the fields are either Mandatory or Conditional.

The Personal Data Protection Law or ‘PDPL’ is the data protection law of Bahrain that applies to any entity processing personal data wholly or partly by automated means – as well as the manual processing of personal data as part of an organized filing system.

Payment Initiation Service Provider or ‘PISP’ refers to a person licensed by the CBB to initiate payment or credit transfers for the customer from an account held with an ASPSP. The role of a PISP is restricted to providing the technology or other means in order to initiate a payment order and the handling of communication or electronic documents between the customer and the licensees should the terms of the offer include such services. PISPs must not receive or otherwise handle customer funds in the course of providing payment initiation services.

Strong Customer Authentication or ‘SCA’ is an authentication based on the use of three elements categorized as knowledge (something only the user knows [for example, a password]), possession (something only the user possesses [for example, particular cell phone and number]) and inherence (something the user is [or has, for example, a fingerprint or iris pattern]) that are independent, so the breach of one does not compromise the others, and is designed in such a way as to protect the confidentiality of the authentication data.

There may exist valid reasons to ignore a particular point in Bahrain OBF, but the full implications need to be understood before choosing a different course.

There may exist valid reasons when a particular point is acceptable or even useful, but the full implications need to be understood before implementing any point described with this label.

A number of resources in the specification include a section for Supplementary Data. This is intended to allow ASPSPs to accept or provide information in a request or response that is not catered for by other sections of the resource definition.
The Supplementary Data section is defined as an empty JSON object in the specification.
Wherever used, an ASPSP must define and document (on their developer portal) their own structure, usage and (mandatory/optional) requirements for Supplementary Data.
An ASPSP must not use Supplementary Data if an element already exists in the OBF standard that fulfills the requirement.

Third Party Providers or “TPP” are CBB licensees that use APIs developed to Standards to access customer’s accounts, in order to provide account information services and/or to initiate payments.
Third Party Providers are either Payment Initiation Service Providers (PISPs) or Account Information Service Providers (AISPs) or both Payment Initiation Service Providers (PISPs) and Account Information Service Providers (AISPs).

The Unified Modeling Language™ or ‘UML®’ is a standard visual modeling language intended to be used for:

• modeling business and similar processes,

• analysis, design, and implementation of software-based systems

UML is a common language for business analysts, software architects and developers used to describe, specify, design, and document existing or new business processes, structure and behavior of artifacts of software systems.

A natural or legal person (end-user) making use of a payment service as a payee, payer or both. A natural or legal person (end-user) making use of an account information service as part of a consent driven data sharing arrangement.

Ain’t Markup Language or ‘YAML’ is a human friendly, cross language, unicode based data serialization language designed around the common native structures of agile programming languages. It is broadly useful for programming needs ranging from configuration files to Internet messaging to object persistence to data auditing.