Repository files navigation

Hi! Thanks for checking out our API! It’s an incredibly powerful tool for you to automate your banking any way you like! We offer over 200 operations you can make use of.

Because our API is so powerful, it can be overwhelming when you work with it for the first time. This article is meant to help you understand how bunq works so you can easily find the right endpoints and build your integration as fast as possible.

Let’s start by looking into the objects you can work with using the bunq API and the relations between them.

No matter what integration you want to build, you will need to work with the core objects that are essential to the bunq user experience. While the concept of each is easy to understand, you’ll see that some names and relations are not what you would expect, which is because the Public bunq API is a part of our internal API, which serves the bunq app.

Without further ado, here are the objects you’ll need to know by ID:

• User
• MonetaryAccount
• Payment
• RequestInquiry
• Card
• Attachment
• NoteAttachment

Let’s dive into the peculiarities of each of them.

As a bank, we believe in user-centred design, and so we organized everything, including our app, service, and backend, aroundUsers. You’ll notice that and every endpoint path starts with it. We support 3 user types, which have separate endpoints, permissions and properties:

• userPerson is accessible at/user-person;
• userCompany is accessible at/user-company;
• userPaymentServiceProvider is readable at/user-payment-service-provider.

User operates as a generalization object over all the possible user types.

userPerson anduserCompany represent bunq users withsubscriptions. As a bunq user, you will find yourself one of them. Getting youruserId (GET /user) will be one of the first things you will do after you open your first session, as you need it to retrieve information from and perform operations with the user account.

Users with bunq subscriptions have access to the core banking services. They can create bank accounts (we call them monetary accounts), order cards, and make payments. All of them have subtypes and work with one another, which you will learn about in the following sections.

AuserPaymentServiceProvider is created when a PSD2-certified company registers theireIDAS certificate to bunq. In return, if the certificate is validated, they receive an API key. These bunq users do not have access to the bunq app and can only operate on behalf of other bunq users within the scope of their PSD2 role - AISP, PISP, and/or CBPII.

The second object you will use the most isMonetaryAccount. Monetary accounts are holders of money you may know as bank accounts, sub-accounts, or pots. Unlike wallets, which work directly with cards, monetary accounts are linked to a legal bank account owner.

You might have correctly guessed that Travel users (UserPersons with the Travel subscription) do not own abank account and so the monetary account they use with a card serves as a wallet.

Most operations including payments work with monetary accounts so you will need to specifymonetary-accountId for the majority of your API calls. You can find the ID of the monetary accounts as well as identify the one you want to use by listing all the monetary accounts of the user (GET /user/userId/monetary-account).

bunq offers 3 types of monetary accounts, which, just likeusers, have dedicated endpoints that serve as filters for your convenience:

• Classic single bank accounts orMonetaryAccountBanks are accessible at/user/userId/monetary-account-bank;
• (Auto-)savings accounts orMonetaryAccountSavingss are accessible at/user/userId/monetary-account-savings;
• Accounts shared with other bunq users (these users become fellow legal owners of the monetary account) orMonetaryAccountJoints are accessible at/user/userId/monetary-account-joint.

VAT accounts fall underMonetaryAccountSavingss.

Because the money is stored in monetary accounts, all transactions derive from or target them.Payment covers both incoming and outgoing payments so if you list the payments of the user, you will get all of them.

While it’s impossible tocontrol incoming payments, you can do so with the outgoing ones. Using the bunq API, you can create single, batch, draft and scheduled payments. All of them operate under the parentPayment object while having dedicated objects and endpoints:

• single payments orPayment are accessible at/user/{userID}/monetary-account/{monetary-accountID}/payment;
• an array of payments to be sent at once orPaymentBatchs are accessible at/user/{userID}/monetary-account/{monetary-accountID}/payment-batch;
• initiated payments that the user needs to accept orDraftPayments are accessible at/user/{userID}/monetary-account/{monetary-accountID}/draft-payment;
• scheduled payments orSchedulePayments are accessible at/user/{userID}/monetary-account/{monetary-accountID}/schedule-payment;

An array of scheduled payments orSchedulePaymentBatchs are accessible at/user/{userID}/monetary-account/{monetary-accountID}/schedule-payment-batch.

Draft scheduled payments or initiated recurring payments fall underDraftPayment. Moving the money between monetary accounts can be covered by any depending on what UX you want to achieve.

Aside from the sum to be sent, all payments require a receiver, which we callcounterparty_alias. You can specify the addressee using the following pointer types:EMAIL,PHONE_NUMBER, orIBAN.

For worldwide and multi-currency payments, use our TransferWise endpoints. Followthis tutorial for the details.

With bunq, you can request payments from anyone - you just need to know their IBAN, email, or phone number. Non-bunq users will receive an email or an SMS leading to an interface where they can make the transaction from their bank account.

RequestInquiry is the magical object that makes the above possible. Just like payments, it links to a monetary account of a user, which you can see in the endpoint you can use to create and accessRequestInquirys:/user/{userID}/monetary-account/{monetary-accountID}/request-inquiry.

Just as cards belong to a bunq user, so isCard directly linked toUser. Money needs to run into and out of monetary accounts so every card a bunq user possesses needs to be linked to one. There is no limit for how many cards can take money from a monetary account but a card can only have one primary monetary account. If the primary monetary account lacks sufficient funds, bunq checks the secondary monetary account. Else, the transaction fails.

Together with their PINs, cards ensure the 2-factor authentication of the user when the user makes a card payment. Such payments end up asPayments and so will be returned when listing the payments of the user (GET /user/{userID}/monetary-account/{monetary-accountID}/payment). If you want to list card transactions, you need to addressMasterCardAction viaGET /user/{userID}/monetary-account/{monetary-accountID}/mastercard-action.

There are 2 kinds of cards bunq users can order:

• CardDebit at/user/{userID}/card-debit, and
• CardCredit at/user/{userID}/card-credit.

CardDebitsupports Maestro, MasterCard, Tap & Pay, and virtual cards.CardCredit, on the other hand, offers MasterCards of eitherMASTERCARD_TRAVEL orMASTERCARD_GREEN product types. All cards of the users are listable underCard.

BothPayment andRequestInquiry objects can have a link toAttachments - images in the .png, or .jpeg, format. This makes it possible for bunq users to send payments and payment requests with contextual photos by specifying theattachmentid and upload photos of invoices and receipts to existing transactions by creatingNoteAttachments.

The difference between theAttachment andNote-attachment objects lies in their relation to other objects.Attachment is directly linked to the monetary account and thus is a higher-level resource that can be referred to underlying objects-to-be-created, whileNoteAttachment is connected to the existing objects that belong to the monetary account. You can observe this relation in the following endpoints:

• /user/{userID}/monetary-account/{monetary-accountID}/attachment
• /user/{userID}/monetary-account/{monetary-accountID}/request-inquiry/{request-inquiryID}/note-attachment
• /user/{userID}/monetary-account/{monetary-accountID}/payment/{paymentID}/note-attachment
• /user/{userID}/monetary-account/{monetary-accountID}/draft-payment/{draft-paymentID}/note-attachment
• /user/{userID}/monetary-account/{monetary-accountID}/schedule-payment/{schedule-paymentID}/note-attachment

As a bank, bunq puts tremendous effort into user data security. That is why you need to do a setup we call “creating an API context” before you can send your first custom API request. API context assures us the sender of the request is you, you are who you say you are, and, if you are a PSD2-certified party, what you are allowed to do.

API context creation flow was designed to exchange the crucial information to formsignatures that will let you and bunq verify each other’s calls.

Our SDKs handle the API context creation flow for you so you’ll only need to provide us with some constants such as your API key and - only if you are a PSD2-certified party - certificate, certificate chain and the private key belonging to the QSEAL certificate.

OAuth is the obligatory authentication method for public projects whereas using API keys is allowed as long as only you have access to your application.

Now you know how bunq works and can move on to building your own app! Jump to one of the below:

• PHP SDK
• Python SDK
• Java SDK
• C# SDK
• API documentation