​
Mandatory identification

In accordance with the RTS for SCA & CSC (Regulatory Technical Standards for Strong Customer Authentication and Common and Secure open standards of Communication), Qonto shall rely on QSeal (Qualified electronic Seal) certificates in order to grant Third-Party Providers (TPPs) access to its Business API.

It means that TPPs must identified themselves through their PSD2 QSeal certificates when calling our Business API endpoints; otherwise they will receive a 401 Unauthorized error.

The aim for Qonto is to identify the TPP acceding to the PSU accounts. Technically, the procedure consists of calling the usual endpoints, in which the TPP adds supplementary headers to identify itself. This procedure is based on the STET PSD2 API document.

​
What is PSD2?

PSD2 (Payment Services Directive II) revises the European Union’s legal framework on payment services due to a series of changes caused by technological changes, changing the behaviour of payment service users, increasing cyber threats, and changes due to the evolution of the payment services market.

PSD2 aims to liberalise the payment industry and increase competition, increase the security of payment service users, stimulate innovation, and establish the rights and obligations of payment service providers and payment service users.

​
What is a QSeal certificate?

A Qualified electronic Seal certificate is a qualified digital certificate under the trust services defined in the eIDAS Regulation. A certificate for electronic seals makes it possible for the owner of the certificate to create electronic seals on any data. The digital signature technology guarantees the integrity, and authenticity of the signed/sealed data. This means that the person receiving digitally signed data can be sure who signed the data (the owner of the certificate), that the data was not changed since it was signed, and they can also present this signed data to third parties as an evidence of the same (who signed it, and that it was not changed since). Therefore, digitally signed data can keep its authenticity and integrity over time when appropriately maintained, regardless of how it is stored or transferred. (An electronic seal can be validated by anyone, at any time, to check whether the integrity and authenticity of the data still holds.) The seal provides strong evidence that given data is originated by the legal entity identified in the certificate.

​
Requirements

Each request sent by the TPP has to be signed using http-signature mechanism which is specified by the following IETF draft-paper.

The way it should be implemented is described below.

Both Signature and Digest are required for the request to be considered valid.

​
Add a digest header

Compute a SHA256 digest of the HTTP body and adding this digest as an extra HTTP header. Digest header consists of “SHA-256=” prefix followed by digest value.

Digest header value
echo SHA-256=$(echo -n "<REQUEST_BODY>" | shasum -a 256 | cut -d " " -f 1 | xxd -r -p | base64
# SHA-256=47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=

In case of empty request body, it is required to calculate digest of the empty string.

​
Add a signature header

​
Compute the signature

Compute a SHA256 signature using a specific Qualified Certificate (QSealC), respecting the ETSI/TS119495 Technical Specification, in order to apply a RSA-SHA256 signature on all the following headers (that are present within the HTTP request sent by the TPP):

  • the previously computed Digest (always);
  • Content-Type (always);
  • Content-Length (always);
  • Date (if available);
  • all available PSU- prefixed headers:
  • PSU-IP-Address;
  • PSU-IP-Port;
  • PSU-HTTP-Method;
  • PSU-Date;
  • PSU-User-Agent;
  • PSU-Referer;
  • PSU-Accept;
  • PSU-Accept-Charset;
  • PSU-Accept-Encoding;
  • PSU-Accept-Language;
  • PSU-GEO-Location;
  • PSU-Device-ID.
Headers
Digest: SHA-256=47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=
Date: Fri, 16 Dec 2022 15:01:13 GMT
Content-Type: application/json
Content-Length: 0
PSU-Date: Fri, 16 Dec 2022 15:01:13 GMT

Having these headers as an example, the content that needs to be signed to create the signature should look like this:

Content to be signed
(request-target): get /v2/external_transfers
digest: SHA-256=47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=
date: Fri, 16 Dec 2022 15:01:13 GMT
content-type: application/json
content-length: 0
psu-date: Fri, 16 Dec 2022 15:01:13 GMT

Please note that:

  • Content-Type and Content-Length headers should always be signed when there are present in the request;
  • Special (request-target) value that consists of<request_method> <request_path> is required to be signed along with the headers list.

Please make sure that each key-value pair is in new line and there is no new line after the last key-value pair.

Signature
openssl dgst -sha256 -sign "<PATH_TO_PRIVATE_KEY>" <PATH_TO_THE_CONTENT_TO_BE_SIGNED> | base64
# UNJ7V413xvKj1MnoDYGXRvn6j0UumQUAp+uDBBWwK2+QdnbvSyx9N5OEf2N0+ch4kQ2ZuFtoOl/8GjBv33EqiJvbvkr8ASOapdJ1tDGNRbeh9WXK37/LCe/XdmRmlxsmEaVU2+eY/T2cdQuF8RYwpohxvxA/y/Eiyn2LpZDIi+MA7M4nKfmcnSWnWurVGZqLwWrxA461v1B29Klegp5mEvG5XVjg2LCghhaMwIN9kcZ8ef4/Bzm2dt5XRE+o+DDDqKxMosL7fqH0ko9Kl0aVPUQOkvFQkJYHSXCkToG1QpSQZyDcpquP1C49N3xLZFv6h4C5sXL2WimoT+rRjy1Ung==

​
Add the header

Add the signature within an extra HTTP header embedding:

  • The key identifier (keyId) which must specify the way to get the relevant qualified certificate. It is requested that this identifier is an URL aiming to provide the relevant Qualified Certificate;
  • The algorithm that has been used;
  • The list of headers that have been signed;
  • The signature itself.
Signature header value
keyId="https://qseal_certificate_url",algorithm="rsa-sha256",headers="(request-target) digest date content-type content-length psu-date",signature="UNJ7V413xvKj1MnoDYGXRvn6j0UumQUAp+uDBBWwK2+QdnbvSyx9N5OEf2N0+ch4kQ2ZuFtoOl/8GjBv33EqiJvbvkr8ASOapdJ1tDGNRbeh9WXK37/LCe/XdmRmlxsmEaVU2+eY/T2cdQuF8RYwpohxvxA/y/Eiyn2LpZDIi+MA7M4nKfmcnSWnWurVGZqLwWrxA461v1B29Klegp5mEvG5XVjg2LCghhaMwIN9kcZ8ef4/Bzm2dt5XRE+o+DDDqKxMosL7fqH0ko9Kl0aVPUQOkvFQkJYHSXCkToG1QpSQZyDcpquP1C49N3xLZFv6h4C5sXL2WimoT+rRjy1Ung=="

It is required that the headers list from the signature header are sent in lowercase, like in the example above.