How to connect to the bunq API via HTTPS, SDKs, and Tinker
Tags: API, Open Banking, Banking Technology, Developer, Integration

You will notice that it takes more steps to start with the bunq API than with most applications. The reason for this is that bunq is a bank and so we are legally required to protect our users and their data.

Before you can make your first API call, you need to generate an API key and create an API context, which means following a sequence of 3 steps:

register your API key so all your calls are signed and verified by our server; register your device and IP address(es) so the server knows you send the calls from your device and location; create a session to send API requests signed with the API context.

To make it easier for you to go through this process, we created alternative, easier ways to connect to our API. As a result, there are three ways you could go:

Directly via https: follow the steps described in the documentation. SDK: use one of the SDKs on our GitHub Tinker: run a short command

The first thing you need to do before you can start is generate an API key. Here’s how you can do it depending on the environment you want to work with.

Production: Generate it from the bunq app. Go Profile → Security & Settings → Developers → API keys.

Sandbox:

create it from the sandbox app generate it using Tinker (see the Tinker section below) run a cURL command from the documentation

P.S. The sandbox API key will not work on the production even if you take away the sandbox_ prefix.

And now let’s look at the ways to create an API context.

HTTPS

Once you have an API key to use, you are ready to create an API context.

Trivia: bunq uses the asymmetric cryptography to ensure the communication between the client and the bunq server is secure. The concept is that each party has a pair of keys: a private key and a public key. You, as a party, generate your own pair of 2048-bit RSA keys in the PEM format.

The parties exchange their public keys in the first, installation step of the API context creation flow. All the following requests need to be signed by both you and the server. You’ll need to pass your signature in the X-Bunq-Client-Signature header, and the server will return its signature in the X-Bunq-Server-Signature header.

We know signing is complicated and might be a sticking point, so we encourage you to use our SDKs for signing requests.

And now back to the API context. :-) To create one, follow these 3 steps:

Pass your public key via POST v1/installation → The asymmetric encryption signature is generated. The server passes you its public key and the installation token in return. Use the installation token in the X-Bunq-Client-Authentication header in the two following requests. Call POST v1/device-server to register your device and IP address. → The server registers the data and associates it with your public key. Create a session via POST v1/session-server. → You receive a session token. Include it in the X-Bunq-Client-Authentication header with every API request you send this session.

Trivia: You need to create a separate session for every bunq user. Make sure to start your first session within 60 minutes. Otherwise, the API key will expire and you’ll need to generate a new one. Sessions last up to 1 week by default; however, the auto logout time you set in the application will determine the session expiration.

Starting from the second session, you can directly jump to calling POST v1/session-server signed with the previously created API context. Make sure to send all API calls from the IP address bound to your API key.

SDK

All official bunq SDKs will help you to create an API context and make API calls (create / read / update / delete objects). We currently support the following languages:

There are also amazing SDKs created by our community:

C# bunq SDK started at the bunq hackathon 2.0

JavaScript SDK

PHP SDK that supports sending and getting the status of a bunq iDeal request

You’ll find hundreds of useful prebuilts and SDKs, including ours, yet the easiest way to connect is to use Tinker.

Tinker

Tinker is a sample project we built on top of our SDKs. It showcases the most common uses of the bunq SDKs and is easy to reuse in your integration.

You can run it using one of the commands from our developer page. It will download and open the project in the folder of your choice, and you can start reshaping it right from there. Alternatively, you can find the code on the bunq GitHub page.

The great practical value of Tinker is that it is connected to the sandbox by default and it literally only takes a couple of seconds to switch to the production. All you need to do is scan the “go pro” QR code. You don’t need to take any extra steps to create API keys.

…

Have successfully connected to the bunq API? Share your story! Which ways did you go?