The special mission of the custom bunq API headers

Unlike most APIs, the bunq API requires up to 8 headers to be passed along with every request. Moreover, most of them are custom and so have a special purpose. What important mission do the bunq headers carry out? Let’s find out.

bunq request headers help us make a difference

Aside from the standard headers such as Cache-Control and User-Agent, bunq is designed to work with 6 peculiar headers that help us do two things:

1. validate the sender of the request is who they say they are;
2. provide the best personalized user experience possible.

That’s 2 groups and more than 2 headers. Let’s stop by the impact every header has on the work of bunq and see to which out of two groups it belongs and why.

X-Bunq-Language

The bunq API expects you to tell us whether you prefer en_US or nl_NL to respond to your requests in your language of preference. You will, for example, notice that error descriptions are returned in the language you choose in the header — either English or Dutch.

X-Bunq-Region

Information about the country the device is located in helps us to properly localize the messages delivered to the bunq user: they are returned in not only the right language but also in the right format that is specific to the region. For example, this header tells us what currency format to use in relevant messages by default.

X-Bunq-Client-Request-Id

bunq asks you to give each request a unique ID for 2purposes:

1. To log the request properly and find them easily when debugging is needed.
2. To map requests with their responses (responses carry the same X-Bunq-Client-Request-Id).

X-Bunq-Geolocation

When the geolocation from which an operation is made is passed in X-Bunq-Geolocation, bunq maps it with the relevant event. For instance, we link the location of transactions with the payment events the user sees in the bunq app.

X-Bunq-Client-Authentication

The bunq API requires you to pass the authentication token to validate that the request is sent by you, that is, with a valid token that identifies you.

Trivia: You receive an authentication token after doing either of these:

1. … when making an installation. This is the first call you send with a new API key. You only need this authentication token to proceed with the next 2 steps of creating an API context, which ends when you create a session.
2. … when creating a session with either your API key or the access_token you get after your authorization request is accepted by another bunq user.

X-Bunq-Client-Signature

We require you to pass the public key of your key pair for 2 reasons:

1. To prevent any modifications of the data in transit.
2. To ensure the communication between the client and bunq is secure.

Response headers

The response headers of the bunq API mirror the request headers to close the mapping and security loops:

• X-Bunq-Client-Request-Id returns the X-Bunq-Client-Request-Id of the request so we could map the request with its response;
• X-Bunq-Client-Response-Id provides an ID you can use as extra protection against replay attacks;
• and X-Bunq-Server-Signature verifies the response is sent by bunq.

Haven’t experienced the freedom of programmable banking yet? Start in seconds by just running a command! No need to create API keys. 😉

Choose your language:

$ bash >(curl -s https://tinker.bunq.com/php/setup.sh)

$ bash >(curl -s https://tinker.bunq.com/python/setup.sh)

$ bash >(curl -s https://tinker.bunq.com/java/setup.sh)

$ bash >(curl -s https://tinker.bunq.com/csharp/setup.sh)