Data account authorization use case

Account validation use case page

You can request to revoke account holder's consent. If the revocation is successful, the status of the consent will be changed to ‘Revoked’. If it’s not possible to revoke the consent, the status of the consent will be set to ‘RevokedAtTpp’, meaning the consent might still be active on the bank's side but can't no longer be used by you to retrieve the data.

In this testing scenario, it has been considered that consent has been revoked successfully. Take the following steps to complete this scenario.

Step - 1 : Get the list of connected banks

• Call Reach API (GET /aspsp) to obtain a list of supported banks. 
• Check API response of a record with ASPSP ID = "20101" and Name = "AIS Delete Consents".
• Details and Options section provide a list of API endpoints  and mandatory fields that need to be used for successful account data request towards the mock bank using redirect mode of authorisation .
• Remark: Details of reach information provided in the sandbox environment are limited and for informational purpose to give you an idea about how reach information looks like. 

Step - 2 : Initiate consent

• Call the POST /consents API to obtain account holder's consent. 
• In response of POST /consents, you will receive consent ID, a redirect link to authorise the consent and a link to call GET /consent/status API to get the status of the consent.
• You will can choose various combination of permissions to access account data:      
  • "Accounts" - Only list of accounts can be retrieved. Balances and transaction details cannot be requested.
  • "Accounts", "Balances" - You can only request accounts and balances details for requested accounts.
  • "Accounts", "Transactions" - You can request list of accounts and transaction details for requested accounts.
  • "Accounts", "Balances", "Transactions" -You can request list of accounts, balances and transaction details for requested accounts. 
  • If there's no permissions provided in request, by default "Accounts", "Balances", "Transactions" permission will be used.
• If "OwnerName" indicator set to "true" in consents request, you can receive actual owner name (if supported and provided by the mock bank) in the response of GET /accounts API.
• "TransactionFromDateTime" and "TransactionToDateTime" can be provided in POST /consents request, so that you could access a list of transactions within a specific time period only.
• Currently below fields are being ignored in POST /consents request in the sandbox environment but supported in live environment:
  • ValidUntilDate,
  • FrequencyPerDay,
  • RecurringIndicatior,
  • CombinedServiceIndicator,
  • PreferredScaMethod
• If GET /consents/status endpoint has been called before user provides their approval, you will receive consent status = "Open" from the mock bank in response.

Step - 3 : Authorise or reject the consent

• With the redirect link received in response of POST /consents, the account holder is redirected to the login page of mock bank. 
• On this login page, the account holder can provide dummy (any) credential details as the log in page is for example purpose only.
• Once the account holder provides their dummy credentials, they are redirected to a page with "Approve" & "Deny" buttons to authorise or reject the data access.
• Once the account holder clicks on Approve or Deny button, the consent is created with an appropriate status and the account holder is redirected back to your software.
• Remark : Mock bank pages were created for the testing purpose only. The actual implementation depends on bank's PSD2 implementation.

Step - 4 : Get consent status

• Call the GET /consents/status API to get the latest consent status from the mock bank.
• If consent is authorised by the account holder, you will receive consent status = "Authorised".
• If consent is denied by the account holder, you will receive consent status = "Rejected" as a final consent status.

Step - 5 : Revoke consent

• If consent status = “Authorised”, call the Delete /consents API endpoint to revoke the consent.

Step - 6 : Get consent status

• Call the GET /consents/status API to get the latest consent status from the mock bank.
• If consent is revoked successfully, you will receive consent status = "Revoked".

Sequence Diagram

If the banks supports paginated response but the number of transactions is considered too high or if the bank provides the response in CAMT format, it might be possible that the GET transactions response contains a download link only.

Using the link you can download the list of transactions in JSON format. If the bank provides the transactions in a non-JSON format, the transactions are converted to JSON by Worldline.

Processing flow for this scenario is similar to described in “Redirect flow with Date filter only” section with addition of GET /download/transactions API.

Account holder's (PSU) consent is needed to access their bank accounts details. In the Redirect Authorisation approach, the browser session of the account holder is redirected from your software / Worldline Bank Selection Interface to mock bank. In that case the mock bank provides all the pages required for authentication (usually username, password). After that the account holder is redirected to Worldline Open Banking Service and from there back to your software.

Take the following steps to complete this scenario.

Step - 1 : Get the list of connected banks

• Call Reach API (GET /aspsp) to obtain a list of supported banks. 
• Check API response of a record with ASPSP ID = "20102" and Name = "Account information redirect + Download transactions".
• Details and Options section provide a list of API endpoints  and mandatory fields that need to be used for successful account data request towards the mock bank using redirect mode of authorisation .
• Remark: Details of reach information provided in the sandbox environment are limited and for informational purpose to give you an idea about how reach information looks like. 

Step - 2 : Initiate consent

• Call the POST /consents API to obtain account holder's consent. 
• In response of POST /consents, you will receive consent ID, a redirect link to authorise the consent and a link to call GET /consent/status API to get the status of the consent.
• You will can choose various combination of permissions to access account data:      
  • "Accounts" - Only list of accounts can be retrieved. Balances and transaction details cannot be requested.
  • "Accounts", "Balances" - You can only request accounts and balances details for requested accounts.
  • "Accounts", "Transactions" - You can request list of accounts and transaction details for requested accounts.
  • "Accounts", "Balances", "Transactions" -You can request list of accounts, balances and transaction details for requested accounts. 
  • If there's no permissions provided in request, by default "Accounts", "Balances", "Transactions" permission will be used.
• If "OwnerName" indicator set to "true" in consents request, you can receive actual owner name (if supported and provided by the mock bank) in the response of GET /accounts API.
• "TransactionFromDateTime" and "TransactionToDateTime" can be provided in POST /consents request, so that you could access a list of transactions within a specific time period only.
• Currently below fields are being ignored in POST /consents request in the sandbox environment but supported in live environment:
  • ValidUntilDate,
  • FrequencyPerDay,
  • RecurringIndicatior,
  • CombinedServiceIndicator,
  • PreferredScaMethod
• If GET /consents/status endpoint has been called before user provides their approval, you will receive consent status = "Open" from the mock bank in response.

Step - 3 : Authorise or reject the consent

• With the redirect link received in response of POST /consents, the account holder is redirected to the login page of mock bank. 
• On this login page, the account holder can provide dummy (any) credential details as the log in page is for example purpose only.
• Once the account holder provides their dummy credentials, they are redirected to a page with "Approve" & "Deny" buttons to authorise or reject the data access.
• Once the account holder clicks on Approve or Deny button, the consent is created with an appropriate status and the account holder is redirected back to your software.
• Remark : Mock bank pages were created for the testing purpose only. The actual implementation depends on bank's PSD2 implementation.

Step - 4 : Get consent status

• Call the GET /consents/status API to get the latest consent status from the mock bank.
• If consent is authorised by the account holder, you will receive consent status = "Authorised".
• If consent is denied by the account holder, you will receive consent status = "Rejected" as a final consent status.

Step - 5 : Get list of accounts

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

Step - 6 : Get transaction details

• Call the GET /transactions API to retrieve transactions details of respective account. 
• In response, you will receive GET /download/transactions API link.

Step - 7 : Download transactions

• Call the GET /download/transactions API link  and  receive the list of transactions in JSON format.

Sequence Diagram

This scenario is similar to the first testing scenario with a slight difference, that the returned transactions are filtered using both date and time parameters ("dateFrom" & "dateTo" query parameters) as we want to bring to your attention that some banks provide requested transaction data based on date & time.

Take the following steps to complete this scenario.

Step - 1 : Get the list of connected banks

• Call Reach API (GET /aspsp) to obtain a list of supported banks. 
• Check API response of a record with ASPSP ID = "20116" and Name = "Account Information redirect + Transaction datetime filter".
• Details and Options section provide a list of API endpoints  and mandatory fields that need to be used for successful account data request towards the mock bank using redirect mode of authorisation .
• Remark: Details of reach information provided in the sandbox environment are limited and for informational purpose to give you an idea about how reach information looks like. 

Step - 2 : Initiate consent 

• Call the POST /consents API to obtain account holder's consent. 
• In response of POST /consents, you will receive consent ID, a redirect link to authorise the consent and a link to call GET /consent/status API to get the status of the consent.
• You will can choose various combination of permissions to access account data:      
  • "Accounts" - Only list of accounts can be retrieved. Balances and transaction details cannot be requested.
  • "Accounts", "Balances" - You can only request accounts and balances details for requested accounts.
  • "Accounts", "Transactions" - You can request list of accounts and transaction details for requested accounts.
  • "Accounts", "Balances", "Transactions" -You can request list of accounts, balances and transaction details for requested accounts. 
  • If there's no permissions provided in request, by default "Accounts", "Balances", "Transactions" permission will be used.
• If "OwnerName" indicator set to "true" in consents request, you can receive actual owner name (if supported and provided by the mock bank) in the response of GET /accounts API.
• "TransactionFromDateTime" and "TransactionToDateTime" can be provided in POST /consents request, so that you could access a list of transactions within a specific time period only.
• Currently below fields are being ignored in POST /consents request in the sandbox environment but supported in live environment:
  • ValidUntilDate,
  • FrequencyPerDay,
  • RecurringIndicatior,
  • CombinedServiceIndicator,
  • PreferredScaMethod
• If GET /consents/status endpoint has been called before user provides their approval, you will receive consent status = "Open" from the mock bank in response.

Step - 3 : Authorise or reject the consent 

• With the redirect link received in response of POST /consents, the account holder is redirected to the login page of mock bank. 
• On this login page, the account holder can provide dummy (any) credential details as the log in page is for example purpose only.
• Once the account holder provides their dummy credentials, they are redirected to a page with "Approve" & "Deny" buttons to authorise or reject the data access.
• Once the account holder clicks on Approve or Deny button, the consent is created with an appropriate status and the account holder is redirected back to your software.
• Remark : Mock bank pages were created for the testing purpose only. The actual implementation depends on bank's PSD2 implementation.

Step - 4 : Get consent status

• Call the GET /consents/status API to get the latest consent status from the mock bank.
• If consent is authorised by the account holder, you will receive consent status = "Authorised".
• If consent is denied by the account holder, you will receive consent status = "Rejected" as a final consent status.

Step - 5 : Get list of accounts

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

Step - 6 : Get balances details

• Once you obtain a list of accounts, call GET /balances API to get the balance details of respective account.

Step - 7 : Get transaction details

• Call the GET /transactions API to retrieve transactions details of respective account. 
• In sandbox environment you can try out the below functionalities of GET /transactions API:
  • Get transaction data for specific date range using "dateFrom" & "dateTo" query parameters. Transaction data is returned based on date with time as this might also happen in the live environment. 
• If the mock bank responds with large number of transactions, you may receive a paginated transactions response.
• In case of paginated response, you can retrieve appropriate transaction page using "first", "next", "previous", "last", "self" links provided in the response.

Sequence Diagram

  Account holder's (PSU) consent is needed to access their bank accounts details. In the Redirect Authorisation approach, the browser session of the account holder is redirected from your software / Worldline Bank Selection Interface to mock bank. In that case the mock bank provides all the pages required for authentication (usually username, password). After that the account holder is redirected to Worldline Open Banking Service and from there back to your software.

Take the following steps to complete this scenario.

Step - 1 : Get the list of connected banks

• Call Reach API (GET /aspsp) to obtain a list of supported banks. 
• Check API response of a record with ASPSP ID = "20101" and Name = "Account Information redirect + Transaction Date filter".
• Details and Options section provide a list of API endpoints  and mandatory fields that need to be used for successful account data request towards the mock bank using redirect mode of authorisation .
• Remark: Details of reach information provided in the sandbox environment are limited and for informational purpose to give you an idea about how reach information looks like. 

Step - 2 : Initiate consent

• Call the POST /consents API to obtain account holder's consent. 
• In response of POST /consents, you will receive consent ID, a redirect link to authorise the consent and a link to call GET /consent/status API to get the status of the consent.
• You will can choose various combination of permissions to access account data:      
  • "Accounts" - Only list of accounts can be retrieved. Balances and transaction details cannot be requested.
  • "Accounts", "Balances" - You can only request accounts and balances details for requested accounts.
  • "Accounts", "Transactions" - You can request list of accounts and transaction details for requested accounts.
  • "Accounts", "Balances", "Transactions" -You can request list of accounts, balances and transaction details for requested accounts. 
  • If there's no permissions provided in request, by default "Accounts", "Balances", "Transactions" permission will be used.
• If "OwnerName" indicator set to "true" in consents request, you can receive actual owner name (if supported and provided by the mock bank) in the response of GET /accounts API.
• "TransactionFromDateTime" and "TransactionToDateTime" can be provided in POST /consents request, so that you could access a list of transactions within a specific time period only.
• Currently below fields are being ignored in POST /consents request in the sandbox environment but supported in live environment:
  • ValidUntilDate,
  • FrequencyPerDay,
  • RecurringIndicatior,
  • CombinedServiceIndicator,
  • PreferredScaMethod
• If GET /consents/status endpoint has been called before user provides their approval, you will receive consent status = "Open" from the mock bank in response.

Step - 3 : Authorise or reject the consent

• With the redirect link received in response of POST /consents, the account holder is redirected to the login page of mock bank. 
• On this login page, the account holder can provide dummy (any) credential details as the log in page is for example purpose only.
• Once the account holder provides their dummy credentials, they are redirected to a page with "Approve" & "Deny" buttons to authorise or reject the data access.
• Once the account holder clicks on Approve or Deny button, the consent is created with an appropriate status and the account holder is redirected back to your software.
• Remark : Mock bank pages were created for the testing purpose only. The actual implementation depends on bank's PSD2 implementation.

Step - 4 : Get consent status

• Call the GET /consents/status API to get the latest consent status from the mock bank.
• If consent is authorised by the account holder, you will receive consent status = "Authorised".
• If consent is denied by the account holder, you will receive consent status = "Rejected" as a final consent status.

Step - 5 : Get list of accounts

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

Step - 6 : Get balances details

• Once you obtain a list of accounts, call GET /balances API to get the balance details of respective account.

Step - 7 : Get transaction details

• Call the GET /transactions API to retrieve transactions details of respective account. 
• In sandbox environment you can try out the below functionalities of GET /transactions API:
  • Get transaction data for specific date range using "dateFrom" & "dateTo" query parameters. Transaction data is returned based on date without time as this might also happen in the live environment. 
• If the mock bank responds with large number of transactions, you may receive a paginated transactions response.
• In case of paginated response, you can retrieve appropriate transaction page using "first", "next", "previous", "last", "self" links provided in the response.

Sequence Diagram

Below you'll find a list of account data testing scenarios. Each scenario has a separate page including 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:

• either on the API reference page (only for registered users, look for the 'try' button) or
• with a tool like Postman

Consent scope

Account data is only provided with the consent of the account holder.  Consent can be given according to three permission groups where a combination of the 3 groups is possible:

• Accounts
• Balances
• Transactions 

The consent can be granted to all accounts or to specific accounts depending whether account holder's bank supports the detailed consent.

POST Consents

Endpoint: POST /psus/{psuId}/consents

Base URL: /xs2a/routingservice/services/ob/ais/v3

This endpoint is used to set up a consent for an account holder for a specific bank. Depending on the bank's API the possible combinations of permissions and account references differ.  Use Permissions body parameter to specify what information you wish to obtain (accounts and / or balances and / or transactions). In case it was not provided, the default (access to all) is used.

In case recurring consent is needed, you should use the body parameter ‘RecurringIndicator’ = True. The default behavior is to request a recurring consent valid for 180 days unless the ValidUntilDate is provided.

Supported consent flows will be determined by the Links section of the response.

Data model

Request (click to enlarge)	Response (click to enlarge)

Multi-level SCA

We support the Multi-Level SCA. In this case consent has to be authorized by multiple account holders. There are no specific endpoints defined for this. The single authorizations have to be started explicitly by the POST Authorization endpoint for each single account holder.

The Reach Directory API allows to retrieve a list of all connected banks and their details such as bank's name and bank's id. It is sufficient to refresh the list of banks once a day. For each bank we provide additional information on their PSD2 implementation, which you need to take into account while implementing consent management and data retrieval. The additional information is split into 2 parts - 'Details' and 'Options'.

Once you retrieve the list of supported banks, you will present it to the user either through the screens you have built or through Worldline Bank Selection interface. Once user bank is selected, you will need to check in Reach API response whether the selected bank requires pre-authentication or you can initiate the consent straight away.

GET ASPSPs

Endpoint: GET /aspsps

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

This endpoint is used to retrieve the reach directory.

Data model

Request	Response (click to enlarge)

Example

Request

curl -X GET "https://xs2a.awltest.de/xs2a/routingservice/services/directory/v3/aspsps?allDetails=true&allOptions=true&allAspspSpecificFields=true" 
-H "accept: application/json" 
-H "X-Request-ID: abcdef2e-3000-4000-88cc-ae40e3b113d7" 
-H "MessageCreateDateTime: 2023-09-25T08:15:00.856Z" 
-H "Service: AIS" 
-H "Authorization: Bearer dc9833a74c712d8c7a50476e71768a1f"

Response body

{
  "Service": "AIS",
  "Groups": [],
  "ASPSP": [
    {
      "AspspId": "20101",
      "Name": [
        {
          "Label": "Account information redirect + Transaction date filter",
          "Language": "en"
        }
      ],
      "Country": "XX",
      "CategoryLabel": [
        "Retail"
      ],
      "Details": [
        {
          "Api": "POST /psus/{psuId}/aspsps/{aspspId}/consents/{consentId}/identification",
          "Fieldname": "preferredScaMethod",
          "Type": "SUPPORTED",
          "Value": "REDIRECT",
          "ProtocolVersion": "BG_V_1_3_6"
        }
      ],
      "Options": [],
      "BIC": "XXAIS001"
    },
    {
      "AspspId": "20116",
      "Name": [
        {
          "Label": "Account information redirect + Transaction datetime filter",
          "Language": "en"
        }
      ],
      "Country": "XX",
      "CategoryLabel": [],
      "Details": [
        {
          "Api": "POST /psus/{psuId}/aspsps/{aspspId}/consents/{consentId}/identification",
          "Fieldname": "preferredScaMethod",
          "Type": "SUPPORTED",
          "Value": "REDIRECT",
          "ProtocolVersion": "STET_V_1_4_2_1_7"
        }
      ],
      "Options": [],
      "BIC": "XXAIS001"
    },
    {
      "AspspId": "20102",
      "Name": [
        {
          "Label": "Account information redirect + Download transactions",
          "Language": "en"
        }
      ],
      "Country": "FR",
      "CategoryLabel": [
        "Retail"
      ],
      "Details": [
        {
          "Api": "POST /psus/{psuId}/aspsps/{aspspId}/consents/{consentId}/identification",
          "Fieldname": "preferredScaMethod",
          "Type": "SUPPORTED",
          "Value": "REDIRECT",
          "ProtocolVersion": "BG_V_1_3_6"
        }
      ],
      "Options": [],
      "BIC": "XXAIS001"
    }
  ]
}

Response - Details section

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

• Api - information on specific endpoints supported or not supported by the bank.
• FieldName - name of a header or a body field.
• Type - restriction of the API endpoint or API field.
• Value - list of supported field values separated by ‘|’.
• ProtocolVersion -  API version used by the bank. Can be ignored.

If there is no FieldName, the Type describes whether this endpoint is available (SUPPORTED) or not (UNSUPPORTED):

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:

Example 1 - Api without FieldName 

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

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

Example 2 - Api combined with FieldName

The example below indicates that from the 'preferredScaMethod' enumeration only the value 'REDIRECT' can be used.

"Api": "POST /psus/{psuId}/aspsps/{aspspId}/consents",
"Fieldname": "preferredScaMethod",
"Type": "SUPPORTED",
"Value": "REDIRECT",
"ProtocolVersion": "STET_V_1_4_2_1_7"

Response - Options section

The Options section provides information regarding the way of using API endpoints for specific bank similar to the Details section. But the information given here is not that specifically related a single API endpoint. It is more to be seen as a parameter for the bank.

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:

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

In this case for the given bank 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: