| Table of Contents |
|---|
1. Overview
The Account Access Consents API is used by an AISP to request an ASPSP to create a new account-access-consent resource, retrieve the status of account-access-consent resource and delete the account-access-consent resource.
This resource description should be read in conjunction with a compatible Account Information Services API Profile.
2. Endpoints
S.No. | Resource | HTTP Operation | Endpoint | Mandatory | Scope | Grant Type | Message Signing | Idempotency Key | Request Object | Response Object |
2.1 | account-access-consents | POST | POST /account-access-consents | Mandatory | accounts | Client Credentials | Signed Request Signed Response | No | OBAccountAccessConsentRequest | OBAccountAccessConsentResponse |
2.2 | account-access-consents | GET | GET /account-access-consents/{ConsentId} | Mandatory | accounts | Client Credentials | Signed Response | No | NA | OBAccountAccessConsentResponse |
2.3 | account-access-consents | DELETE | DELETE /account-access-consents/{ConsentId} | Mandatory | accounts | Client Credentials | Signed Response | No | NA | NA |
2.1. POST /account-access-consents
The API allows the AISP to ask an ASPSP to create a new account-access-consent resource.
This API effectively allows the AISP to send a copy of the consent to the ASPSP to authorise access to account and transaction information.
An AISP is not able to pre-select a set of accounts for account-access-consent authorisation. This is because the behaviour of the pre-selected accounts, after authorisation, is not clear from a Legal perspective.
An ASPSP creates the account-access-consent resource and responds with a unique ConsentId to refer to the resource.
Prior to calling the API, the AISP must have an access token issued by the ASPSP using a client credentials grant.
2.1.1 Account Access Consent Status
The PSU must authenticate with the ASPSP and authorise the account-access-consent for the account-access-consent to be successfully setup. The account-access-consent resource that is created successfully must have the following Status code-list enumeration:
S.No. | Status | Status Description |
1 | AwaitingAuthorisation | The account access consent is awaiting authorisation. |
After authorisation has taken place the account-access-consent resource may have these following statuses:
S.No. | Status | Status Description |
1 | Rejected | The account access consent has been rejected. |
2 | Authorised | The account access consent has been successfully authorised. |
3 | Revoked | The account access consent has been revoked via the ASPSP interface. |
2.1.2 Status Flow
...
2.2. GET /account-access-consents/ {ConsentId}
An AISP may optionally retrieve an account-access-consent resource that they have created to check its status.
Prior to calling the API, the AISP must have an access token issued by the ASPSP using a client credentials grant.
The usage of this API endpoint will be subject to an ASPSP's fair usage policies.
2.2.1 Account Access Consent Status
Once the PSU authorises the account-access-consent resource - the Status of the account-access-consent resource will be updated with "Authorised".
The available Status code-list enumerations for the account-access-consent resource are.
S.No. | Status | Status Description |
1 | Rejected | The account access consent has been rejected. |
2 | AwaitingAuthorisation | The account access consent is awaiting authorisation |
3 | Authorised | The account access consent has been successfully authorised. |
4 | Revoked | The account access consent has been revoked via the ASPSP interface. |
2.3. DELETE /account-access-consents/{ConsentId}
If the PSU revokes consent to data access with the AISP, the AISP must delete the account-access-consent resource with the ASPSP as soon as is practically possible.
This is done by making a call to DELETE the account-access-consent resource.
Prior to calling the API, the AISP must have an access token issued by the ASPSP using a client credentials grant.
TPP should also clear the Account Access Consent resources, from ASPSP's system, which are:
Expired, i.e. ExpirationDateTime is lapsed, or ExpirationDateTime is not lapsed, but PSU doesn't want to refresh/re-authenticate it, and
Consent Resource may never be referenced by the PSU in AISP or ASPSP domain.
3. Data Models
3.1. Account Access Consents - Request
The OBAccountAccessConsentRequest object will be used for the call to:
POST /account-access-consents
3.1.1 UML Diagram
...
3.1.2 Notes
The fields in the OBAccountAccessConsentRequest object are described in the Consent Elements section.
3.1.3 Data Dictionary
...
Name
...
Occurrence
...
XPath
...
Definition
...
Class/ Datatype
...
Codes
...
OBAccountAccessConsentRequest
...
...
OBAccountAccessConsentRequest
...
...
| Table of Contents | ||||
|---|---|---|---|---|
|
1. Version Control
Version | Date | Description of Changes |
Bahrain OBF v1.0.0 | 25th Aug 2020 | Initial Release |
2. Overview
The Account Access Consents API is used by an AISP to request an ASPSP to create a new account-access-consents resource, retrieve the status of account-access-consents resource and patch the account-access-consents resource.
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 | account-access-consents | POST | POST /account-access-consents | Mandatory | accounts | Client Credentials | No | OBAccountAccessConsentRequest | OBAccountAccessConsentResponse | |
3.2 | account-access-consents | GET | GET /account-access-consents/{ConsentId} | Mandatory | accounts | Client Credentials | No | NA | OBAccountAccessConsentResponse | |
3.3 | account-access-consents | PATCH | PATCH /account-access-consents/{ConsentId} | Mandatory | accounts | Client Credentials | No | OBPatchAccountAccessConsentRequest | OBAccountAccessConsentResponse |
3.1 POST /account-access-consents
The API allows the AISP to ask an ASPSP to create a new account-access-consents resource.
This API effectively allows the AISP to send a copy of the consent to the ASPSP to authorise access to account and transaction information
An AISP is not able to pre-select a set of accounts for account-access-consent authorisation
An ASPSP creates the account-access-consents resource and responds with a unique ConsentId to refer to the resource
Prior to calling the API, the AISP must have an access token issued by the ASPSP using a client credentials grant
3.1.1 Account Access Consent Status
The user/customer must authenticate with the ASPSP and authorise the account-access-consent for the account-access-consent to be successfully setup. The account-access-consents resource that is created successfully must have the following Status code-list enumeration:
S. No. | Status | Status Description |
1 | AwaitingAuthorisation | The account access consent is awaiting authorisation |
After authorisation has taken place the account-access-consents resource may have these following statuses:
S. No. | Status | Status Description |
1 | Rejected | The account access consent has been rejected |
2 | Authorised | The account access consent has been successfully authorised |
3 | Revoked | The account access consent has been revoked via the AISP/ASPSP interface |
3.1.2 Status Flow
...
3.2 GET /account-access-consents/ {ConsentId}
An AISP may retrieve an account-access-consents resource that they have created to check its status.
Prior to calling the API, the AISP must have an access token issued by the ASPSP using a client credentials grant.
3.2.1 Account Access Consent Status
Once the user/customer authorises the account-access-consents resource - the Status of the account-access-consents resource will be updated with "Authorised".
The available Status code-list enumerations for the account-access-consents resource are:
S. No. | Status | Status Description |
1 | Rejected | The account access consent has been rejected |
2 | AwaitingAuthorisation | The account access consent is awaiting authorisation |
3 | Authorised | The account access consent has been successfully authorised |
4 | Revoked | The account access consent has been revoked via the AISP interface |
3.3 PATCH /account-access-consents/{ConsentId}
If the user/customer revokes consent to data access with the AISP, the AISP must patch the account-access-consents resource with the ASPSP as soon as is practically possible.
This is done by making a call to PATCH the account-access-consents resource
Prior to calling the API, the AISP must have an access token issued by the ASPSP using a client credentials grant
AISP should also clear the Account Access consents resources, from ASPSP’s system, which are:
Expired, i.e. user/customer doesn't want to refresh/re-authenticate it
4. Data Models
4.1 Account Access Consents - Request
The OBAccountAccessConsentRequest object will be used for the call to:
POST /account-access-consents
4.1.1 UML Diagram
...
4.1.1.1 Notes
The Account access consent request contains the following elements:
Permissions provided by the user/customer
Transaction from Date Time - A specified start date and time for the transaction query period
Transaction to Date Tome - A Specified end date and time for the transaction query period
4.1.2 Data Dictionary
Name | Occurrence | XPath | Enhanced Definition | Class/ Datatype | Codes |
OBAccountAccessConsentRequest |
| OBAccountAccessConsentRequest |
| OBAccountAccessConsentRequest |
|
Data | 1..1 | OBAccountAccessConsentRequest/Data |
| OBAccountAccessConsentRequest/Data |
|
Permissions | 1..n | OBAccountAccessConsentRequest/Data/Permissions | Specifies the Open Banking account access data types. This is a list of the data clusters being consented by the User/Customer, and requested for authorisation with the ASPSP | String | Enum:
|
TransactionFromDateTime | 0..1 | OBAccountAccessConsentRequest/Data/TransactionFromDateTime | Specified start date and time for the transaction query period. If this is not populated, the start date will be open ended, and data will be returned for upto the last 12 months from the date of customer providing consent | DateTime |
|
TransactionToDateTime | 0..1 | OBAccountAccessConsentRequest/Data/TransactionToDateTime | Specified end date and time for the transaction query period. If this is not populated, the end date will be open ended, and data will be returned till the date of customer providing consent | DateTime |
|
4.2 Access Account Consents - Response
The OBAccountAccessConsentResponse object will be used for the call to:
GET /account-access-consents/{ConsentId}
And response to:
POST /account-access-consents
4.2.1 UML Diagram
...
4.2.2 Notes
The OBAccountAccessConsentResponse contains these objects:
The OBAccountAccessConsentResponse object contains the same information as the OBAccountAccessConsentRequest, but with additional fields:
ConsentId - to uniquely identify the account-access-consents resource
Status
CreationDateTime
StatusUpdateDateTime
4.2.3 Data Dictionary
Name | Occurrence | XPath | Enhanced Definition | Class/ Datatype | Codes |
OBAccountAccessConsentResponse |
| OBAccountAccessConsentResponse |
| OBAccountAccessConsentResponse |
|
Data | 1..1 | OBAccountAccessConsentRequestOBAccountAccessConsentResponse/Data |
| OBAccountAccessConsentRequestOBAccountAccessConsentResponse/Data |
|
PermissionsConsentId | 1..n1 | OBAccountAccessConsentRequestOBAccountAccessConsentResponse/Data/Permissions | Specifies the Open Banking account access data types. This is a list of the data clusters being consented by the PSU, and requested for authorisation with the ASPSP | String | Enum:
|
ExpirationDateTime | 0..1 | OBAccountAccessConsentRequest/Data/ExpirationDateTime | Specified date and time the permissions will expire. If this is not populated, the permissions will be open ended | DateTime |
|
TransactionFromDateTime | 0..1 | OBAccountAccessConsentRequest/Data/TransactionFromDateTime | Specified start date and time for the transaction query period. If this is not populated, the start date will be open ended, and data will be returned from the earliest available transaction | DateTime |
|
TransactionToDateTime | 0..1 | OBAccountAccessConsentRequest/Data/TransactionToDateTime | Specified end date and time for the transaction query period. If this is not populated, the end date will be open ended, and data will be returned to the latest available transaction | DateTime |
|
Risk | 1..1 | OBAccountAccessConsentRequest/Risk | The Risk section is sent by the initiating party to the ASPSP. It is used to specify additional details for risk scoring for Account Info | OBRisk |
|
3.2. Access Account Consents - Response
The OBAccountAccessConsentResponse object will be used for the call to:
GET /account-access-consents/{ConsentId}
And response to:
POST /account-access-consents
3.2.1 UML Diagram
...
3.2.2 Notes
The domestic-payment-consent request contains these objects:
The OBAccountAccessConsentResponse object contains the same information as the OBAccountAccessConsentRequest, but with additional fields:
ConsentId - to uniquely identify the account-access-consent resource.
Status.
CreationDateTime.
StatusUpdateDateTime.
3.2.3 Data Dictionary
...
Name
...
Occurrence
...
XPath
...
Definition
...
Class/ Datatype
...
Codes
...
OBAccountAccessConsentResponse
...
...
OBAccountAccessConsentResponse
...
...
OBAccountAccessConsentResponse
...
...
Data
...
1..1
...
OBAccountAccessConsentResponse/Data
...
...
OBAccountAccessConsentResponse/Data
...
...
ConsentId
...
1..1
...
OBAccountAccessConsentResponse/Data/ConsentId
...
Unique identification as assigned to identify the account access consent resource.
...
String
...
...
CreationDateTime
...
1..1
...
OBAccountAccessConsentResponse/Data/CreationDateTime
...
Date and time at which the resource was created.
...
DateTime
...
...
Status
...
1..1
...
OBAccountAccessConsentResponse/Data/Status
...
Specifies the status of consent resource in code form.
...
String
...
Enum:
Authorised
AwaitingAuthorisation
Rejected
Revoked
...
StatusUpdateDateTime
...
1..1
...
OBAccountAccessConsentResponse/Data/StatusUpdateDateTime
...
DateTime
...
...
Permissions
...
1..n
...
OBAccountAccessConsentResponse/Data/Permissions
...
Specifies the Open Banking account access data types. This is a list of the data clusters being consented by the PSU, and requested for authorisation with the ASPSP
...
String
...
Enum:
ReadAccountsBasic
ReadAccountsDetail
ReadBalances
ReadBeneficiariesBasic
ReadBeneficiariesDetail
ReadDirectDebits
ReadOffers
ReadPAN
ReadParty
ReadPartyPS
ReadProducts
ReadScheduledPaymentsBasic
ReadScheduledPaymentsDetail
ReadStandingOrdersBasic
ReadStandingOrdersDetail
ReadStatementsBasic
ReadStatementsDetail
ReadTransactionsBasic
ReadTransactionsCredits
ReadTransactionsDebits
ReadTransactionsDetail
...
ExpirationDateTime
...
0..1
...
OBAccountAccessConsentResponse/Data/ExpirationDateTime
...
Specified date and time the permissions will expire. If this is not populated, the permissions will be open ended
...
DateTime
...
...
TransactionFromDateTime
...
0..1
...
OBAccountAccessConsentResponse/Data/TransactionFromDateTime
...
Specified start date and time for the transaction query period. If this is not populated, the start date will be open ended, and data will be returned from the earliest available transaction
...
DateTime
...
...
TransactionToDateTime
...
0..1
...
OBAccountAccessConsentResponse/Data/TransactionToDateTime
...
Specified end date and time for the transaction query period. If this is not populated, the end date will be open ended, and data will be returned to the latest available transaction
...
DateTime
...
...
Risk
...
1..1
...
OBAccountAccessConsentResponse/Risk
...
The Risk section is sent by the initiating party to the ASPSP. It is used to specify additional details for risk scoring for Account Info
...
OBRisk
...
...
Links
...
0..1
...
OBAccountAccessConsentResponse/Links
...
Links relevant to the payload
...
Links
...
...
Meta
...
0..1
...
OBAccountAccessConsentResponse/Meta
...
Meta Data relevant to the payload
...
Meta
...
=
4. Usage Example
4.1. Post Account Access Consents
4.1.1 Request
...
POST /account-access-consents
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
x-fapi-auth-date: Sun, 10 Sep 2020 19:43:31 GMT
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json
Accept: application/json
|
4.1.2 Response
ConsentId | Unique identification as assigned to identify the account access consents resource | String |
| ||
CreationDateTime | 1..1 | OBAccountAccessConsentResponse/Data/CreationDateTime | Date and time at which the resource was created | DateTime |
|
Status | 1..1 | OBAccountAccessConsentResponse/Data/Status | Specifies the status of consents resource in code form | String | Enum:
|
StatusUpdateDateTime | 1..1 | OBAccountAccessConsentResponse/Data/StatusUpdateDateTime |
| DateTime |
|
Permissions | 1..n | OBAccountAccessConsentResponse/Data/Permissions | Specifies the Open Banking account access data types. This is a list of the data clusters being consented by the User/Customer, and requested for authorisation with the ASPSP | String | Enum:
|
TransactionFromDateTime | 0..1 | OBAccountAccessConsentResponse/Data/TransactionFromDateTime | Specified start date and time for the transaction query period. If this is not populated, the start date will be open ended, and data will be returned for upto the last 12 months from the date of customer providing consent | DateTime |
|
TransactionToDateTime | 0..1 | OBAccountAccessConsentResponse/Data/TransactionToDateTime | Specified end date and time for the transaction query period. If this is not populated, the end date will be open ended, and data will be returned till the date of customer providing consent | DateTime |
|
4.3. Access Account Consents - Patch Consent – Request
The OBPatchAccountAccessConsentRequest object will be used for the call to:
PATCH /account-access-consents/{ConsentId}
4.3.1 UML Diagram
...
4.3.2 Data Dictionary
Name | Occurrence | XPath | Enhanced Definition | Class/ Datatype | Codes | Pattern |
OBPatchAccountAccessConsentRequest |
| OBPatchAccountAccessConsentRequest |
| OBPatchAccountAccessConsentRequest |
|
|
Data | 1..1 | OBPatchAccountAccessConsentRequest/Data |
| OBPatchAccountAccessConsentRequest/Data |
|
|
Status | 1..1 | OBPatchAccountAccessConsentRequest/Data/Status | Specifies the status of consents resource in code form | String | Enum:
|
|
5. Usage Example
5.1 Post Account Access Consents
5.1.1 Request
|
|
5.1.2 Response
|
|
5.2 GET /account-access-consents/{ConsentId}
5.2.1 Request
|
5.2.2 Response
|
|
...
5.3 PATCH /account-access-consents/{ConsentId}
...
5.
...
3.
...
1 Request
|
4.2.2 Response
|
|
5.3.2 Response
|
|
4.3. DELETE /account-access-consents/{ConsentId}
4.3.1 Request
|
4.3.2 Response
|
CENTRAL BANK OF BAHRAIN © 2020