Statements
- CBB Admin
1. Version Control
Version | Date | Description of Changes |
Bahrain OBF v1.0.0 | 28th Oct 2020 | Initial Release |
2. Overview
The statements resource is used by an AISP to retrieve the
Statements information
Statement information for a StatementId in json and non-json(file) format
Transactions for a selected StatementId
for a specific account identified by AccountId or retrieve statement information for all accounts that the user/customer has consented to.
This resource description should be read in conjunction with a compatible Account Information Services API Profile.
3. Endpoints
S. No. | Resource | HTTP Operation | Endpoint | Mandatory | Scope | Grant Type | Idempotency Key | Parameters | Request Object | Response Object |
3.1 | statements | GET | GET /accounts/{AccountId}/statements | Conditional | accounts | Authorisation Code | No | Pagination Filtering |
| OBReadStatement |
3.2 | statements | GET | GET /accounts/{AccountId}/statements/{StatementId} | Conditional | accounts | Authorisation Code | No |
|
| OBReadStatement |
3.3 | statements | GET | GET /accounts/{AccountId}/statements/{StatementId}/file | Optional | accounts | Authorisation Code | No |
|
| File |
3.4 | transactions | GET | GET /accounts/{AccountId}/statements/{StatementId}/transactions | Conditional | accounts | Authorisation Code | No | Pagination |
| OBReadTransaction |
3.5 | statements | GET | GET /statements | Optional | accounts | Authorisation Code | No | Pagination Filtering |
| OBReadStatement |
3.1 GET /accounts/{AccountId}/statements
An ASPSP may provide this endpoint for AISPs to retrieve the statements information resource for the AccountId (which is retrieved in the call to GET /accounts).
3.2 GET /accounts/{AccountId}/statements/{StatementId}
An ASPSP may provide this endpoint for AISPs to retrieve the statement information resource for a specific statement in the AccountId (which is retrieved in the call to GET /accounts).
3.3 GET /accounts/{AccountId}/statements/{StatementId}/file
An ASPSP may provide this endpoint for AISPs to retrieve a non-json representation of a specific statement.
3.4 GET /accounts/{AccountId}/statements/{StatementId}/transactions
An ASPSP may provide this endpoint for AISPs to retrieve transactions that appear on the selected statement. The data model for the returned objects is documented in the transactions resource.
3.5 GET/statements
An ASPSP may provide this endpoint for AISPs to retrieve statement information for all accounts that the customer has consented to. This will retrieve the statement resources for all authorised accounts linked to the account-request.
4. Data Models
4.1 OBReadStatement
The OBReadStatement object will be used for the call to:
GET /statements
GET /accounts/{AccountId}/statements
GET /accounts/{AccountId}/statements/{StatementId}
The call to:
GET /accounts/{AccountId}/statements/{StatementId}/file will return unstructured data in binary (e.g., pdf, doc) or text (e.g., csv) formats. This will be specified in the Accept header by the AISP
The OBReadTransaction object (documented in the transactions resource) will be used for the call to:
GET /accounts/{AccountId}/statements/{StatementId}/transactions
4.1.1 Resource Definition
A resource that describes summary details for an account statement period. For a specific date range, an account (AccountId) may have no statements, or may have multiple statements. The /statements endpoint (if implemented by the ASPSP) must return all statements within the requested date range for all accounts selected during the authorisation of the account-request. If an AISP would like to access a specific statement (StatementId) to retrieve a formal statement download or transactions for a specific statement - the AISP must specify the account (the AccountId) via the URI request path i.e., via:
GET /accounts/{AccountId}/statements/{StatementId}/file - to download the statement
GET /accounts/{AccountId}/statements/{StatementId}/transactions - to return the transactions relating to a statement
4.1.2 UML Diagram
4.1.3 Notes
The statements resource must only be used for data that can be returned for a statement period
StartDateTime, EndDateTime and CreationDateTime are mandatory for the statements resource. If an ASPSP does not display these dates in an online channel, the ASPSP must populate these dates with sensible values. E.g., the StartDateTime could be the day after the previous statement EndDateTime, and the CreationDateTime could be the day after the EndDateTime
4.1.4 Filtering
Limited support for filtering is provided on the statements resource:
Name | Occurrence | Enhanced Definition | Class |
fromStatementDateTime | 0..1 | Specifies start date and time for filtering of the Statements on the Statement/StartDateTime field. If this is not populated, the start date will be open ended | DateTime |
toStatementDateTime | 0..1 | Specifies end date and time for filtering of the Statements on the Statement/StartDateTime field. If this is not populated, the end date will be open ended | DateTime |
The ASPSP must treat the following as valid input:
non-working days (e.g. a Friday/Saturday or a Bank holiday) or any other days on which no transactions are recorded
dates that fall outside the range for which transaction information is provided through APIs
dates that fall outside the range for which a consent authorisation is available
In the above situations, the ASPSP must return statements where the StartDateTime and EndDateTime are both between the fromStatementDateTime and toStatementDateTime parameters.
Filtering Examples
|
4.1.5 Permission Codes
The resource differs depending on the permissions (ReadStatementsBasic and ReadStatementsDetail) used to access resource (the OBReadStatement object). In the event the resource is accessed with both ReadStatementsBasic and ReadStatementsDetail, the most detailed level (ReadStatementsDetail) must be used.
These objects must not be returned without the ReadStatementsDetail permission:
OBReadStatement/Data/Statement/StatementAmount
Calls to GET /accounts/{AccountId}/statements/{StatementId}/file
If the ReadStatementsDetail is granted by the User/Customer:
OBReadStatement/Data/Statement/StatementAmount may be returned if applicable to the statement and ASPSP (0..n)
For the call to GET /accounts/{AccountId}/statements/{StatementId}/transactions:
The ReadTransactionsBasic or ReadTransactionsDetail (in addition to the appropriate ReadTransactionsCredits and/or ReadTransactionsDebits ) permission codes will be required. The ASPSP must apply the same access to GET /accounts/{AccountId}/statements/{StatementId}/transactions as GET /accounts/{AccountId}/transactions
If the ReadPAN permission is granted by the user/customer - the ASPSP may choose to populate the unmasked PAN - if the PAN is being populated in the response for these fields
OBReadTransaction/Data/Transaction/CreditorAgent/Identification
OBReadTransaction/Data/Transaction/DebtorAccount/Identification
OBReadTransaction /Data/Transaction/CardInstrument/Identification
4.1.6 Data Dictionary
Name | Occurrence | XPath | Enhanced Definition | Class/ Datatype | Codes | Pattern |
OBReadStatement |
| OBReadStatement |
| OBReadStatement |
|
|
Data | 1..1 | OBReadStatement/Data |
| OBReadStatement/Data |
|
|
Statement | 0..n | OBReadStatement/Data/Statement | Provides further details on a statement resource | OBReadStatement/Data/Statement |
|
|
AccountId | 1..1 | OBReadStatement/Data/Statement/AccountId | A unique and immutable identifier used to identify the account resource. This identifier has no meaning to the account owner | String |
|
|
StatementId | 0..1 | OBReadStatement/Data/Statement/StatementId | Unique identifier for the statement resource within a servicing institution. This identifier is both unique and immutable | String |
|
|
StatementReference | 0..1 | OBReadStatement/Data/Statement/StatementReference | Unique reference for the statement. This reference may be optionally populated if available | String |
|
|
Type | 1..1 | OBReadStatement/Data/Statement/Type | Statement type, in a coded form | String | Enum:
|
|
StartDateTime | 1..1 | OBReadStatement/Data/Statement/StartDateTime | Date and time at which the statement period starts | DateTime |
|
|
EndDateTime | 1..1 | OBReadStatement/Data/Statement/EndDateTime | Date and time at which the statement period ends | DateTime |
|
|
CreationDateTime | 1..1 | OBReadStatement/Data/Statement/CreationDateTime | Date and time at which the resource was created | DateTime |
|
|
StatementDescription | 0..n | OBReadStatement/Data/Statement/StatementDescription | Other descriptions that may be available for the statement resource | String |
|
|
StatementBenefit | 0..n | OBReadStatement/Data/Statement/StatementBenefit | Set of elements used to provide details of a benefit or reward amount for the statement resource | OBReadStatement/Data/Statement/StatementBenefit |
|
|
Type | 1..1 | OBReadStatement/Data/Statement/StatementBenefit/Type | Benefit type, in a coded form | String |
|
|
Amount | 1..1 | OBReadStatement/Data/Statement/StatementBenefit/Amount | Amount of money associated with the statement benefit type | OBReadStatement/Data/Statement/StatementBenefit/Amount |
|
|
Amount | 1..1 | OBReadStatement/Data/Statement/StatementBenefit/Amount/Amount | A number of monetary units specified in an active currency where the unit of currency is explicit and compliant with ISO 4217 | String |
| ^\d{1,13}$\|^\d{1,13}\.\d{1,5}$ |
Currency | 1..1 | OBReadStatement/Data/Statement/StatementBenefit/Amount/Currency | A code allocated to a currency by a Maintenance Agency under an international identification scheme, as described in the latest edition of the international standard ISO 4217 "Codes for the representation of currencies and funds" | String |
| ^[A-Z]{3,3}$ |
StatementFee | 0..n | OBReadStatement/Data/Statement/StatementFee | Set of elements used to provide details of a fee for the statement resource | OBReadStatement/Data/Statement/StatementFee |
|
|
Description | 0..1 | OBReadStatement/Data/Statement/StatementFee/Description | Description that may be available for the statement fee | String |
|
|
CreditDebitIndicator | 1..1 | OBReadStatement/Data/Statement/StatementFee/CreditDebitIndicator1 | Indicates whether the amount is a credit or a debit. Usage: A zero amount is considered to be a credit amount | String | Enum:
|
|
Type | 1..1 | OBReadStatement/Data/Statement/StatementFee/Type | Fee type, in a coded form | String | Enum: (Indicative)
|
|
Rate | 0..1 | OBReadStatement/Data/Statement/StatementFee/Rate | Rate charged for Statement Fee (where it is charged in terms of a rate rather than an amount) | Number |
|
|
RateType | 0..1 | OBReadStatement/Data/Statement/StatementFee/RateType | Description that may be available for the statement fee rate type | String | Enum:
|
|
Frequency | 0..1 | OBReadStatement/Data/Statement/StatementFee/Frequency | How frequently the fee is applied to the Account | String | Enum:
|
|
Amount | 1..1 | OBReadStatement/Data/Statement/StatementFee/Amount | Amount of money associated with the statement fee type | OBReadStatement/Data/Statement/StatementFee/Amount |
|
|
Amount | 1..1 | OBReadStatement/Data/Statement/StatementFee/Amount/Amount | A number of monetary units specified in an active currency where the unit of currency is explicit and compliant with ISO 4217 | String |
| ^\d{1,13}$\|^\d{1,13}\.\d{1,5}$ |
Currency | 1..1 | OBReadStatement/Data/Statement/StatementFee/Amount/Currency | A code allocated to a currency by a Maintenance Agency under an international identification scheme, as described in the latest edition of the international standard ISO 4217 "Codes for the representation of currencies and funds" | String |
| ^[A-Z]{3,3}$ |
StatementInterest | 0..n | OBReadStatement/Data/Statement/StatementInterest | Set of elements used to provide details of a generic interest amount related to the statement resource | OBReadStatement/Data/Statement/StatementInterest |
|
|
Description | 0..1 | OBReadStatement/Data/Statement/StatementInterest/Description | Description that may be available for the statement interest | String |
|
|
CreditDebitIndicator | 1..1 |
| Indicates whether the amount is a credit or a debit. Usage: A zero amount is considered to be a credit amount | String | Enum:
|
|
Type | 1..1 | OBReadStatement/Data/Statement/StatementInterest/Type | Interest amount type, in a coded form | String | Enum: (Indicative)
|
|
Rate | 0..1 | OBReadStatement/Data/Statement/StatementInterest/Rate | Rate for Statement Interest (where it is applicable in terms of a rate rather than an amount) | Number |
|
|
RateType | 0..1 | OBReadStatement/Data/Statement/StatementInterest/RateType | Description that may be available for the statement Interest rate type | String | Enum:
|
|
Frequency | 0..1 | OBReadStatement/Data/Statement/StatementInterest/Frequency | How frequently the Interest Rate is applied to the Account | String | Enum:
|
|
Amount | 1..1 | OBReadStatement/Data/Statement/StatementInterest/Amount | Amount of money associated with the statement interest amount type | OBReadStatement/Data/Statement/StatementInterest/Amount |
|
|
Amount | 1..1 | OBReadStatement/Data/Statement/StatementInterest/Amount/Amount | A number of monetary units specified in an active currency where the unit of currency is explicit and compliant with ISO 4217 | String |
| ^\d{1,13}$\|^\d{1,13}\.\d{1,5}$ |
Currency | 1..1 | OBReadStatement/Data/Statement/StatementInterest/Amount/Currency | A code allocated to a currency by a Maintenance Agency under an international identification scheme, as described in the latest edition of the international standard ISO 4217 "Codes for the representation of currencies and funds" | String |
| ^[A-Z]{3,3}$ |
StatementAmount | 0..n | OBReadStatement/Data/Statement/StatementAmount | Set of elements used to provide details of a generic amount for the statement resource | OBReadStatement/Data/Statement/StatementAmount |
|
|
CreditDebitIndicator | 1..1 | OBReadStatement/Data/Statement/StatementAmount/CreditDebitIndicator | Indicates whether the amount is a credit or a debit. Usage: A zero amount is considered to be a credit amount | String | Enum
|
|
Type | 1..1 | OBReadStatement/Data/Statement/StatementAmount/Type | Amount type, in a coded form | String | Enum: (Indicative)
|
|
Amount | 1..1 | OBReadStatement/Data/Statement/StatementAmount/Amount | Amount of money associated with the amount type | OBReadStatement/Data/Statement/StatementAmount/Amount |
|
|
Amount | 1..1 | OBReadStatement/Data/Statement/StatementAmount/Amount/Amount | A number of monetary units specified in an active currency where the unit of currency is explicit and compliant with ISO 4217 | String |
| ^\d{1,13}$\|^\d{1,13}\.\d{1,5}$ |
Currency | 1..1 | OBReadStatement/Data/Statement/StatementAmount/Amount/Currency | A code allocated to currency by a Maintenance Agency under an international identification scheme, as described in the latest edition of the international standard ISO 4217 "Codes for the representation of currencies and funds" | String |
| ^[A-Z]{3,3}$ |
StatementDateTime | 0..n | OBReadStatement/Data/Statement/StatementDateTime | Set of elements used to provide details of a generic date time for the statement resource | OBReadStatement/Data/Statement/StatementDateTime |
|
|
DateTime | 1..1 | OBReadStatement/Data/Statement/StatementDateTime/DateTim | Date and time associated with the date time type | DateTime |
|
|
Type | 1..1 | OBReadStatement/Data/Statement/StatementDateTime/Type
| Date time type, in a coded form | String | Enum: (Indicative)
|
|
StatementRate | 0..n | OBReadStatement/Data/Statement/StatementRate |
| OBReadStatement/Data/Statement/StatementRate |
|
|
Rate | 1..1 | OBReadStatement/Data/Statement/StatementRate/Rate
| Rate associated with the statement rate type | String |
| ^(-?\d{1,3}){1}(.\d{1,4}){0,1}$ |
Type | 1..1 | OBReadStatement/Data/Statement/StatementRate/Type | Statement rate type, in a coded form | String | Enum: (Indicative)
|
|
StatementValue | 0..n | OBReadStatement/Data/Statement/StatementValue | Set of elements used to provide details of a generic number value related to the statement resource | OBReadStatement/Data/Statement/StatementValue |
|
|
Value | 1..1 | OBReadStatement/Data/Statement/StatementValue/Value | Value associated with the statement value type | String |
|
|
Type | 1..1 | OBReadStatement/Data/Statement/StatementValue/Type | Statement value type, in a coded form | String | Enum: (Indicative)
|
|
5. Usage Example
5.1 Bulk
5.1.1 Get Statements Request
|
5.1.2 Get Statements Response
|
|
5.2 Specific Account
5.2.1 Get Account Statements Request
|
5.2.2 Get Account Statements Response
|
|
CENTRAL BANK OF BAHRAIN © 2020