The Open Banking API offered by CIC Banque Privée 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 CIC Banque Privée;
- 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 theBearer
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 CIC Banque Privée 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 aGET
request on the appropriate URL); - The
x5u
field given by the client when registering;
- The
- 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 JWKx5u
can be used as thekeyId
member in the HTTP signature;
- Either the JWK
- Make an ordered list of HTTP headers that will be sent and signed
(including
(request-target)
) - this will be set in theheaders
member of the HTTP Signature; - Set
rsa-sha256
as thealgorithm
(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);
- for
- Hash the signature string (with
rsa-sha256
, use SHA2-256), and sign the hash using the private key and the selected algorithm (withrsa-sha256
, this will be an RSA digest, with PKCS#1 v1.5 encoding), and put the base64 encoding of the resulting digest in thesignature
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:
Known issues
Resolved: Payment Initiation APIs outside SEPA
Initiation of wire transfers outside SEPA is supported as of February 8th, 2021, in API v2.x.