Sorry, you need to enable JavaScript to visit this website.

Signing requests for PSD2 Bulk API

To ensure that your request was not tampered with during transit, your application needs to sign it. Below we will explain the steps you need to take to correctly sign the request. You may also want to consult this reference:

  1. The signing certificate
  2. Create the digest
  3. Create the signing string
  4. Sign with your private key
  5. Signature header
  6. Certificate header

1. The signing certificate

Use your (PSD2) eIDAS QSEAL certificate issued by the Qualified Trust Service Provider of your choice. We recommend you to develop your application using the sandbox environment first, where you can use our example certificate if you don't have a real eIDAS certificate yet. In the examples below we have used the same example certificate so you can reproduce the resulting values.

2. Create the digest

The digest is a base64 encoded hash of the body: Base64(SHA512(body))

  • Take the body of your request and include the metadata of the file.
  • Pass the body through the SHA-512 hashing algorithm (SHA-256 is also allowed).
  • Make sure the hashed output is binary. In other words; do not convert it to a string.
  • Base64 encode the output.
  • Add the result to your digest header and make sure that you declare which hashing algorithm you have used.
  • The boundary value will be dynamically generated when doing a HTTP request. This boundary value is mandatory information as part of the metadata.

Example of metadata:

Content-Disposition: form-data; name="xml_sct"; filename="samplefile.xml"
Content-Type: application/xml
<- content of samplefile.xml ->

Download and use the sample XML file below to reproduce the example values in this document.

⤓ SampleFile.xml

An example of the digest header with the examples above using SHA-256 or SHA-512:

digest: sha-256=9SfITFfNaCo5SGdzsFNekyblr2DTOl+SHuaXJwPihRU=
digest: sha-512=CwpW0kD24czZzJkjcqBTZnADBlOUdDxQpH5dhdCPMHZTd1W+HbmUQPbKYpguvgmvZosvSEUI4taIJeujn3Npig==


3. Create the signing string

The signing string contains several headers depending on which API you are using, separated by line breaks. The order is not important as long as you define them in the same order in the signature header.

For example

date: Tue, 15 Dec 2020 10:34:45 GMT
digest: sha-512=CwpW0kD24czZzJkjcqBTZnADBlOUdDxQpH5dhdCPMHZTd1W+HbmUQPbKYpguvgmvZosvSEUI4taIJeujn3Npig==
x-request-id: fb88b462-60cc-48f8-b710-bd1620135d52

Signing headers

  • date
  • digest
  • x-request-id
  • psu-id (optional / if and only if included as a header of the HTTP request)
  • psu-corporate-id (optional / if and only if included as a header of the HTTP request)
  • tpp-redirect-uri (mandatory)
  • tpp-nok-redirect-uri (optional / if and only if included as a header of the HTTP POST request)

4. Sign with your private key

The signature is the signing string signed with the private key: Base64(RSA-SHA512(signing_string))

  • Create the signing string (see step 3).
  • Sign it using RSA-SHA512 (RSA-SHA256 is also allowed) and the private key of the signing certificate.
  • Base64 encode the output.

An example of the signature using the above information:


5. Signature header

The signature header consists of the following components:

component description
keyId The serial number of the certificate as defined in 'TPP-Signing-Certificate' header, the format should be Integer not hex. You can use the openssl command line tool to find the serial number. For example:
$ openssl x509 -in cert.pem -noout -text
algorithm Specify which algorithm was used when generating the signature: rsa-sha512 or rsa-sha256.

The list of headers contained in the signature:

  • lowercase
  • separated by a space
  • in the same order as they have in the signing string
signature The result from step 4.

The resulting signature header for our example:

signature: keyId="1523433508",algorithm="rsa-sha512",headers="date digest x-request-id tpp-redirect-uri",signature="Q+deIM5k+OPvy0+eIdh7ZvRmvB9cu/TW88Ni1C3jfIk2C+y9QkNuKP7olkCNALY5XexTkfYLJlpbcZWkQ0OipT05Mb7LNbbN91bl3bRTjEHIlJ0XCJzORHRlYWpY/HsaKrF8PfuQBM/i6xkbH1eGWaiRxV/lMChsXYRcw9ncVieRMLP1QGfyBKgF/ZbvSuXdjwvcD3BewL7U3O60mL/1BxqJRoXZRlvMPpO34/Tl8XDRccaW7hAA7+X46f57Ath1wqo6PxJZ4CTauAVWeUjJMGaGXcIyviYXWE4wFKZEaTFd28Jq7E5ZhOPrLYRDY+7fajOkQGg7TAeenIKnQ7oT5w=="

6. Certificate header

In order to verify your signature we need you to send us the public certificate in a header. To do so you need to strip the pem certificate from its begin and end tags and remove all linebreaks. The result with our example certificate would be: