Reach Directory API

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: