Consent
Before a TPP can access account information from a PSU he has to have consent of the PSU to do so.
The Open Banking Service will keep track of the consent status. And will check if the consent is in the authorized state before continuing towards the ASPSP.
A lot of banks allow one consent per PSU per TPP only. This becomes a problem if a TPP has Initiating Parties set up having a relation to the same PSU. If a PSU grants consent to a first Initiating Party for an account at a given ASPSP and afterwards grants consent to another Initiating Party for the same or another account at the same ASPSP this second consent will overwrite the first one at the ASPSP since it is requested via the same TPP. By that, the first Initiating Party will not be able to use its consent anymore at that ASPSP.
This is a structural problem introduced by the ASPSP by managing only one single consent for each PSU per TPP. There is an initiative ongoing to have ASPSPs extending their service by allowing multiple consents per PSU and TPP which would solve this problem.
Consent Status
Figure: Consent Status when GET consent/status API is called.
The consent status will be set when the GET consent/status API is called on the Open Banking Service.
| Status | Description |
|---|---|
| Open | In case of a redirect scenario, where a TPP has to take additional steps to get the consent, like redirecting the PSU towards the ASPSP |
| Pending | We didn’t get an answer yet. We stopped polling. The TPP should do a get consent to get an update on the status of the consent. |
| Rejected | Rejected by PSU/ASPSP |
| PartiallyAuthorised | The consent is due to a multi-level authorisation, some but not all mandated authorisations have been performed yet. |
| Authorised | Consent was granted, and is active. |
| Expired | The time the consent was active has been expired. |
| Revoked | Consent was revoked by PSU or ASPSP. |
| RevokedAtTpp |
Consent status changes to ‘RevokedAtTpp’ in the Open Banking Service if ASPSP responds with an error for DELETE Consents request. This is to inform the Initiating Party that the actual status of consent at ASPSP side is unknown due to error and the consent is not usable at TPP side anymore. |
| Error | An error occurred. |
| Inactive | Indicates that a consent is inactive because it has been replaced by a newer authorized consent (only 1 consent per psu- ASPSP protocol is allowed, so that the Open Banking Service doesn’t have to choose and can always just pick the authorized one while doing the other AIS calls). |
Permission
Consent can be given to grant access according to three permission groups:
- Accounts
- Balances
- Transactions
AIS Endpoints
The base URL for the account information service API is: /xs2a/routingservice/services/ob/ais/v3
(The most recent up-to-date reference of the API is given by the swagger files.)
POST Consents
Endpoint: POST /psus/{psuId}/consents
This endpoint is used by the Initiating Party to set up a consent for a PSU for an ASPSP.
Depending on the ASPSPs API the possible combinations of permissions and account references differ. In the Reach Directory 'Options' inform about the ASPSP specific options. The detailed information for an ASPSP for this API is given within the value for the Option ACCOUNT_REFERENCES_SUPPORTEDFORMS (see the chapter Reach API, Options) as list of parameters separated by a ‘|’. The available parameters are described in the table below. (The default for this list is: ‘Filled|Empty‘)
|
Parameter Value for ACCOUNT_REFERENCES_SUPPORTEDFORMS |
Comments |
|---|---|
| Filled | Account List is supported, if not set, the ‘PermittedAccountReferences’ are not supported |
| Empty | Empty account lists are supported, requests without account references are accepted |
| AvailableAccounts | If this set, empty ‘PermittedAccountReferences’ are interpreted as permission for accounts access only, if the permissions are requests for Accounts |
| AvailableAccountsWithBalances | If this set, empty ‘PermittedAccountReferences’ are interpreted as permission for accounts and balances access, if the permissions are requests for Accounts, Balances |
| AllPSD2 | If this set, empty ‘PermittedAccountReferences’ are interpreted as permission for accounts, balances and transactions access if the permissions are requests for Accounts, Balances, Transactions |
The Open Banking Service translates the given combination on requested permissions and account lists as shown in the diagram below. In the first step the requested permissions are set to the default (Accounts, Balances, Transactions) if no permissions are contained in the request.
figure: Initiating Party to set up a consent for a PSU for an ASPSP (PostConsents)
Request
Remarks
The body parameter ‘RecurringIndicator’ steers the ASPSP to grant a recurring consent, which can be reused within its validity period for an undefined number of AIS requests or for a single request (session) only. The default is to request a recurring consent. By default recurring consent is valid till 180 days, if ValidUntilDate is not provided.
Response
POST Identification
Endpoint: POST /psus/{psuId}/consents/{consentId}/identification
This endpoint is used in Decoupled Approach to start the authorization explicitly and identifying the PSU at the ASPSP to enable the Push message to be sent to the PSU’s device.
Request
Response
Remark
The Initiating Party will have to poll for status changes, since the authorization is done in Decoupled Approach and no feedback are provided by the ASPSP to the TPP directly.
POST Authorisations
Endpoint: POST /psus/{psuId}/consents/{consentId}/authorisations/{authorisationId}
This endpoint is used in 2 approaches
- Embedded Approach to start the authorisation and provide the required information according the first step of the embedded authorization flow.
- Redirect Approach to start explicit redirect authorisation. Mostly is being used in case of multi-level authorisation.
Request
Response
PUT Authorisations
Endpoint: PUT /psus/{psuId}/authorisations/{authorisationId}
This endpoint is used in Embedded Approach to provide the required information according to the necessary steps driven by the ASPSP due to the Links section.
Request
Response
GET Consent Status
Endpoint: GET /psus/{psuId}/consents/{consentId}/status
This endpoint is used to retrieve the status of a consent.
Request
Response
DELETE Consents
Endpoint: DELETE /psus/{psuId}/consents/{consentId}
This endpoint is used to revoke a consent. When this endpoint is called the Open Banking Service will also try to revoke the consent at ASPSP side. If this is successful the status of the consent will be changed to ‘Revoked’. If it’s not possible to revoke the status at the ASPSP side the status of the consent will be set to ‘RevokedAtTpp’, The consent might still be active on the ASPSP side bit will no longer be used by the Open Banking Service.
Request
Response
The response is an HTTP response with the HTTP code 204
GET Accounts
Endpoint: GET /psus/{psuId}/accounts
This endpoint is used to retrieve the list of accounts of a PSU.
Request
Response
GET Balances
Endpoint: GET /psus/{psuId}/aspsps/{aspspId}/accounts/{accountId}/balances
This endpoint is used to retrieve the balances of an account of a PSU.
Request
Response
GET Transactions
Endpoint: GET /psus/{psuId}/aspsps/{aspspId}/accounts/{accountId}/transactions
This endpoint is used to retrieve the balances of an account of a PSU.
Request
Response
GET Download Transactions
Endpoint: GET /download/psus/{psuId}/aspsps/{aspspId}/accounts/{accountId}/transactions
Some ASPSPs do not provide paginated transactions response. In those cases it isn’t possible to predict the number of transactions to be received in response of a GET transactions request. Even if the ASPSP is supporting paginated responses it might be possible that reponse on the GET transactions request contains a download link only and no transactions, if the number of transactions is considered too high. In this cases or if the bank isn’t giving the response instead of JSON in CAMT format for example, the Open Banking Service response on the GET transactions will have a download link instead of a set of transactions.
By calling that download link, the response will be given in a streamed JSON structure starting the stream of transactions already before all transactions are downloaded from the ASPSP. If the bank provides the transactions in a non-JSON format the transactions are converted to JSON on the fly.
Request
Response
The JSON structure of the response to this request is the same as it is for GET transactions. The only difference is that there will be no MetaData and no links like First, Prev, Next, Last or Download be contained.
AIS Extended service
AIS Extended: Multi-Level SCA
If the extended Services are subscribed for AIS, the Open Banking Service supports the Multi-Level SCA feature. In this case consent has to be authorized by multiple PSUs.
There are no specific endpoints defined for this. The single authorizations have to be started explicitly by the POST Authorization endpoint for each single PSU.
Registration Use Cases
The set of registration API's allows the initiating party to perform a specific use case with the AIS data. It's possible to add mulitple PSU's to one registration resource so that, for example, a Credit score can be calculated for a family.
note: post register can have an array of PSUs, the post register API can then be started for each PSU individually.
Example of a possible registration flow:
