API fallback

Use our fallback solution when our APIs are not available

Introduction

When our APIs are not available or if our APIs do not meet the legally requirements in terms of availability and performance, our fallback solution can be used.

Belfius fallback solution ensures that our customer interfaces are available to you in a secured way.

Using our regulatory fallback interface:

Pre-requisites:

  • Be a registered TPP by being in possession of valid QWAC and QSeal eIDAS certificates.
  • Be on-boarded to use our regulatory interfaces.

Endpoints:

First call with the signature must happen on:

All subsequent calls must happen on the following endpoint (without HTTP-signature):

Mandatory Headers:

Following mandatory headers must be added in each request.

Request-Id

Unique request identifier

Example: 2744ab8e-af9c-4a8d-acf9-692a727e5eff

Client-Id

Client-Id received during TPP onboarding

Example: 4df63778-1295-11ea-8d71-362b9e155667

Date

Current date time in ISO8601 format. We will tolerate a drift of +-3 minutes.

Example: 2018-08-04T12:23:34Z

Digest

Digest of the payload following RFC3230 on instance digests. Possible values are SHA256.

Example:

payload_string = {\"data\":{\"type\":\"sample-token\",\"attributes\":{\"appReference\":\"12345\"}}}"

digest = "SHA256=" + BASE64_ENCODING(SHA256(payload_string)) 

Signature

Signature header based on https://tools.ietf.org/html/draft-cavage-http-signatures-10.
See the detailed description+Example below.


Steps to create the Signature header

Step 1: Create the Date header

As shown above, with drift of +-3 minutes from now

Date: 2018-08-04T12:23:34Z

Step 2: Create the Digest

As shown above

digest = "SHA256=" + BASE64_ENCODE(SHA256(payload_string))

Step 3: Build the (request target) virtual header

In order to build the signature you will need a virtual header named (request-target) (the parentheses are important). The (request-target) is the string concatenation of the HTTP method (in lowercase) with the path and query parameters if there are.

Example:

path = "/sample-path"

method = "post"

request_target = method + " " + path

=> "post /sample-path"

Example: 

path = "/sample-path?a=1&b=2"

method = "post"

request-target = method + " " + path

=> "post /sample-path?a=1&b=2"

Note

path : it is the complete URI invoked by caller, including all query and path parameters.

Sender must make sure that request-target includes the method+SPACE+full URI

Recipient must make sure to consider the method+SPACE+full URI while reconstructing request-target

Step 4: Build the signed headers list

In order to check which headers have been signed and in what order, client has to provide a list of the header names (lowercase and in the same order as used to create the signing string).

List can vary but at You always have to sign AT LEAST the following headers: (request-target), date, request-id, digest.

Example:

headers = "(request-target) " +

"date " +

"digest "+ 

"request-id"

=> "(request-target) date digest request-id"


Note

Header list CAN vary. Client MAY decide to pass more headers in headers list. All those in headers must be used to validate the signature.

Example:

headers = "(request-target) " +

"date " +

"digest "+ 

"request-id "+ 

"authorization " + //client is free to include this header if it decides to do so (for example with access-token case)

=> "(request-target) date digest request-id authorization"

Step 5: Create signing string

The signing string is the concatenation of the signed headers names (in lowercase) and values separated by a 'new line' : \n.

You always have to sign the following headers: (request-target), date, digest, request-id.

Optionally, you can also pass additional headers and include them when signing, e.g. authorization header.

Example: 

signing_string = "(request-target): post /sample-path\n" +

"date: 2018-08-04T12:23:34Z\n" +

"digest: SHA-256=ZVJ9LmCElQs4E6QiWwMUGUqe3c74B6gcXhgj3UIZEUPFkrLoXSGAK2Z2vYN7xKZmOgPEby0xb8RWy5U1eoTGew==\n" +

"request-id": 2323enkjdgdgjd"


=> "(request-target): post /customer-access-tokens\ndate: 2018-03-30T12:22:35Z\ndigest: SHA-256=ZVJ9LmCElQs4E6QiWwMUGUqe3c74B6gcXhgj3UIZEUPFkrLoXSGAK2Z2vYN7xKZmOgPEby0xb8RWy5U1eoTGew==\nrequest-id: 2323enkjdgdgjd"

Example: (when additional headers authorization header  and PSU-IP-Address e.g. are included: This is up to the client to decide if he/she want to include these headers. Just being Mandatory in the request DOES NOT make them a candidate to be present here)

signing_string =

"(request-target): post /sample-path\n" +

"date: 2018-08-04T12:23:34Z\n" +

"digest: SHA-256=ZVJ9LmCElQs4E6QiWwMUGUqe3c74B6gcXhgj3UIZEUPFkrLoXSGAK2Z2vYN7xKZmOgPEby0xb8RWy5U1eoTGew==\n" +

"request-id": 2323enkjdgdgjd\n" +

"authorization: bearer FDDFGDFGDFGDFGDFGFDG\n" +

"psu-ip-address: 10.20.30.456"

=> "(request-target): post /customer-access-tokens\ndate: 2018-03-30T12:22:35Z\ndigest: SHA-256=ZVJ9LmCElQs4E6QiWwMUGUqe3c74B6gcXhgj3UIZEUPFkrLoXSGAK2Z2vYN7xKZmOgPEby0xb8RWy5U1eoTGew==\nrequest-id: 2323enkjdgdgjd\nauthorization : bearer FDDFGDFGDFGDFGDFGFDG\npsu-host-up: 10.20.30.456"

Step 6 : Build the Signature header

This is where the real signing happens. The signature header is a combination of several sub-headers: And all these sub-headers are comma separated (Not space)

  • keyId: This is the identifier of application's certificate, obtained from the Developer Portal. In PSD2 case, It will be a TPP-ID, as we already have a mapping between TPP-ID  and certificate at API-GW. This is compliant with RFC.
  • algorithm: the digital signature algorithm used to generate the signature, matching the signature algorithm used for the application certificate (e.g. rsa) and SHA-256 or SHA-512 as the hashing function; Note that Client can only use the algorithms allowed as per his registered certificate with Belfius. This is due to the fact that while verifying the signature, Belfius will NOT use the algorithm present in this request, but the one obtained from client's certificate, in order to be compliant with RFC Section 2.5, point 2. Example: rsa-sha256
  • headers: The list of HTTP headers created in step 4;
  • signature: the Base64-encoded digital signature of the signing string created in step 5.

Example: 

key_id = "62f02718-eeee-46e1-b5eb-e8fd6e799c2e"//TPP-ID for now, could be unique-application-id  in future.

algorithm = "rsa-sha256"

headers = "(request-target) date digest request-id [OTHER HEADERS]"

signature = BASE64_ENCODE(RSA_SHA256_SIGN(PRIVATE_KEY, SIGNING_STRING_FROM_STEP5))  //MIN SHA_256 RSA Assymetric  

Signature => "keyId=\"" + key_id + "\"," + "algorithm=\"" + algorithm + "\"," + "headers=\"" + headers + "\"," + "signature=\"" + signature + "\""

"keyId=\"62f02718-eeee-46e1-b5eb-e8fd6e799c2e\",algorithm=\"rsa-sha256\",headers=\"(request-target) date digest request-id authorization-header\" ,signature=\"SjWJWbWN7i0wzBvtPl8rbASWz5xQW6mcJmn+ibttBqtifLN7Sazz6m79cNfwwb8DMJ5cou1s7uEGKKCs+FLEEaDV5lp7q25WqS+
lavg7T8hc0GppauB6hbgEKTwblDHYGEtbGmtdHgVCk9SuS13F0hZ8FD0k/5OxEPXe5WozsbM=\""

Functional documentation

The following document explain the different functionalities of our customer interfaces.
Note that the customer interface to be used depends on the client segmentation.

  • Belfius Direct Net is used by
    • retail clients
    • business clients – independent professions and SMEs
  • Belfius Web New Technology is used by corporate clients – public authorities and big enterprises