Register as a TPP
Last updated
Was this helpful?
Last updated
Was this helpful?
This guide will walk you through the steps to register as a Third-Party Provider (TPP) with bunq. If you're a PSD2-certified company, you'll learn how to authenticate with the bunq API, register your certificate, and start using your credentials to access the data and services you're authorized for.
You must generate a 2048-bit RSA key pair beforehand.
You'll need your QSeal certificate (Qualified Seal Certificate), including intermediate and root certificate chain.
OpenSSL and curl installed
Basic knowledge of command line
The easiest way to register is via command line, but you can also implement this in your code.
You can also use one of our ready-to-go SDKs, just check .
These keys are used to register your app installation with bunq:
Replace the subject /CN=.../C=...
with your own details as needed.
This step registers your public key with bunq and returns an installation token.
The client_public_key
is the public part of the key pair you generated earlier using OpenSSL. This key is sent to bunq so we know how to verify future requests from your integration.
What the API expects here is:
A PEM-formatted public key (typically starting with -----BEGIN PUBLIC KEY-----
and ending with -----END PUBLIC KEY-----
)
All line breaks and formatting preserved correctly as a single escaped string (so it fits into the JSON payload)
Here's an example of a formatted public key:
You can call the installation endpoint by using the following command line:
Here is the full specification of the endpoint:
This proves ownership of your PSD2 certificate by signing the public key and token.
Make sure there is NO new line at the end of the file! Otherwise, the signature will be invalid.
Extract the installation_token
from the previous step:
Take the server_public_key
of the installation you also received in the previous step.
Append the token
Sign the string using the private key of your PSD2 certificate
This base64 string should be passed as value of client_public_key_signature
in the next step.
Use your certificate and signature to request your TPP credentials in bunq's API.
Here is the command line code:
You can repeat the same value on the client_payment_service_provider_certificate
and client_payment_service_provider_certificate_chain
in sandbox, but please ensure you have your certificate chain ready when going to production, otherwise the call will fail.
Save the response for the next step:
Here is the full specification of the endpoint:
After creating a credential in the previous step, you'll receive a credential_token
, which acts as a unique secret. This token is required when registering your device using POST /device-server
. Registering the device is an important security step—it lets bunq know where the API calls are coming from and links your setup to a specific environment (like your server or app).
By sending the credential token as the secret
, you're proving that your device is authorized to operate under your PSD2 certificate and credentials. Without this step, bunq can’t associate API activity with a verified, trusted source.
Here's the bash code to extract your credential_token
from the credential.json (saved in the last step):
With that value in hands, you can then call the endpoint POST /device-server
and register your device:
When using a standard API Key the DeviceServer and Installation that are created in this process are bound to the IP address they are created from.
Using a Wildcard API Key gives you the freedom to make API calls from any IP address after the POST device-server. You can switch to a Wildcard API Key by tapping on “Allow All IP Addresses” in your API Key menu inside the bunq app.
You can also programatically switch to a Wildcard API Key by passing your current ip and a *
(asterisk) in the permitted_ips
field of the device-server POST call. E.g: ["1.2.3.4", "*"]
.
Here is the full specification of the endpoint:
In this step, you're preparing to create a session with bunq's API, which requires proving your identity using a digital signature.
Make sure there is NO new line at the end of the file! Otherwise, the signature will be invalid.
Then you'll digitally sign the contents of the request body using your installation private key. This proves to bunq that the request really comes from someone in control of the private key tied to your public key.
After, you'll encode the binary signature into base64 so it can be safely sent in the signature HTTP header from the next step.
If you get an error telling you "The request signature is invalid", please check the following:
There are no redundant characters (extra spaces, trailing line breaks, etc.) in the data to sign.
Make sure the body is appended to the data to sign exactly as you're adding it to the request.
You have added the full body to the data to sign.
You use the data to sign to create a SHA256 hash signature.
You have base64 encoded the SHA256 hash signature before adding it to the request under X-Bunq-Client-Signature
.
The POST /session-server
endpoint is used to start a new session with the bunq API. Once your device is registered and you've created a valid credential, this call creates an authenticated session. The session ensures secure, time-limited access to the bunq API on behalf of your registered device and credentials.
The response will contain a session_token
. Use this token in the X-Bunq-Client-Authentication
header for all subsequent API calls.
Here is the full specification of the endpoint:
You’ve now successfully authenticated with the bunq Public API as a PSD2-certified provider.
Now you're ready to set up the OAuth with your end user and start using the API in accordance with your certified roles (AISP, PISP, or CBPII).
Please refer to this page on how to set up OAuth:
All integration steps must be repeated in the production environment with your real eIDAS certificate when you're ready to go live.
Ready to continue? You can check what you can do with bunq's API according to your role in these pages here:
Need to update your PSD2 certificate? No problem, just repeat this step with the new certificate
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 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.
You can find more info about signing the request body in .
This is the only API call that does not require you to use the "X-Bunq-Client-Authentication" and "X-Bunq-Client-Signature" headers. You provide the server with the public part of the key pair that you are going to use to create the value of the signature header for all future API calls. The server creates an installation for you. Store the Installation Token and ServerPublicKey from the response. This token is used in the "X-Bunq-Client-Authentication" header for the creation of a DeviceServer and SessionServer.
The standard HTTP Cache-Control header is required for all signed requests.
The User-Agent header field should contain information about the user agent originating the request. There are no restrictions on the value of this header.
The X-Bunq-Language header must contain a preferred language indication. The value of this header is formatted as a ISO 639-1 language code plus a ISO 3166-1 alpha-2 country code, separated by an underscore. Currently only the languages en_US and nl_NL are supported. Anything else will default to en_US.
The X-Bunq-Region header must contain the region (country) of the client device. The value of this header is formatted as a ISO 639-1 language code plus a ISO 3166-1 alpha-2 country code, separated by an underscore.
This header must specify an ID with each request that is unique for the logged in user. There are no restrictions for the format of this ID. However, the server will respond with an error when the same ID is used again on the same DeviceServer.
This header must specify the geolocation of the device. The format of this value is longitude latitude altitude radius country. The country is expected to be formatted of an ISO 3166-1 alpha-2 country code. When no geolocation is available or known the header must still be included but can be zero valued.
The authentication token is used to authenticate the source of the API call. It is required by all API calls except for POST /v1/installation. It is important to note that the device and session calls are using the token from the response of the installation call, while all the other calls use the token from the response of the session-server call
Your public key. This is the public part of the key pair that you are going to use to create value of the "X-Bunq-Client-Signature" header for all future API calls.
Register a Payment Service Provider and provide credentials
The standard HTTP Cache-Control header is required for all signed requests.
The User-Agent header field should contain information about the user agent originating the request. There are no restrictions on the value of this header.
The X-Bunq-Language header must contain a preferred language indication. The value of this header is formatted as a ISO 639-1 language code plus a ISO 3166-1 alpha-2 country code, separated by an underscore. Currently only the languages en_US and nl_NL are supported. Anything else will default to en_US.
The X-Bunq-Region header must contain the region (country) of the client device. The value of this header is formatted as a ISO 639-1 language code plus a ISO 3166-1 alpha-2 country code, separated by an underscore.
This header must specify an ID with each request that is unique for the logged in user. There are no restrictions for the format of this ID. However, the server will respond with an error when the same ID is used again on the same DeviceServer.
This header must specify the geolocation of the device. The format of this value is longitude latitude altitude radius country. The country is expected to be formatted of an ISO 3166-1 alpha-2 country code. When no geolocation is available or known the header must still be included but can be zero valued.
The authentication token is used to authenticate the source of the API call. It is required by all API calls except for POST /v1/installation. It is important to note that the device and session calls are using the token from the response of the installation call, while all the other calls use the token from the response of the session-server call
Payment Services Directive 2 compatible QSEAL certificate
Intermediate and root certificate belonging to the provided certificate.
The Base64 encoded signature of the public key provided during installation and with the installation token appended as a nonce. Signed with the private key belonging to the QSEAL certificate.
Create a new DeviceServer providing the installation token in the header and signing the request with the private part of the key you used to create the installation. The API Key that you are using will be bound to the IP address of the DeviceServer which you have created.Using a Wildcard API Key gives you the freedom to make API calls even if the IP address has changed after the POST device-server.Find out more at this link https:/bunq.com/en/apikey-dynamic-ip.
The standard HTTP Cache-Control header is required for all signed requests.
The User-Agent header field should contain information about the user agent originating the request. There are no restrictions on the value of this header.
The X-Bunq-Language header must contain a preferred language indication. The value of this header is formatted as a ISO 639-1 language code plus a ISO 3166-1 alpha-2 country code, separated by an underscore. Currently only the languages en_US and nl_NL are supported. Anything else will default to en_US.
The X-Bunq-Region header must contain the region (country) of the client device. The value of this header is formatted as a ISO 639-1 language code plus a ISO 3166-1 alpha-2 country code, separated by an underscore.
This header must specify an ID with each request that is unique for the logged in user. There are no restrictions for the format of this ID. However, the server will respond with an error when the same ID is used again on the same DeviceServer.
This header must specify the geolocation of the device. The format of this value is longitude latitude altitude radius country. The country is expected to be formatted of an ISO 3166-1 alpha-2 country code. When no geolocation is available or known the header must still be included but can be zero valued.
The authentication token is used to authenticate the source of the API call. It is required by all API calls except for POST /v1/installation. It is important to note that the device and session calls are using the token from the response of the installation call, while all the other calls use the token from the response of the session-server call
The description of the DeviceServer. This is only for your own reference when reading the DeviceServer again.
The API key. You can request an API key in the bunq app.
An array of IPs (v4 or v6) this DeviceServer will be able to do calls from. These will be linked to the API key.
Create a new session for a DeviceServer. Provide the Installation token in the "X-Bunq-Client-Authentication" header. And don't forget to create the "X-Bunq-Client-Signature" header. The response contains a Session token that should be used for as the "X-Bunq-Client-Authentication" header for all future API calls. The ip address making this call needs to match the ip address bound to your API key.
The standard HTTP Cache-Control header is required for all signed requests.
The User-Agent header field should contain information about the user agent originating the request. There are no restrictions on the value of this header.
The X-Bunq-Language header must contain a preferred language indication. The value of this header is formatted as a ISO 639-1 language code plus a ISO 3166-1 alpha-2 country code, separated by an underscore. Currently only the languages en_US and nl_NL are supported. Anything else will default to en_US.
The X-Bunq-Region header must contain the region (country) of the client device. The value of this header is formatted as a ISO 639-1 language code plus a ISO 3166-1 alpha-2 country code, separated by an underscore.
This header must specify an ID with each request that is unique for the logged in user. There are no restrictions for the format of this ID. However, the server will respond with an error when the same ID is used again on the same DeviceServer.
This header must specify the geolocation of the device. The format of this value is longitude latitude altitude radius country. The country is expected to be formatted of an ISO 3166-1 alpha-2 country code. When no geolocation is available or known the header must still be included but can be zero valued.
The authentication token is used to authenticate the source of the API call. It is required by all API calls except for POST /v1/installation. It is important to note that the device and session calls are using the token from the response of the installation call, while all the other calls use the token from the response of the session-server call
The API key of the user you want to login. If your API key has not been used before, it will be bound to the ip address of this DeviceServer.