Versions Compared

Version Old Version 15 New Version 16
Changes made by

CBB Admin

CBB Admin

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

General

Expand
titleWhat is Bahrain Open Banking Framework (Bahrain OBF)?

Bahrain OBF is a holistic Open Banking Framework that will support the evolution of innovation while continuously addressing issues to protect, maintain and bolster the safety and robustness of Bahrain’s financial system.
Bahrain OBF has been developed considering the relevant use cases (payments as well as account information sharing) that have several business opportunities for the ASPSPs and third party providers to cater to the customer’s unique needs. Bahrain OBF covers the associated technical and non-technical elements namely customer experience guidelines, user/customer journeys, API specifications, operational guidelines, and security standards and guidelines.

...

Expand
titleWhat access rights do AISPs/PISPs have?

Under Bahrain OBF, third party providers have both read and write access depending on the nature of service they provide.

  • Read access allows the data recipient to obtain copies of customers’ financial data and use it for such activities as data aggregation (for example – AIS - account aggregations services).

  • Write access allows data recipient to initiate payments on behalf of the user/customer (for example – PIS - payment initiation services).

Security and Privacy

Expand
titleIs Bahrain Open Banking safe?

Safety and Security of user/customer data has always been the primary focus area for Bahrain Open Banking:

  • The user/customer is always in control: The user/customer can choose when, for what purpose and for how long, to give access to his/her data.

  • Accreditation: Only third party providers regulated by the CBB can provide Open Banking services in Bahrain.

  • Existing Bahrain Regulations: All the existing Bahrain regulations for data security, storage, dispute etc. will continue to be applicable to Open Banking services as well.

  • Security: All Open Banking participants should comply with the Security Standards and Guidelines as part of the Bahrain OBF.

The principles of control, regulation and security combine to create a trusted Open Banking environment for the user/customer.

...

Expand
titleHow can I complain about a regulated AISP/PISP or an ASPSP?

The first step is to discuss your complaint directly with AISP/PISP or an ASPSP. If you believe you are not satisfied with their response, you can contact CBB by submitting the Complaint Form available on https://www.cbb.gov.bh/complaint-form/

Accreditation

Expand
titleWhy should anyone apply for accreditation?

Only accredited third party providers and ASPSPs are allowed to offer Open Banking services in Bahrain.
Anyone who wishes to receive user/customer data to offer products or services to users/customers must be accredited with the CBB.
To become accredited, a person must apply to the CBB. The CBB will review the application and duly advise the applicant in writing when it has:

  • Granted the application without conditions;

  • Granted the application subject to conditions specified by the CBB; or

  • Refused the application, stating the grounds on which the application has been refused and the process for appealing against that decision

...

Expand
titleWhat happens when an accredited entity does not comply with the Open Banking regulations?

The CBB may amend or revoke a license in any of the following cases:

  • If the licensee fails to satisfy any of the license conditions;

  • If the licensee violates the terms of the CBB Rulebook;

  • If the licensee fails to start business within six months from the date of the license;

  • If the licensee ceases to carry out the licensed activity in the Kingdom;

  • The legitimate interests of the customers or creditors of a licensee required such amendment or cancellation

API Specification

Expand
titleWhat is Idempotency?

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

Expand
titleWhat is Message Signing?

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

Expand
titleWhat is Message Encryption?

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.

Expand
titleWhat is the use of Unique Identifiers (Id Fields)?

A REST resource should have a unique identifier (e.g. a primary key) that may be used to identify the resource. These unique identifiers are used to construct URLs to identify and address specific resources.

However, considering that some of the resources described in these specifications do not have a primary key in the system of record, the Id field will be optional for some resources.

An ASPSP that chooses to populate optional Id fields must ensure that the values are unique and immutable.

Expand
titleDefinition of Mandatory, Conditional and Optional.

The functionality, endpoints and fields within each resource are categorised as 'Mandatory', 'Conditional' or 'Optional'.

Mandatory

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:

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

Conditional

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.

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

Optional

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.

Expand
titleWhat is character encoding?

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.

All date-time fields in responses must include the timezone. For Example:

Expand
titleWhat are the Date Formats used in the API?

2020-04-05T10:43:07+03:00

2020-05-03T14:43:41Z

The API allows the AISP to ask an ASPSP to create a new account-access-consent resource.

All dates in the query string are represented in ISO-8601 date-time format and must not include the timezone. For example:

2020-04-05T10:43:07

2020-04-05

All dates in the HTTP headers are represented as RFC 7231 Full Dates. An example is below:

Tue, 10 Mar 2020 19:43:31 GMT+03:00

All dates in the JWT claims are expressed as a JSON number, representing the number of seconds from 1970-01-01T0:0:0Z as measured in GMT until the date/time.

//Wed, 12 Feb 2020 14:45:00 GMT+03:00

1581507900

Expand
titleWhat will be the structure of resource URI path?

The path of the URI must follow the structure below

[participant-path-prefix]/open-banking/
the use of Unique Identifiers (Id Fields)?

A REST resource should have a unique identifier (e.g. a primary key) that may be used to identify the resource. These unique identifiers are used to construct URLs to identify and address specific resources.

However, considering that some of the resources described in these specifications do not have a primary key in the system of record, the Id field will be optional for some resources.

An ASPSP that chooses to populate optional Id fields must ensure that the values are unique and immutable.

Expand
titleWhat are the Date Formats used in the API?

All date-time fields in responses must include the timezone. For Example:

2020-04-05T10:43:07+03:00

2020-05-03T14:43:41Z

The API allows the AISP to ask an ASPSP to create a new account-access-consent resource.

All dates in the query string are represented in ISO-8601 date-time format and must not include the timezone. For example:

2020-04-05T10:43:07

2020-04-05

All dates in the HTTP headers are represented as RFC 7231 Full Dates. An example is below:

Tue, 10 Mar 2020 19:43:31 GMT+03:00

All dates in the JWT claims are expressed as a JSON number, representing the number of seconds from 1970-01-01T0:0:0Z as measured in GMT until the date/time.

//Wed, 12 Feb 2020 14:45:00 GMT+03:00

1581507900

Expand
titleWhat will be the structure of resource URI path?

The path of the URI must follow the structure below

  • [participant-path-prefix]/open-banking/[version]/[resource-group]/[resource]/[resource-id]/[sub-resource]

This consists of the following elements:

  • [participant-path-prefix]
    An optional ASPSP specific path prefix.

  • open-banking
    The constant string "open-banking".

  • [version]
    The version of the APIs expressed as /v[major-version].[minor-version]/.

  • [resource-group]
    The resource-group identifies the group of endpoints, to access the API (as "aisp", "pisp").

  • [resource]/[resource-id]
    Details the resource.

  • [sub-resource]
    Details the sub-resource.

An ASPSP must use the same participant-path-prefix and host name for all its resources.

Examples:

  • https://xyz.com/apis/open-banking/v1.1/pisp/domestic-payments

  • https://xyz.com/apis/open-banking/v1.1/aisp/account-access-consents

  • https://xyz.com/apis/open-banking/v3.1/aisp/accounts

  • https://xyz.com/apis/open-banking/v3.1/aisp/accounts/1234

  • https://xyz.com/apis/open-banking/v3.1/aisp/accounts/1234/transactions

Expand
titleWhat are Request Headers?
Expand
titleWhat is Supplementary Data?

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 fulfils the requirement

Header Value

Notes

POST Requests

GET Requests

DELETE Requests

PUT

Requests

PATCH
Requests

x-fapi-auth-date

The time when the User/Customer last logged in with the AISP/PISP. e.g., x-fapi-auth-date: Mon, 11 May 2020 19:43:31 GMT+03:00

Optional

Optional

Optional

Do not use

Optional

x-fapi-customer-ip-address

The User’s/Customer’s IP address if the User/Customer is currently logged in with the AISP/PISP.

Optional

Optional

Optional

Do not use

Optional

x-fapi-interaction-id

An RFC4122 UID used as a correlation Id.
If provided, the ASPSP must "play back" this value in the x-fapi-interaction-id response header

Optional

Optional

Optional

Optional

Optional

Authorization

Standard HTTP Header; Allows Credentials to be provided to the Authorisation / Resource Server depending on the type of resource being requested. For OAuth 2.0 / OIDC, this comprises of either the Basic / Bearer Authentication Schemes.

Mandatory

Mandatory

Mandatory

Mandatory

Mandatory

Content-Type

Standard HTTP Header; Represents the format of the payload being provided in the request.
This must be set to application/json, except for the endpoints that support Content-Type other than application/json (e.g POST /file-payment-consents/{ConsentId}/file), the ASPSP must specify the available options on their developer portals.
This must be set to application/jose+jwe for encrypted requests.
The AISP/PISP may provide additional information (e.g. a 'q' value and charset).

Mandatory

Do not use

Do not use

Mandatory

Mandatory

Accept

Standard HTTP Header; Determine the Content-Type that is required from the Server.
If the AISP/PISP expects an unencrypted response, it must indicate that the only a JSON response is accepted (e.g by setting the value to application/json) as a content header for all endpoints that respond with JSON.
If the AISP/PISP expects an encrypted response, it must indicate that the only a JWT response is accepted (e.g by setting the value to application/jose+jwe) as a content header for all endpoints that respond with JSON.
For endpoints that do not respond with JSON (e.g GET ../statements/{StatementIdthis value in the x-fapi-interaction-id response header

Optional

Optional

Optional

Optional

Optional

Authorization

Standard HTTP Header; Allows Credentials to be provided to the Authorisation / Resource Server depending on the type of resource being requested. For OAuth 2.0 / OIDC, this comprises of either the Basic / Bearer Authentication Schemes.

Mandatory

Mandatory

Mandatory

Mandatory

Mandatory

Content-Type

Standard HTTP Header; Represents the format of the payload being provided in the request.
This must be set to application/json, except for the endpoints that support Content-Type other than application/json (e.g POST /file-payment-consents/{ConsentId}/file), the ASPSP must specify the available options on their developer portals.
If set to an unacceptable value the ASPSP must respond with a 406 (Not Acceptable).
If not specified, the default is application/json.

Optional

OptionalThis must be set to application/jose+jwe for encrypted requests.
The AISP/PISP may provide additional information (e.g. a 'q' value and charset).

Mandatory

Do not use

Do not use

OptionalMandatory

Optional

x-idempotency-key

Custom HTTP Header; Unique request identifier to support idempotency.
Mandatory for POST requests to idempotent resource end-points.
Must not be specified for other requests.

Optional

Do not use

Do not use

Do not use

Do not use

x-jws-signature

Header containing a detached JWS signature of the body of the payload.
Refer to resource specific documentation on when this header must be specified

API specific

API specific

API specific

Mandatory

API specific

x-customer-user-agent

The header indicates the user-agent that the User/Customer is using.
The AISP/PISP may populate this field with the user-agent indicated by the User/Customer.
If the User/Customer is using a AISP/PISP mobile app, the AISP/PISP must ensure that the user-agent string is different from browser based user-agent strings.

Optional

Optional

Optional

Optional

Optional

Expand
titleWhat are Response Headers?

Header Value

Notes

Mandatory?

Content-Type

Standard HTTP Header; Represents the format of the payload returned in the response.
The ASPSP must return Content-Type: application/json as a content header for all unencrypted endpoints, except the GET ../statements/{StatementId}/file and ../file-payment-consents/{ConsentId}/file endpoints, where it is up to the ASPSP to specify available options.
The ASPSP must return Content-type: application/jwe for all encrypted end-points

Mandatory

x-jws-signature

Header containing a detached JWS signature of the body of the payload.
Refer to resource specific documentation on when this header must be returned. Where a signed response is indicated in the documentation this header should be returned for error responses where a response body is returned.

API specific

x-fapi-interaction-id

An RFC4122 UID used as a correlation Id.
The ASPSP must set the response header x-fapi-interaction-id to the value received from the corresponding fapi client request header or to a RFC4122 UUID value if the request header was not provided to track the interaction. The header must be returned for both successful and error responses.

Mandatory

Retry-After

Header indicating the time (in seconds) that the AISP/PISP should wait before retrying an operation.
The ASPSP should include this header along with responses with the HTTP status code of 429 (Too Many Requests).

Optional

Expand
titleDoes GET operation supports filtering?

An ASPSP must provide limited support of filtering on GET operations that return multiple records.

The filter parameters, are always specific to particular field(s) of the resource, and follow the rules/formats defined under the resource's data dictionary.

In case of DateTime type filter parameters, values must be specified in ISO8601 format. If the DateTime contains a timezone, the ASPSP may ignore the timezone component.

The filter values will be assumed to refer to the same timezone as the timezone in which the resource is maintained.

Expand
titleDoes GET operations supports pagination?

An ASPSP MAY provide a paginated response for GET operations that return multiple records.

In such a situation, the ASPSP MUST:

  • If a subsequent page of resource records exists, the ASPSP must provide a link to the next page of resources in the Links.Next field of the response. The absence of a next link would indicate that the current page is the last page of results.

  • If a previous page of resource records exists, the ASPSP must provide a link to the previous page of resources in the Links.Prev field of the response. The absence of a prev link would indicate that the current page is the first page of results.

For a paginated responses, the ASPSP may ensure that the number of records on a page are within reasonable limits, the minimum and maximum level for number of records may be decided based on agreement between ASPSP and AISP/PISP.

Additionally, the ASPSP MAY provide:

  • A link to the first page of results in the Links.First field.

  • A link to the last page of results in the Links.Last field.

  • The total number of pages in the Meta.TotalPages field.

As with all other responses, the ASPSP MUST include a "self" link to the resource in the Links.Self field as described in the Links sections.

This standard does not specify how the pagination parameters are passed by the ASPSP and each ASPSP may employ their own mechanisms to paginate the response.

If the original request from the AISP included filter parameters, the paginated response must return only results that match the filter.

ASPSPs are not expected to implement pagination with transaction isolation. The underlying data-set may change between two subsequent requests. This may result in situations where the same transaction is returned on more than one page.

Expand
titleWhat are the Archiving policies?

ASPSPs should define archiving policies based on existing Bahrain regulations and their internal legal requirements.

Mandatory

Accept

Standard HTTP Header; Determine the Content-Type that is required from the Server.
If the AISP/PISP expects an unencrypted response, it must indicate that the only a JSON response is accepted (e.g by setting the value to application/json) as a content header for all endpoints that respond with JSON.
If the AISP/PISP expects an encrypted response, it must indicate that the only a JWT response is accepted (e.g by setting the value to application/jose+jwe) as a content header for all endpoints that respond with JSON.
For endpoints that do not respond with JSON (e.g GET ../statements/{StatementId}/file), the ASPSP must specify the available options on their developer portals.
If set to an unacceptable value the ASPSP must respond with a 406 (Not Acceptable).
If not specified, the default is application/json.

Optional

Optional

Do not use

Optional

Optional

x-idempotency-key

Custom HTTP Header; Unique request identifier to support idempotency.
Mandatory for POST requests to idempotent resource end-points.
Must not be specified for other requests.

Optional

Do not use

Do not use

Do not use

Do not use

x-jws-signature

Header containing a detached JWS signature of the body of the payload.
Refer to resource specific documentation on when this header must be specified

API specific

API specific

API specific

Mandatory

API specific

x-customer-user-agent

The header indicates the user-agent that the User/Customer is using.
The AISP/PISP may populate this field with the user-agent indicated by the User/Customer.
If the User/Customer is using a AISP/PISP mobile app, the AISP/PISP must ensure that the user-agent string is different from browser based user-agent strings.

Optional

Optional

Optional

Optional

Optional

Expand
titleWhat are Response Headers?

Header Value

Notes

Mandatory?

Content-Type

Standard HTTP Header; Represents the format of the payload returned in the response.
The ASPSP must return Content-Type: application/json as a content header for all unencrypted endpoints, except the GET ../statements/{StatementId}/file and ../file-payment-consents/{ConsentId}/file endpoints, where it is up to the ASPSP to specify available options.
The ASPSP must return Content-type: application/jwe for all encrypted end-points

Mandatory

x-jws-signature

Header containing a detached JWS signature of the body of the payload.
Refer to resource specific documentation on when this header must be returned. Where a signed response is indicated in the documentation this header should be returned for error responses where a response body is returned.

API specific

x-fapi-interaction-id

An RFC4122 UID used as a correlation Id.
The ASPSP must set the response header x-fapi-interaction-id to the value received from the corresponding fapi client request header or to a RFC4122 UUID value if the request header was not provided to track the interaction. The header must be returned for both successful and error responses.

Mandatory

Retry-After

Header indicating the time (in seconds) that the AISP/PISP should wait before retrying an operation.
The ASPSP should include this header along with responses with the HTTP status code of 429 (Too Many Requests).

Optional

Expand
titleDoes GET operation supports filtering?

An ASPSP must provide limited support of filtering on GET operations that return multiple records.

The filter parameters, are always specific to particular field(s) of the resource, and follow the rules/formats defined under the resource's data dictionary.

In case of DateTime type filter parameters, values must be specified in ISO8601 format. If the DateTime contains a timezone, the ASPSP may ignore the timezone component.

The filter values will be assumed to refer to the same timezone as the timezone in which the resource is maintained.

Expand
titleDoes GET operations supports pagination?

An ASPSP MAY provide a paginated response for GET operations that return multiple records.

In such a situation, the ASPSP MUST:

  • If a subsequent page of resource records exists, the ASPSP must provide a link to the next page of resources in the Links.Next field of the response. The absence of a next link would indicate that the current page is the last page of results.

  • If a previous page of resource records exists, the ASPSP must provide a link to the previous page of resources in the Links.Prev field of the response. The absence of a prev link would indicate that the current page is the first page of results.

For a paginated responses, the ASPSP may ensure that the number of records on a page are within reasonable limits, the minimum and maximum level for number of records may be decided based on agreement between ASPSP and AISP/PISP.

Additionally, the ASPSP MAY provide:

  • A link to the first page of results in the Links.First field.

  • A link to the last page of results in the Links.Last field.

  • The total number of pages in the Meta.TotalPages field.

As with all other responses, the ASPSP MUST include a "self" link to the resource in the Links.Self field as described in the Links sections.

This standard does not specify how the pagination parameters are passed by the ASPSP and each ASPSP may employ their own mechanisms to paginate the response.

If the original request from the AISP included filter parameters, the paginated response must return only results that match the filter.

ASPSPs are not expected to implement pagination with transaction isolation. The underlying data-set may change between two subsequent requests. This may result in situations where the same transaction is returned on more than one page.

Expand
titleWhat will be the error flow if the access token is missing or expired?

This flow assumes that the following steps have been completed successfully:

  • Step 1: Request Account Information

  • Step 2: Setup Account Request

  • Step 3: Authorise Consent

The AISP attempts to provide an expired or missing access token to the ASPSP in an attempt to Request Data

...

Expand
titleWhat will be the error flow if consent authorisation has failed?

This flow assumes that the following Steps have been completed successfully:

  • Step 1: Request Account Information

  • Step 2: Setup Account Request

  • Step 3: Authorise Consent Flow fails to succeed due to the USER/CUSTOMER providing invalid credentials to the ASPSP, resulting in no Authorization Code being generated.

Further Information

Expand
titleHow can I stay informed on new Open Banking updates or news?

The confluence pages will be updated on a periodic basis to keep the Open Banking participants informed on new developments.

...