A Beginner’s Guide to the bunq API

This tutorial is a quick and simple guide to the public bunq API. It focuses on the fundamental REST routes and basic endpoint interaction.

In this tutorial, we’re going to do the following:

1. Create an API-key for the Sandbox environment;
2. Initiate a payment request;
3. Make a SEPA transfer;
4. Use Postman to interact with the bunq API.

Who is this tutorial for? 🤷🏻‍♂️

You should have a basic understanding of RESTful APIs and HTTP requests.

What do we need?

• Postman
• The bunq API Postman collection 💪🏻

Setting up

1. First of all, download and install Postman on your machine.
2. Download the bunq Postman collection via GitHub.

Download the bunq API Postman collection.

3. Unpack the ZIP-file on your computer. You will see a “postman-master” folder 📂containing the JSON-project files for Postman.

4. Run the Postman application.

You can choose “Skip signing in and take me straight to the app” at the very bottom. Registration or login is not required because the project does not use the Postman cloud features.

4a. Next, you can skip the new project screen ⏭

Adding the collection to a Postman workspace

1. Click on “Import” to import the project files to the Postman “Collections” panel.

Import the project files as a new collection.

2. Drag-and-drop the unpacked “postman-master” folder, or just click on “Choose Folder” in the “Import Folder” tab.

Import the “postman-master”-folder.

Once you import the folder, it appears on the “Collections” panel.
It contains all the requests you need to create a new Sandbox user (and API-key 🔑), installation, device, and session. The collection also contains some basic sample requests like “Get monetary accounts”, “Request money” and “Get events”.

bunq API collection

Setting up the connection and interact with the bunq API

Now the real fun begins: we’re going to interact with the API! 🎉
First of all, let’s create a new Sandbox user (and a Sandbox API-key).

1. Select the “bunq Sandbox” environment at the top-right corner.
2. Select the “Create a sandbox user” request on the “Collections” panel.
3. Click on “Send”.

Select the bunq Sandbox environment.

The JSON response contains a new API-key for the Sandbox. This API-key will be automatically saved in the environment (“bunq Sandbox” in our case) as a variable value. You don’t need to write it down 😁

4. Now select the request “Create an installation” and click on “Send”.
It will send a new client public key to the installation endpoint. As a response, you will receive an authentication token, which you will use in all the following requests. This token will also be saved as an environment variable.

5. Register a device by using the “Add the device” request. This will tell the bunq API the name of our client, our API-key, and the allowed IP-addresses to interact from.

Using a wildcard API-key (the asterisk as permitted_ips value) gives you the freedom to make API calls even if the IP-address of the device has changed.

The JSON that will be sent to the device-server endpoint.

6. Create a new session. Select the “Add a session” request and click on “Send”.

This request returns customer information such as name, address, phone number, and language.

The UserPerson object contains customer information.

Did you know?
You can use this phone number or e-mail address to login in the Android Sandbox app in combination with this login code: 000000 (6 times zero).

The auto logout time of the account is used for the session lifetime; the default is set to 1 week. After this, you have to generate a session again. You can change the auto logout time in the Sandbox app via Profile->Security & Settings->Auto Logout.

Getting monetary accounts 💰

To get an overview of your monetary accounts, select the “Get monetary accounts” request and click on “Send”. The response will contain all the aliases for the account, their statuses (for example “ACTIVE”) and, a very important one 😉, the current balance.

A part of the monetary-account response.

Did you know?
There are different types of bunq monetary account objects: MonetaryAccountBank, MonetaryAccountSavings and MonetaryAccountJoint .

Requesting money 💶

The endpoint to send a payment request is request-inquiry :

/user/{user_id}/monetary-account/{monetary_account_id}/request-inquiry

1. Click on the “Request money” request and select the “Body” tab.

Select the Body tab.

In this example, the request will be sent to “sugardaddy@bunq.com”, which is a fake account that will auto-accept all requests up to € 500 (unfortunately only in the Sandbox 😉). You can set the requested amount in the value inside the amount_inquired object.

2. Click on “Send” to post the request. It will return the ID of the new request in the response body.

Did you know?
You can pass the customer’s email address, phone number or IBAN as type (types: EMAIL, PHONE_NUMBER or IBAN) in counterparty_alias .

You can change the value of allow_bunqme to TRUE to generate a request URL (bunq.me), to share via e-mail, WhatsApp, or Telegram.

The ID of the sent request.

Check the status of the sent request ✔

1. First of all, copy (or remember) the ID of the sent request.
2. Duplicate the request (right click on the “Request money” request, then, “Duplicate”).
3. Give the new Postman request a name (e.g. “Get Request status”).
4. Change the method to “GET” and add the ID to the URL.
5. Empty the request body.

The settings

6. Click on “Send”. The response will contain the status of the sent request. In this case, it is “ACCEPTED”.

The status of the request.

Sending money (SEPA transfer) 🚚

In this last example, we’re going to send some money to an IBAN-address (i.e. make a SEPA transfer). The endpoint we’re going to use to send a payment ispayment:

/user/{user_id}/monetary-account/{monetary_account_id}/payment

1. Duplicate the Postman request “Request money”.
2. Change the name of the new request to “Send payment”.
3. Change the endpoint URL.

The Payment endpoint.

4. Specify the JSON body:

{
 "amount": {
  "value": "1",
  "currency": "EUR"
 },
 "counterparty_alias": {
  "type": "IBAN",
  "value": "NL65BUNQ9900000188",
  "name": "Sugar Daddy"
 },
 "description": "Here you go!"
}

In this case, we are sending € 1 to this IBAN: NL65BUNQ9900000188; with “Here you go!” as payment description.

5. Click on “Send”. The API will return the ID of the new Payment in the response.

The Id of the Payment is in the Response JSON.

6. Use the Payment ID to get the status of this payment. It works just like it did with the payment request as described above.

Hopefully, this article helped you to get started with the bunq API. Good luck 👍

In the meanwhile, don’t forget giving this tutorial a clap if you have enjoyed it!😄