4. Data Models (Draft Version 1.0)

4. Data Models (Draft Version 1.0) | 4.1 Enumerations

4. Data Models (Draft Version 1.0) | 4.2 Common Payload Structure

https://kuwaitobframework.atlassian.net/wiki/spaces/KOBF/pages/5603467/4.+Data+Models+Draft+Version+1.0#4.3-Data

4. Data Models (Draft Version 1.0) | 4.4 Response Structure

4. Data Models (Draft Version 1.0) | 4.5 Error Response Structure

https://kuwaitobframework.atlassian.net/wiki/spaces/KOBF/pages/5603467/4.+Data+Models+Draft+Version+1.0#4.6-Links

4. Data Models (Draft Version 1.0) | 4.7 Meta

https://kuwaitobframework.atlassian.net/wiki/spaces/KOBF/pages/5603467/4.+Data+Models+Draft+Version+1.0#4.8-FirstAvailableDateTime-and-LastAvailableDateTime

https://kuwaitobframework.atlassian.net/wiki/spaces/KOBF/pages/5603467/4.+Data+Models+Draft+Version+1.0#4.9-Data-Standards

4.1 Enumerations

API Specifications include various fields of Enumerated data types, where either the values are fixed to a defined set of alternatives (i.e., Static Enumerations), or flexible with an initial defined set of alternatives, and ASPSPs can use/extend these alternatives (i.e., Namespaced Enumerations). While Static Enumerations are listed on each API Specification page, Namespaced Enumerations are captured on the Namespaced Enumerations page.

4.2 Common Payload Structure

The payload structure defines the contents of a data-packet, including the field-naming convention, the field path relative to the data root, and the field definition. The Bank and the OBSP could consider using the JSON object format for the request and response payload. The Bank and the OBSP could consider maintaining a consistent data format when defining the payload structure of the Open Banking APIs.

• Request Payload: The Bank and the OBSP could consider using the JSON object format for the request payload through the POST, PATCH and PUT methods of the HTTP request. The JSON object could contain the primary input parameters required for each endpoint and meta information (e.g., pagination, authorization data, etc.)

• Response Payload: The Bank and the OBSP could consider using the JSON object format for the response payload through the GET, POST and PUT methods of the HTTP response. The JSON object could contain the response data object of specific endpoints (e.g., account balance), links object (e.g., self-URI) and meta information (e.g., additional information specific to data error)

• Error Response Payload: The error response payload is used to classify errors encountered in RESTful API services with error messages from the Open Banking API response. The Bank and the OBSP could consider using the JSON object format for the error response payload through the GET, POST, PATCH and PUT methods of the HTTP response. The JSON object could contain the response data object of specific endpoints (e.g., errorCode, errorMessage, URL)

This section gives an overview of the top-level structure for the API payloads for the Open Banking Read/Write APIs. The data contained within the Data section is documented with each individual API endpoint.

4.3 Data

The Data section contains the request data for the specific API request. The structure of this element differs for each API endpoint.

4.4 Response Structure

The top-level response structure for Open Banking Read/Write APIs:

In line with the principle of RESTful APIs, the full resource must be replayed as part of the response.

Two additional top-level sections are included in the response for:

• Links

• Meta

4.5 Error Response Structure

The error response structure for Open Banking Read/Write APIs:

4.6 Links

The Links section is optional and will always contain absolute URIs to related resources,

The "Self" member is mandatory.

For example:

Where an API provides a paginated response, the Links element may also contain the members First, Prev, Next and Last as described in the section Basics / Pagination.

For example:

4.7 Meta

The Meta section is optional and may be empty.  An optional member is "TotalPages" which is specified as an integer (int32) and shows how many pages of results (for pagination) are available.

For example:

4.8 FirstAvailableDateTime and LastAvailableDateTime

The FirstAvailableDateTime represents the earliest point in time for which data is accessible through the Open Banking API. It is the starting timestamp from which historical account data or transaction information can be retrieved. Any data or transactions that have occurred before this date cannot be retrieved through the API.

The LastAvailableDateTime represents the most recent or latest point in time for which data is accessible through the Open Banking API. It is the ending timestamp that outlines the range of data available for retrieval. Any data or transactions that occurred after this date would not be accessible through the API.

4.9 Data Standards

The data standards element sets out the API specifications to enable the customer data access process using the Kuwait Open Banking Technical API specifications to retrieve account details (accounts, balances, beneficiaries, direct debits, scheduled payments, standing orders, and transactions), process payments, notifications and generate leads. An example of Accounts API with all the elements encompassing data standards have been detailed below for ease of reference:

Accounts: API Specifications - This resource description should be read in conjunction with a compatible Account and Transaction API Profile defined as part of the Account Information Use Cases Technical API Specifications document.

Overview: The accounts resource is used by an AISP to retrieve full list of accounts and account information that the user/customer has authorized to access.

Endpoints: Endpoints for the resource - and available methods.

A. GET/accounts

The first step for an AISP after an account-request is authorised - is to call the GET /accounts endpoint.

The AISP will be given the full list of accounts (the AccountId(s)) that the user/customer has authorised the AISP to access. The AccountId(s) returned may then be used to retrieve other resources for a specific AccountId. The selection of the authorised accounts happens only at the ASPSP’s interface.

B. GET /accounts/{AccountId}

An AISP may retrieve the account information resources for the AccountId (which is retrieved in the call to GET /accounts).

Data Models

The OBReadAccount object will be used for the call to:

• GET /accounts/{AccountId}

• GET /accounts

Resource Definition: This resource represents the account to which credit and debit entries are made. Each account resource will have a unique and immutable AccountId.

UML Diagram:

Open

Notes

• The Account and Servicer structure has been designed to:

  • Reflect the DebtorAccount, DebtorAgent, CreditorAccount and CreditorAgent structures in the PISP use case.

  • Defining a SchemeName for the Account and Servicer blocks can help accommodate multiple types of accounts.

• For common Domestic Kuwait identification schemes:

  • Account/Account

    • Where "KW.OBF.IBAN" is specified as the SchemeName, the Identification field must be populated with the full IBAN

  • Account/Servicer

    • Where "KW.OBF.BICFI" is populated as the SchemeName, the Identification field must be populated with the BIC

Permission Codes

The resource differs depending on the permissions (ReadAccountsBasic and ReadAccountsDetail) used to access the resource. In the event that the resource is accessed with both ReadAccountsBasic and ReadAccountsDetail, the most detailed level (ReadAccountsDetail) must be used.

• These objects must not be returned without the ReadAccountsDetail permission:

  • OBReadAccount/Data/Account/Account

  • OBReadAccount/Data/Account/Servicer

• If the ReadAccountsDetail is granted by the user/customer:

  • OBReadAccount/Data/Account/Account must be returned (1..n)

  • OBReadAccount/Data/Account/Servicer may be returned if applicable to the account and ASPSP (0..1)

Data Dictionary

Usage Examples

A. Bulk Accounts

The call to GET /accounts is the first step after an account-request is authorised. This will allow the AISP to discover which accounts (and AccountId values) are associated with the authorisation of consent.

I Get Accounts Request

II Get Accounts Response

B. Specific Account

An AISP may also retrieve the account resource details specifically for AccountId 00347895. The ReadAccountsDetail permission has been granted.

I Get Accounts Request

II Get Accounts Response