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

Signing requests for PSD2 APIs

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: https://tools.ietf.org/html/draft-cavage-http-signatures-10

  1. The signing certificate
  2. Create the digest
  3. Create the signing string
  4. Sign with your private key
  5. Signature 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 or an empty string if there is no body.
  • 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.
  • Base64encode the output.
  • Add the result to your digest header and make sure that you declare which hashing algorithm you have used.

An example of the digest header for an empty body using SHA-256 or SHA-512:

digest: sha-256=47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=
digest: sha-512=z4PhNX7vuL3xVChQ1m2AB9Yg5AULVxXcg/SpIdNs6c5H0NE8XYXysP+DGNKHfuwvY7kxvUdBeoGlODJ6+SfaPg==

Reference: https://tools.ietf.org/html/rfc3230

 
Known issue: due to security regulation, spaces or line breaks between JSON elements will cause incorrect digest error.

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, 18 Sep 2018 09:51:01 GMT
digest: sha-512=z4PhNX7vuL3xVChQ1m2AB9Yg5AULVxXcg/SpIdNs6c5H0NE8XYXysP+DGNKHfuwvY7kxvUdBeoGlODJ6+SfaPg==
x-request-id: 95126d8f-ae9d-4ac3-ac9e-c357dcd78811

Signing headers per API

Account Information:

  • date
  • digest
  • x-request-id

Confirmation Availability of Funds:

  • date
  • digest
  • x-request-id

Payment Initiation:

  • 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 for ‘HTTP POST request)
  • 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:

y5o7gKxmfA6AT6IvZ5L89uWxhjcw0BPqDlfK6WX1pB5vKtOctzwustjHI6TjdgQMzQL9LAJX6izs5lVCB6Bjl/l3ntCt4rigJPzfTLbnSlxBhLcabru+KyC7pu00NasyMzl4kv/1jtxrBqzSsUvCz87IBSTLSeoPCJc4E5ME82Bdpss67RWcVe94UzLW8jsCqrncLxiMsD6d2ZQmnH/S7Gu9zk8g9eJovmLIaVLn4C5vW7khS63hSZf8qdTEDlMI/L+QgYVgZVIijKosYEnCB9tH5OYWS9cQ1g1NBrMHQASg/ZV8CxHkXizYg7gQoTGaKvSeD7QC172OqySblE1A9Q==

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.
headers

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",signature="y5o7gKxmfA6AT6IvZ5L89uWxhjcw0BPqDlfK6WX1pB5vKtOctzwustjHI6TjdgQMzQL9LAJX6izs5lVCB6Bjl/l3ntCt4rigJPzfTLbnSlxBhLcabru+KyC7pu00NasyMzl4kv/1jtxrBqzSsUvCz87IBSTLSeoPCJc4E5ME82Bdpss67RWcVe94UzLW8jsCqrncLxiMsD6d2ZQmnH/S7Gu9zk8g9eJovmLIaVLn4C5vW7khS63hSZf8qdTEDlMI/L+QgYVgZVIijKosYEnCB9tH5OYWS9cQ1g1NBrMHQASg/ZV8CxHkXizYg7gQoTGaKvSeD7QC172OqySblE1A9Q=="