Automating scheduled payments with the bunq API

Dec 4, 2019 · 4 min read

Scheduled payments save time! No wonder they are so widely used by bunqers who code. 😜 We decided to save you even more time by delving into how to configure the right request body by the type of recipient. You can reuse it and focus on integrating scheduled and recurring payments into your application or personal automation flow.

Let’s start by defining what kinds of payments you can schedule using the bunq API and how they are linked to other objects.

bunq scheduled payments 101

The bunq API supports direct and draft payments and both can be scheduled. Unlike draft payments, direct payments can be batched and carried out immediately. Draft payments provide an extra validation step because they require the approval of the bank account owner.

All in all, there are three endpoints you can use to create scheduled payments:

  • /user/{userID}/monetary-account/{monetary-accountID}/schedule-payment
  • /user/{userID}/monetary-account/{monetary-accountID}/schedule-payment-batch
  • /user/{userID}/monetary-account/{monetary-accountID}/draft-payment

These and other endpoints from the schedule-payment, schedule-payment-batch, and draft-payment resources are also possible to call with other CRUDL methods.

Keep in mind: When sending PUT requests, only send the object with the relevant fields updated in the request body.

Other related endpoints

When looking through the API reference, you’ll also find schedule and schedule-instance resources and you might come across schedule objects. Let’s clarify what’s what and how they relate to scheduled payments and each other in particular.

A scheduled instance is either a scheduled payment or a scheduled payment batch put on the schedule. Only GET and PUT requests are possible with the schedule-instance endpoints.

A schedule is a list of payments that are ready to be carried through on the set date and time. It is only possible to read and list schedules. The number of schedules per user is limited to 1; however, it is possible to filter out schedules by a monetary account too.

A schedule object is either a future or set scheduled payment. It can operate in both request and response bodies of the endpoints of the schedule, schedule-instance, schedule-payment, and schedule-payment-batch resources. A schedule object is always a scheduled instance but not vice versa.

Alias types per counterparty

You can send [scheduled] payments to a party either with or without a bunq account. Different alias pointers are allowed for internal and external money receivers. It does not matter whether they are a company or a person. What does matter is if you are sending a payment to an IBAN, you must know the receiver’s name because it’s impossible to do it otherwise.

There are three alias types that you can use to send money to another bunq account:

  • IBAN

You need to set the counterparty_alias object fields depending on what information you know about the recipient. In particular, you must pass the relevant pointer type and value. For the IBAN type, you must also add the name of the user (company name if it’s a business).

IBAN is the only alias type you can use to send a transaction to a non-bunq bank account. Whether the counterparty is a person or a company, the request body has the same structure.

Finally, let’s move on to scheduling payments in practice. 🙌

Scheduling a single payment

If you know the email address of the recipient, the request body of the POST /user/{userID}/monetary-account/{monetary-accountID}/schedule-payment call will look like this:

If you want to schedule a payment to a recipient without a bunq account, the request body should look like this:

Scheduling a payment batch

The request body example you can reuse with a POST /user/{userID}/monetary-account/{monetary-accountID}/schedule-payment-batch call is the following:

Scheduling a draft payment

You can put a draft payment on the user’s schedule by calling POST /user/{userID}/monetary-account/{monetary-accountID}/draft-payment. The request body should look like this:

Once created, draft scheduled payments won’t appear in the responses to the GET requests sent to the endpoints of the schedule-payment, schedule-instance, or schedule resources. You can get them via the draft-payment resource.

Automate your banking routine the way you want it! Start by just running a single command. 😛

Choose your language:

$ bash >(curl -s

$ bash >(curl -s

$ bash >(curl -s

$ bash >(curl -s

bunq Developers’ Corner

Tips & tricks to enjoy a super, powerful, real-time RESTful API: an API so powerful, the entire bunq app runs on it.


Written by


Mobile banking, revolutionized.

bunq Developers’ Corner

Tips & tricks to enjoy a super, powerful, real-time RESTful API: an API so powerful, the entire bunq app runs on it.

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade