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 Open Banking Service 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 Open Banking Service, the Open Banking Service 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 Open Banking Service will use a default value. If an unsupported value is used, the Open Banking Service 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 Open Banking Service. If the mentioned FieldName is not filled by the initiating party the Open Banking Service will throw an error. If an unsupported value is used, the Open Banking Service will throw an error. |
| FORBIDDEN | The mentioned FieldName is forbidden. The Open Banking Service 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 Open Banking Service 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 |
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.
Data model
| Request | Response (click to enlarge) |
 |  |
Example: Reach PIS
Request
GET https://xs2a.awltest.de/xs2a/routingservice/services/directory/v2/aspsps?allDetails=true
Authorization: Bearer 4248ce19f27a7df671b29a1816a0ff1f
Accept: application/json
Host: xs2a.ewl.de
Response
HTTP/1.1 200 OK
Cache-Control: no-cache,no-store
MessageCreateDateTime: 2021-03-22T13:51:34.431Z
X-Request-ID: 4aa13498-b3eb-4dbf-b373-a9878b29214d
Pragma: no-cache
Date: Mon, 22 Mar 2021 13:51:34 GMT
Content-Type: application/json;charset=UTF-8
Connection: close
Strict-Transport-Security: max-age=16070400; includeSubDomains
Transfer-Encoding: chunked
{
"Service": "PIS",
"ASPSP": [
{
"AspspId": "1401",
"Name": [ {
"Label": "French example bank",
"Language": "en"
}],
"CountryCode": "FR",
"CategoryLabel": [],
"Details": [
{
"Api": "POST /payments",
"Fieldname": "PaymentProduct",
"Type": "SUPPORTED",
"Value": "Normal",
"ProtocolVersion": "STET_V_1_4_2_1_7"
},
{
"Api": "POST /payments",
"Fieldname": "RemittanceInformation",
"Type": "MANDATORY",
"ProtocolVersion": "STET_V_1_4_2_1_7"
},
{
"Api": "POST /payments/{paymentId}/identification",
"Fieldname": "preferredScaMethod",
"Type": "SUPPORTED",
"Value": "REDIRECT",
"ProtocolVersion": "STET_V_1_4_2_1_7"
}
],
"BIC": "FREBFRPP"
}
]
}