Open Banking API Endpoints

Open Banking API

PSD2 API Developer Portal Open Banking API

The Open Banking API offered by Beobank is documented in detail in an:

OpenAPI ("Swagger") Specification file:
- View v2.1 Published

This Open Banking API implementation is based on the documents produced by STET.

In order to successfully send API requests, callers must respect a number of requirements:

They must be registered by Beobank;
They must make the call with mutual-TLS, with the appropriate Website Authentication Certificate;
They must have an access token that matches the target endpoint;
They must send a set of HTTP headers that allow the bank to check the request's validity;
They must sign the request with an appropriate Sealing Certificate;

The following sections will discuss the last two requirements, the other requirements have been described on the pages for Registration and OAuth 2 Endpoints.

Necessary and Signed Request Headers

The following headers are necessary, and must be signed:

Host: The standard HTTP header defined in RFC 7230;
Date: The standard HTTP header defined in RFC 7231, it needs to be set to a value that is not too far from the current date/time - otherwise an error will be returned;
X-Request-Id: This header, defined by STET, contains a correlation ID set by the TPP to uniquely identify each request made to the ASPSP API, with an ID that can be understood by both;

These headers must be present, and should not be signed:

Authorization: The HTTP header defined in RFC 7235, with the Bearer HTTP Authorization Scheme defined in RFC 6750, holds the OAuth 2 token previously obtained by the caller;

These headers must be present, and do not need to be signed:

Accept: The standard HTTP header defined in RFC 7231;
User-Agent: The standard HTTP header defined in RFC 7231;

If the request contains a body, the following additional headers are necessary, and must be signed:

Content-Type: The standard HTTP header defined in RFC 7231;
Digest: The HTTP header for instance digests, defined in RFC 3230. It should be noted that the only supported Digest Method is SHA-256, defined in RFC 5843;

The PSU-* family of headers, that allow the TPP to forward PSU device, location and usage information to the ASPSP, are facultative, but must be signed if present. The following headers are defined:

PSU-IP-Address: The IP Address on which the PSU is connected to the TPP;
PSU-IP-Port: The TCP Port of the PSU Terminal on which he is connected to the TPP;
PSU-Date: The timestamp of the relevant PSU action;
PSU-HTTP-Method: HTTP Method for the most relevant PSU's HTTP request to the TPP;
PSU-Accept: Accept HTTP header value for the most relevant PSU's HTTP request to the TPP;
PSU-Accept-Charset: Accept-Charset HTTP header value for the most relevant PSU's HTTP request to the TPP;
PSU-Accept-Encoding: Accept-Encoding HTTP header value for the most relevant PSU's HTTP request to the TPP;
PSU-Accept-Language: Accept-Language HTTP header value for the most relevant PSU's HTTP request to the TPP;
PSU-Referer: Referer HTTP header value for the most relevant PSU's HTTP request to the TPP;
PSU-User-Agent: User-Agent HTTP header value for the most relevant PSU's HTTP request to the TPP;
PSU-GEO-Location: The PSU location as returned by their mobile terminal;
PSU-Device-ID: The PSU Device ID - usually only available on a mobile terminal;

Signature process

The signature process uses the Cavage HTTP Signatures Draft, with the following specificities:

The HTTP Signature data must be in a Signature header;
In addition to the headers mentioned above, (request-target) (which summarizes the HTTP Status Line), must be signed;
The key pair used for signing must be associated to a Qualified Sealing Certificate sent by the TPP to Beobank when the OAuth 2 client was registered. In order to reference which certificate is in use in a given signature, the keyId field in the signature may be set to one of two fields in the registered JWK:
- The kid field generated by the server (which may be checked with a GET request on the appropriate URL);
- The x5u field given by the client when registering;
As the Sealing Certificates are RSA, only the rsa-sha256 algorithm is supported;

The new features from Draft 11 and after of Cavage HTTP Signatures are not supported.

As a reminder, here are the steps for the signature process:

Select a private key that will be used for the signature, determine the keyId - you can check what certificates are registered for a given client by calling the Registration GET endpoint;
- Either the JWK kid or the JWK x5u can be used as the keyId member in the HTTP signature;
Make an ordered list of HTTP headers that will be sent and signed (including (request-target)) - this will be set in the headers member of the HTTP Signature;
Set rsa-sha256 as the algorithm (other algorithms are currently not supported);
Create the signature string, by concatenating, for each header (in the order chosen at step 2):
- The name of the header, in lower case;
- An ASCII colon (:) and an ASCII space;
- The value of the header, without any case modifications;
  - for (request-target), the value is the concatenation of:
    - The HTTP method, lowercased;
    - An ASCII space;
    - The URL Path as it appears in the first line of the HTTP request (with path and query information);
  - for multi-valued headers, the value is the concatenation of all values of that header, in the order they appear in the HTTP message, separated with the sequence (ASCII comma , and ASCII space);
Hash the signature string (with rsa-sha256, use SHA2-256), and sign the hash using the private key and the selected algorithm (with rsa-sha256, this will be an RSA digest, with PKCS#1 v1.5 encoding), and put the base64 encoding of the resulting digest in the signature member of the HTTP Signature;

Actual examples of the signature process can be found in the IETF Draft Specification.

PISP objects lifecyle and status information

The lifecycle and statuses of PISP objects follow the STET API specification v1.4.2:
For Payment Request objects:
For individual Credit Transfer Transaction objects: