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 response 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 by "Open Banking Service".

Processing flow for this scenario is similar to described in “AIS with Redirect Authorisation + Accounts + Balances + Transactions (With Date filter only)” section with addition of GET /download/transactions API to be called by initiating party (user).

 

Step – 1 : Get the reach details :

Reach details provides list of APIs needs to be used for this scenario and mandatory fields needs to be passed for successful API call towards ASPSP mock.

Call the reach API – GET /aspsps. Get the ASPSP details with Name = “Account information redirect + Download transactions” and the ASPSP ID = “20102”, which has to be used to initiate the consent with redirect mode of authorisation and other further requests.

Remark : Details of reach information provided in developer portal are limited and informational purpose to give initiating party (user) an idea about how reach information looks like. Initiating party (user) can skip this step and use specified ASPSP ID for the scenario to try out.

 

Step - 2 : Obtain customer's (PSU) consent to access accounts information :

Call the POST /consents API to obtain customer's (PSU) consent. In response of POST /consents, initiating party (user) will receive consent ID, ASPSP redirect link to authorise the consent and link to call GET /consents/status API to get the status of the consent.

Below are some consent related functionalities initiating party (user) can try out.

• Below consent permissions are supported to access customer's (PSU) details.

  Permissions (Array)

   {[

      "Accounts",

      "Balances",

      "Transactions"

   ]}

Initiating party (user) can request permissions in below combination based on customer's (PSU) request:

- Request permissions for only "Accounts" - Initiating party (user) can only request list of accounts from customer's (PSU) bank. Balances and Transaction details cannot be requested.

- Request permissions for "Accounts", "Balances" - Initiating party can get request of accounts and balances details for requested accounts from customer's (PSU) bank.

- Request permissions for "Accounts", "Transactions" - Initiating party can request list of accounts and transaction details for requested accounts from customer's (PSU) bank.

- Request permissions for "Accounts", "Balances", "Transactions" - Initiating party can request list of accounts, balances and transaction details for requested accounts from customer's (PSU) bank.

- If there's no permissions provided in request, by default "Open Banking Service" sends request to get the consent for "Accounts", "Balances", "Transactions" from ASPSP.

- If "OwnerName" indicator set to "true" in consents request, initiating party (user) can receive actual owner name (if supported and provided by ASPSP) in response of GET /accounts API.

- "TransactionFromDateTime" and "TransactionToDateTime" can be provided in POST /consents request, so that Initiating party (user) can access list of transactions within a specific time period only.

- The fields below are being ignored in POST /consents request in the sandbox.

• ValidUntilDate,
• FrequencyPerDay,
• RecurringIndicatior,
• CombinedServiceIndicator,
• PreferredScaMethod

If GET /consents/status endpoint has been called before user provides his / her approval, initiating party (user) will receive consent status = "Open" from the ASPSP Mock in response.

 

Step - 3 : Authorise or Cancel the consent at ASPSP Mock :

With ASPSP redirect link received in response of POST /consents, customer (PSU) will get redirect to ASPSP Mock GUI login page. On this login page, customer (PSU) can provide dummy credential details as ASPSP GUI page is example purpose only. Once customer  (PSU) provides his / her dummy credentials, he / she will be redirected to ASPSP Mock GUI page with "Approve" & "Deny" buttons to authorise or reject the consent.

If customer (PSU) "Approve" the consent, consent will be created with the ASPSP Mock and customer (PSU) will redirect back to initiating party (user).

If customer (PSU) "Deny" the consent, ASPSP Mock will reject the consent request and customer (PSU) will redirect back to initiating party (user).

Remark : GUI pages of ASPSP Mock for customer login and to authorise the consent is just a demo purpose. Actual ASPSP GUI pages may vary based on acutal ASPSP.

 

Step - 4 : Get the consent status :

Call the GET /consents/status API to get the latest consent status from ASPSP Mock.

If consent is authorised by customer (PSU), initiating party (user) will receive consent status = "Authorised".

If consent is deny by customer (PSU), initiating party (user) will receive consent status = "Rejected" as final consent status.

Remark : Consent status provided for this scenario is just to guide initiating party (user) for consent process. Actual consent status may vary based on scenario from actual ASPSP.

 

Step - 5 : Get the list of accounts :

Once consent is authorised by the customer (PSU), call the GET /accounts API to obtain list of accounts from ASPSP Mock.

 

Step - 6 : Get balances details for respective account :

Once initiating party (user) obtains list of accounts from ASPSP Mock, call GET /balances API to get the balance details of respective account from ASPSP Mock.

Remark : This is an optional step for this scenario. User can skip this step.

 

Step - 7 : Get the transaction details for respective account :

After getting list of customer's (PSU) accounts from ASPSP Mock, call the GET /transactions API to retrieve transactions details of respective account from ASPSP Mock. In response, initiating party (user) will receive GET /download/transactions API link.

 

Step - 8 : Call the GET /download/transactions API :

Call the GET /download/transactions API and in response initiating party (user) will receive streamed JSON structure.

 

Sequence Diagram :

 

Using this scenario, initiating party (user) can request transaction data from ASPSP Mock using date & time filter ("dateFrom" & "dateTo" query parameters). This is to let initiating party (user) know that some actual ASPSPs are provides requested transaction data based on date & time.

 

Step - 1 : Get the reach details :

Reach details provides list of APIs and mandatory fields needs to be used for successful request towards ASPSP mock.

Call the reach API - GET /aspsps. Get the ASPSP details with Name = "Account Information redirect + Transaction datetime filter" and the ASPSP ID = "20116", which has to be used to initiate the consent with redirect mode of authorisation and other further requests.

Remark : Details of reach information provided in developer portal are limited and informational purpose to give initiating party (user) an idea about how reach information looks like. Initiating party (user) can skip this step and use specified ASPSP ID for the scenario to try out.

 

Step - 2 : Obtain customer's (PSU) consent to access accounts information :

Call the POST /consents API to obtain customer's (PSU) consent. In response of POST /consents, initiating party (user) will receive consent ID, ASPSP redirect link to authorise the consent and link to call GET /consents/status API to get the status of the consent.

Below are some consent related functionalities initiating party (user) can try out.

• Below consent permissions are supported to access customer's (PSU) details.

   Permissions (Array)

   {[

      "Accounts",

      "Balances",

      "Transactions"

   ]}

Initiating party (user) can request permissions in below combination based on customer's (PSU) request:

- Request permissions for only "Accounts" - Initiating party (user) can only request list of accounts from customer's (PSU) bank. Balances and Transaction details cannot be requested.

- Request permissions for "Accounts", "Balances" - Initiating party can get request of accounts and balances details for requested accounts from customer's (PSU) bank.

- Request permissions for "Accounts", "Transactions" - Initiating party can request list of accounts and transaction details for requested accounts from customer's (PSU) bank.

- Request permissions for "Accounts", "Balances", "Transactions" - Initiating party can request list of accounts, balances and transaction details for requested accounts from customer's (PSU) bank.

- If there's no permissions provided in request, by default "Open Banking Service" sends request to get the consent for "Accounts", "Balances", "Transactions" from ASPSP

• If "OwnerName" indicator set to "true" in consents request, initiating party (user) can receive actual owner name (if supported and provided by ASPSP) in response of GET /accounts API.
• "TransactionFromDateTime" and "TransactionToDateTime" can be provided in POST /consents request, so that initiating party (user) can access list of transactions within a specific time period only.
• Currently below fields are being ignored in POST /consents request in developer portal. We may introduce another scenario later on to include below fields functionalities.
• ValidUntilDate,
• FrequencyPerDay,
• RecurringIndicatior,
• CombinedServiceIndicator,
• PreferredScaMethod

If GET /consents/status endpoint has been called before user provides his / her approval, initiating party (user) will receive consent status = "Open" from the ASPSP Mock in response.

 

Step - 3 : Authorise or Cancel the consent at ASPSP Mock :

With ASPSP redirect link received in response of POST /consents, customer (PSU) will get redirect to ASPSP Mock GUI login page. On this login page, customer (PSU) can provide dummy credential details as ASPSP GUI page is example purpose only. Once customer  (PSU) provides his / her dummy credentials, he / she will be rediereted to ASPSP Mock GUI page with "Approve" & "Deny" buttons to authorise or reject the consent.

If customer (PSU) "Approve" the consent, consent will be created with the ASPSP Mock and customer (PSU) will redirect back to initiating party (user).

If customer (PSU) "Deny" the consent, ASPSP Mock will reject the consent request and customer (PSU) will redirect back to initiating party (user).

Remark : GUI pages of ASPSP Mock for customer login and to authorise the consent is just a demo purpose. Actual ASPSP GUI pages may vary based on actual ASPSP.

 

Step - 4 : Get the consent status :

Call the GET /consents/status API to get the latest consent status from ASPSP Mock.

If consent is authorised by customer (PSU), initiating party (user) will receive consent status = "Authorised".

If consent is deny by customer (PSU), initiating party (user) will receive consent status = "Rejected" as final consent status.

Remark : Consent status provided for this scenario is just to guide initiating party (user) for consent process. Actual consent status may vary based on scenario from actual ASPSP.

 

Step - 5 : Get the list of accounts :

Once consent is authorised by the customer (PSU), call the GET /accounts API to obtain list of accounts from ASPSP Mock.

 

Step - 6 : Get balances details for respective account :

Once initiating party (user) obtains list of accounts from ASPSP Mock, call GET /balances API to get the balance details of respective account from ASPSP Mock.

 

Step - 7 : Get the transaction details for respective account :

Call the GET /transactions API to retrieve transactions details of respective account from ASPSP Mock. Initiating party (user) can try out below functionalities of GET /transactions API.

• Initiating party (user) can request to get transaction data for specific date range using "dateFrom" & "dateTo" query parameters. Remark : For this filter if initiating party (user) provides date & time in "dateFrom" & "dateTo" fields, ASPSP Mock will return transaction data based on both date & time provided. This is to let initiating party (user) know that some actual ASPSPs are also behaves the same way to filter transaction data (Omit time part).
• If ASPS Mock respond with large number of transactions, initiating party (user) may receive paginated transactions response.
• In case of paginated response, initiating party (user) can retrieve appropriate transactions page using "first", "next", "previous", "last", "self" links provided in response.

 

Sequence Diagram :

 

  Customer's (PSU) consent needs to be acquire first to access his / her bank's accounts details. In the Redirect Authorisation approach, the browser session of the customer (PSU) is redirected from the Initiating Party (user) to the ASPSP Mock. In that case the ASPSP Mock provides all the pages required for authentication (usually username, password). After that the customer (PSU) is redirected to the "Open Banking Service" and from there back to the Initiating Party (user).

Take the following steps to complete this scenario.

 

Step - 1 : Get the reach details :

Reach details provides list of APIs and mandatory fields needs to be used for successful request towards ASPSP mock.

Call the reach API - GET /aspsps. Get the ASPSP details with Name = "Account Information redirect + Transaction Date filter" and the ASPSP ID = "20101", which has to be used to initiate the consent with redirect mode of authorisation and other further requests.

Remark : Details of reach information provided in developer portal are limited and informational purpose to give initiating party (user) an idea about how reach information looks like. Initiating party (user) can skip this step and use specified ASPSP ID for the scenario to try out.

 

Step - 2 : Obtain customer's (PSU) consent to access accounts information :

Call the POST /consents API to obtain customer's (PSU) consent. In response of POST /consents, initiating party (user) will receive consent ID, ASPSP redirect link to authorise the consent and link to call GET /consent/status API to get the status of the consent.

Below are some consent related functionalities initiating party (user) can try out.

• Below consent permissions are supported to access customer's (PSU) details.

   Permissions (Array)

   {[

      "Accounts",

      "Balances",

      "Transactions"

   ]}

 Initiating party (user) can request permissions in below combination based on customer's (PSU) request:

- Request permissions for only "Accounts" - Initiating party (user) can only request list of accounts from customer's (PSU) bank. Balances and Transaction details cannot be requested.

- Request permissions for "Accounts", "Balances" - Initiating party can get request of accounts and balances details for requested accounts from customer's (PSU) bank.

- Request permissions for "Accounts", "Transactions" - Initiating party can request list of accounts and transaction details for requested accounts from customer's (PSU) bank.

- Request permissions for "Accounts", "Balances", "Transactions" - Initiating party can request list of accounts, balances and transaction details for requested accounts from customer's (PSU) bank.

If there's no permissions provided in request, by default "Open Banking Service" sends request to get the consent for "Accounts", "Balances", "Transactions" from ASPSP

• If "OwnerName" indicator set to "true" in consent request, initiating party (user) can receive actual owner name (if supported and provided by ASPSP) in response of GET /accounts API.
• "TransactionFromDateTime" and "TransactionToDateTime" can be provided in POST /consents request, so that initiationg party (user) can access list of transactions within a specific time period only.
• Currently below fields are being ignored in POST /consents request in developer portal. We may introduce another scenario later on to include below fields functionalities.
• ValidUntilDate,
• FrequencyPerDay,
• RecurringIndicatior,
• CombinedServiceIndicator,
• PreferredScaMethod

If GET /consents/status endpoint has been called before user provides his / her approval, initiating party (user) will receive consent status = "Open" from the ASPSP Mock in response.

 

Step - 3 : Authorise or Cancel the consent at ASPSP Mock :

With ASPSP redirect link received in response of POST /consents, customer (PSU) will get redirect to ASPSP Mock GUI login page. On this login page, customer (PSU) can provide dummy credential details as ASPSP GUI page is example purpose only. Once customer  (PSU) provides his / her dummy credentials, he / she will be redirected to ASPSP Mock GUI page with "Approve" & "Deny" buttons to authorise or reject the consent.

If customer (PSU) "Approve" the consent, consent will be created with the ASPSP Mock and customer (PSU) will redirect back to initiating party (user).

If customer (PSU) "Deny" the consent, ASPSP Mock will reject the consent request and customer (PSU) will redirect back to initiating party (user).

Remark : GUI pages of ASPSP Mock for customer login and to authorise the consent is just a demo purpose. Actual ASPSP GUI pages may vary based on actual ASPSP.

 

Step - 4 : Get the consent status :

Call the GET /consents/status API to get the latest consent status from ASPSP Mock.

If consent is authorised by customer (PSU), initiating party (user) will receive consent status = "Authorised".

If consent is deny by customer (PSU), initiating party (user) will receive consent status = "Rejected" as final consent status.

Remark : Consent status provided for this scenario is just to guide initiating party (user) for consent process. Actual consent status may vary based on scenario from actual ASPSP.

 

Step - 5 : Get the list of accounts :

Once consent is authorised by the customer (PSU), call the GET /accounts API to obtain list of accounts from ASPSP Mock.

 

Step - 6 : Get balances details for respective account :

Once initiating party (user) obtains list of accounts from ASPSP Mock, call GET /balances API to get the balance details of respective account from ASPSP Mock.

 

Step - 7 : Get the transaction details for respective account :

Call the GET /transactions API to retrieve transactions details of respective account from ASPSP Mock. Initiating party (user) can try out below functionalities of GET /transactions API.

• Initiating party (user) can request to get transaction data for specific date range using "dateFrom" & "dateTo" query parameters. Remark : For this filter if initiating party (user) provides date & time in "dateFrom" & "dateTo" fields, ASPSP Mock will return transaction data based on date only. It will omit time part to filter transaction data. This is to let initiating party (user) know that some actual ASPSPs are also behaves the same way to filter transaction data (Omit time part).
• If ASPS Mock respond with large number of transactions, initiating party (user) may receive paginated transactions response.
• In case of paginated response, initiating party (user) can retrieve appropriate transaction page using "first", "next", "previous", "last", "self" links provided in response.

 

Sequence Diagram :

 

Below you'll find a list of Account Information Scenarios. Each scenario has a separate page with a step by step description of the steps to complete the scenario. You can choose a scenario by providing the corresponding ASPSP ID in the request which initiates the consent.

To simplify the interaction, these scenario's work with a static token which doesn't expire. This sandbox token is supplied in the API reference.

You can use the sandbox:

• On the API reference page (only for registered users, look for the 'try' button)

• With a tool like Postman

Sr. No.	Scenario Name	ASPSP ID	Scenario Guideline
01.	AIS with Redirect Authorisation and Accounts, Balances & Transactions (Date filter only)	20101	Read more
02.	AIS with Redirect Authorisation and Accounts, Balances & Transactions (DateTime filter)	20116	Read more
03.	AIS Download Transactions	20102	Read more
04.	AIS Delete Consents	20101	Read more

 

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:

The Reach Directory API allows the Initiating Party to retrieve a list of all reachable ASPSP's via the Open Banking Service. The main information that can be received is the ASPSP name and ID, which has to be used to identify the ASPSP to which the payment should be addressed.

The information returned by the Reach Directory API doesn't change frequently. It will be sufficient to retrieve a new list once a day.

ASPSP's have implemented their APIs based on several standards, sometimes with proprietary deviations. Since the Open Banking Service offers a unified API to reach ASPSP's, additional information is provided to inform the Initiating Party about specific details required to make a successful payment request.

How these specific details are communicated in the Reach Directory response is described in the sections 'Details' and 'Options'

Details

The Details section in the reach directory response consists of the following fields:

• Api
• FieldName
• Type
• Value
• ProtocolVersion

Mandatory information in this section is the Api, which is defining for which endpoint the information is applicable. If there is no FieldName given, the Type is describing whether this endpoint is available (SUPPORTED) or not (UNSUPPORTED).

Type	Description if NOT combined with a FieldName
UNSUPPORTED	The mentioned Api is not supported by the ASPSP, the TPP solution will throw an error if it’s used. This is mentioned for Api’s which are normally supported (for the api’s not mentioned in the row below)
SUPPORTED	The mentioned Api is supported by the ASPSP. This is mentioned for the following Api’s (because they are usually not supported): - POST /psus/{psuId}/Aspsps/{aspspId}/pre-authentication" If the Post is supported the corresponding api methods (GET, PUT, DELETE) are also supported, if defined in the swagger.

If the FieldName is given, the Type is describing whether the field is UNSUPPORTED, SUPPORTED, MANDATORY or FORBIDDEN. The table below specifies the rules for the Type-FieldName combination:

Type	Description if combined with a FieldName
UNSUPPORTED	The mentioned FieldName is ignored if provided to the TPP solution, the TPP solution will not throw an error
SUPPORTED	A subset of the values in the mentioned FieldName is supported. The Value field (which is always supplied with the SUPPORTED Type) will indicate which values are supported. If no value is provided by the initiating party the TPP solution will use a default value. If an unsupported value is used, the TPP solution will throw an error.
MANDATORY	The mentioned FieldName is mandatory and has to be filled. If supplied, the Value field will indicate which values are supported. If the Value field is not supplied no validation on the field is done by the TPP solution. If the mentioned FieldName is not filled by the initiating party the TPP solution will throw an error. If an unsupported value is used, the TPP solution will throw an error.
FORBIDDEN	The mentioned FieldName is forbidden. The TPP solution will throw an error if the initiating party fills this field and the request will not be sent to the Aspsp.

The FieldName may refer to a header field in the same way. Since the fields in an API endpoint are unique for header and body there is no distinction between header and body in the Details record.

The Value is providing detailed information of that field within the given Api. If the Value contains a list of values, they are separated by ‘|’.

In addition the ProtocolVersion used for the communication between the TPP solution and the ASPSP is provided, although this information isn’t crucial for the Initiating Party.

Example for API

An example for API without the FieldName is the pre-authentication API. For most ASPSPs a pre-authentication is not supported. For those ASPSPs where a pre-authentication is possible there is a record in the Details:

"Api": "POST /psus/{psuId}/Aspsps/{aspspId}/pre-authentication",
"Type": "SUPPORTED",
"ProtocolVersion": "BG_V_1_3_0"

Examples for API combined with FieldName

An example of API combined with a FieldName is the Post /payments API with the PaymentProduct field. This field is defined as optional in the corresponding swagger file. The swagger also indicates that four values can be given: Normal, Instant, Target2 or Domestic. In the case that only a subset of these values is supported by the ASPSP, the following record is provided in the reach directory response:

"Api": "POST /payments",
"FieldName": "PaymentProduct",
"Type": "SUPPORTED",
"Value": "Normal|Instant",
"ProtocolVersion": "BG_V_1_3_0"

In this example above Type SUPPORTED indicates the PaymentProduct field is still optional but the values to be used are restricted to Normal and Instant.

It would be possible to configure the same for Type MANDATORY. In that case the PaymentProduct has to be specified in the POST payment request.

"Api": "POST /payments",
"FieldName": "DebtorName",
"Type": "MANDATORY",
"ProtocolVersion": "BG_V_1_3_0"

In this example the Type is MANDATORY, the DebtorName has to be provided in the body. No Value is given, so no validation is done for the content.

Options

The Options section is providing information regarding the way of using API endpoints for specific ASPSPs similar to the Details section. But the information given here is not that specifically related a single API’s endpoint. It is more to be seen as a parameter for the ASPSP itself even though a clear separation between API endpoint and ASPSP globally isn’t that clear always.

Since the Options are not defined for a single endpoint there is no Api attribute given for the single options. Instead they have two keys (Key1 and Key2) identifying the use of the single Option. An example for this is:

"Key1": "PREAUTH_MANDATORY",
"Value": "1",
"Level": "INFORMATIONAL"

In this case for the given ASPSP pre-authentication is mandatory because the value is set to 1. The setting of 1 is reflecting that the option is set. A list of possible option keys is given below. The Key2 is currently not used. It is foreseen to allow definition of grouped options having the same main key Key1 and a different sub-key key2. An example for options provided in the Reach API is shown below:

Key1	Key2	Value	Level	Description
PREAUTH_MANDATORY		1, 0	INFORMATIONAL	The pre-authentication (regardless whether being done implicitly or explicitly) is mandatory. Default 0
PREAUTH_EXPLICIT_REQUIRED		1, 0	CRITICAL	Pre-authentication has to be done explicitly by the POST pre-authentication endpoint
ACCOUNT_REFERENCES_SUPPORTEDFORMS		Filled, Empty, AvailableAccounts, AvailableAccountsWithBalances, AllPSD2	INFORMATIONAL	More information on the values can be found on the Account Information API page

GET ASPSPs

The base URL for the Reach Directory is: /xs2a/routingservice/services/directory/v3 

Endpoint: GET /aspsps

This endpoint is used to retrieve the reach directory.

Request

Response

Example: Reach AIS

Request

GET https://xs2a.ewl.de/xs2a/routingservice/services/directory/v2/ASPSPs?allDetails=true&allOptions=true
 
Authorization: Bearer dc983c2fe3bd5cf2565cde42805e236e
Accept: application/json
Content-Type: application/json
X-Request-Id: ABCDEF12-2000-4000-1234-f61950068a1c
MessageCreateDateTime: 2020-08-19T10:11:36.770+02:00
Host: xs2a.ewl.de

Response

HTTP/1.1 200 OK
Cache-Control: no-cache,no-store
MessageCreateDateTime: 2020-08-19T10:44:36.258Z
X-Request-Id: 1af27926-08f4-4479-865a-d6dcca5d11
Pragma: no-cache
Date: Wed, 19 Aug 2020 10:44:36 GMT
Connection: keep-alive
Strict-Transport-Security: max-age=31536000 ; includeSubDomains; preload
Transfer-Encoding: chunked
Content-Type: application/json
{
    "Service": "AIS",
    "ASPSP":     [
              {
            "AspspId": "6002",
            "Name": [    {
                "Label": "Your Bank",
                "Language": "en"
            }],
            "CountryCode": "GB",
            "CategoryLabel": [],
            "Details": [{"ProtocolVersion": "OB_UK_V_1_1_1"}],
            "Options": [],
            "BIC": "BNPADEFE"
        },                {
            "AspspId": "50002",
              "Name": [   {
                "Label": "Second Bank",
                "Language": "en"
            }],
            "CountryCode": "DE",
            "CategoryLabel": [Retail],
            "Details": [            {
                "Api": "POST /psus/{psuId}/aspsps/{aspspId}/pre-authentication",
                "Type": "SUPPORTED",
                "ProtocolVersion": "BG_V_1_3_0"
            },            {
                "Api": "POST /payments",
                "FieldName": "DebtorName",
                "Type": "MANDATORY",
                "ProtocolVersion": "BG_V_1_3_0"
            },            {
                "Api": "POST /payments",
                "FieldName": "PaymentProduct",
                "Type": "MANDATORY",
                "Value": "Normal|Instant|Target2|Domestic",
                "ProtocolVersion": "BG_V_1_3_0"
            }],
            "Options": [            {
                "Key1": "PREAUTH_MANDATORY",
                "Value": "1",
                "Level": "INFORMATIONAL"
            }],
            "BIC": "DE12ZZZ123"
        }
    ]
}

ais transaction flow

The APIs presented in the Account Information section can be used to access a PSU’s (Payment Service User) bank account, held with any reachable ASPSP. Retrieval of PSU’s account information is only allowed upon explicit consent of the account holder.

Account Information Consent

The APIs for Account Information require consent by the PSU. There are different approaches offered by the different ASPSPs to authorize this consent. Although the implementation may differ for some ASPSPs they can be categorized to three types: 

• Redirect
• Decoupled
• Embedded

Redirect

In the Redirect Approach the browser session of the PSU is redirected from the Initiating Party to the ASPSP. In that case the ASPSP provides all the pages required for authentication (usually username, password) and for the Strong Customer Authentication SCA for example by a One Time Password (OTP). After that the PSU is redirected to the Open Banking Service and from there back to the Initiating Party.

Decoupled

In the Decoupled Approach no redirection takes place. Instead the ASPSP notifies the PSU on a mobile App for example. The authentication is executed by the app without involving the Initiating Party or the Open Banking Service. Since this approach is asynchronous the Initiating Party (and the Open Banking Service) do not know when the authentication process has been finished and the status of the consent or payment at the ASPSP has been updated. 

Embedded

In the Embedded Approach the Initiating Party has to provide all the screens required for the authentication process and to communicate all necessary steps over the API of the Open Banking Service to the ASPSP. 

Authorisation steps

In any case the Initiating Party can set the PreferredScaMethod (Embedded, Decoupled, Redirect) to select the preferred SCA approach with the consent Initiation Request. However, the selection of the approach will be by the ASPSP, depending on whether it supports a few of them, or just one. Even if the requested approach is supported, it might not be guaranteed, that the ASPSP will select it. 

The Initiating Party can set UseAuthorisationLandingPages (true, false) to true to use the Bank Selection Interface. In the response he will then receive a RedirectUrl towards the Bank Selection Interface. The Bank Selection Interface will handle the authorisation flow for the specific ASPSP, including retrieving additional information from the PSU if required.

The selected flow with which authentication will go through, is being identified by the name of a hyperlink, provided in the response.

The table below includes every possible step with the corresponding approach. In the response of each request the named link informs about the next request to be sent according to the actual state in the flow.

Hyperlink Name	Hyperlink URL API	Description	SCA Approach
PreAuthenticationForEmbedded	POST /pre-auth	Pre-Authentication is required and will be made with Embedded Approach.	Embedded
RedirectUrl	Redirect link	URL of PSU’s authentication or authorisation on APSPS side, or towards the Initiation Service	Redirect
RedirectUrl (towards the Bank selection interface)	a Worldline URL, can optionally be white labeled	The Worldline provide Bank selection interface will take care of the subsequent authorization flow. In practice this means that from the Initiating Party perspective it will always be a redirect flow.	Redirect
PostAuthorisationForExplicit	POST /authorisation	Mostly is being used when multi-sca should be done with Redirect Approach. Nobody required in the request.	Redirect/Embedded
PostIdentificationForDecoupled	POST /identification	Requires PSU’s identification at ASPSP for Decoupled Approach.	Decoupled
PostAuthorisationForEmbedded	POST /authorisation	Start of Authentication with PSU’s credentials at ASPSP.	Embedded
SelectAuthenticationMethod	PUT /authorisation	The update of the authorisation resource where selected SCA method should be provided	Embedded
AuthorizeTransaction	PUT /authorisation	The update of the authorisation resource where challenge response (OTP) should be provided.	Embedded
ConfirmationRequired	POST /confirmation	Confirmation of the transaction after authorisation is being done or being exempted.	Redirect/Embedded/Decoupled
PutAuthorisationForEmbedded	PUT /authorisation	The update of the authorisation resource with PSU’s credentials, when some other authorisation steps have been done before.	Embedded

Sequence diagrams

Below the sequence of requests corresponding for the different approaches are shown in sequence diagrams. Depending on the individual implementation of the ASPSP the actual flow may differ slightly.

Redirect Flow Example

The sequence diagram below is an example of a typical AIS flow. In this case the Strong Customer Authentication SCA is done using the redirect flow. 

Once the status of the consent is retrieved with the Get psus/consents/status the consent is stored within the Open Banking Service (including all the relevant tokens if applicable for the ASPSP). When the Get psus/accounts API is called the Open Banking Service will use pick the correct consent and use it towards the ASPSP. The Initiating Party does not have to keep track of the consents himself. 

The consent can be valid for at most 90 days (this will change to 180 days in the near future). The Open Banking Service will provide an http 401 response with error code 123 ‘The PSU consent is expired’ if AIS data is requested after the validity of the consent is expired. The Initiating Party should then request a new consent.

Decoupled Flow Example

Embedded Flow Example

 

The Bank Selection Interface provides a set of white labeled screens which supports the ASPSP selection and the PSU interaction required for certain authorisation flows. It can be used by setting the field UseAuthorisationLandingPages= true in the Consent request. The Bank selection interface will simplify the integration effort for the Initiating Party.

Below a few screenshots how the screens look on a mobile device with the Worldline branding. Select the demonstration button above to see how the Bank Selection Interface works in a live setting.

Step 1: Bank Selection

Users quickly find their bank: we highlight popular ones and provide a blazing-fast search experience.

Step 2: Authorize access

After the user validates through the bank’s mobile app or SMS code, the user’s identity and IBAN are instantly retrieved.

Step 3: Account Selection

Users can select just the bank accounts they wish to share and give the consent

Step 4: Succes

Success! The user’s identity and IBAN are instantly retrieved