Signing
We deprecated the signing of the entire API request (the URL, headers and body). You only need to sign the request body. Requests with full request signatures are no longer validated.
We are legally required to protect our users and their data from malicious attacks and intrusions. That is why we beyond having a secure https connection, we use asymmetric cryptography for signing requests that create a session or payment. The use of signatures ensures the data is coming from the trusted party and was not modified after sending and before receiving.
Request body signing is only mandatory for the following operations:
open a session;
create a payment;
create a scheduled payment;
any other operation that executes a payment such as the following:
accept a draft payment;
accept a draft scheduled payment;
accept a payment request.
You will know that the API call must be encrypted if you get the 466 error code.
The signing mechanism is implemented in our SDKs so if you are using them you don't have to worry about the details described below.
The signatures are created using the SHA256 cryptographic hash function and are included (already encoded in Base64) in the X-Bunq-Client-Signature
request header and the X-Bunq-Server-Signature
response header.
Here is the data you need to sign:
WHERE | DETAILS |
Requests |
|
Responses |
|
For signing requests, the client must use the private key corresponding to the public key that was sent to the server in the installation API call. That public key is what the server will use to verify the signature when it receives the request. In that same call the server will respond with a server side public key, which the client must use to verify the server's signatures. The generated RSA key pair must have key lengths of 2048 bits and adhere to the PKCS #8 standard.
Request signing example
Let's callPOST /v1/user/126/monetary-account/222/payment
. Here is the request:
Let's sign the request.
So for our example above the request to sign will look like this:
Here is how to create a signature in PHP. The signature will be passed by reference into $signature
.
Encode the resulting $signature
using Base64 and add the resulting value under the X-Bunq-Client-Signature
header. It will look something like this: UINaaJELGHekiye4JExGx6TCs2lKMta74oVlZlwVNuVD6xPpH7RS6H58C21MmiQ75
You have signed your request! Send it!
Response verifying example
We sent the request and have received this response with code 200
:
The response will only contain X-Bunq-Client-Request-Id
if you pass it with your request.
We need to verify that this response was sent by the bunq server and not from a man-in-the-middle.
We started to only sign the response body on April 28, 2020. Please make sure you validate our new response signature.
So for our example above the response to sign will look like this:
Here is how you can verify the signature in PHP:
Troubleshooting
If you get this error The request signature is invalid
, please check the following:
Last updated