Automating Scheduled Payments with the bunq API

Automating Scheduled Payments with the bunq API

Automating Scheduled Payments with the bunq API

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-paymentschedule-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.

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.

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 scheduleschedule-instanceschedule-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:

  • EMAIL
  • PHONE_NUMBER
  • 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:

{
   "payment":{
      "amount":{
         "value":"0.10",
         "currency":"EUR"
      },
      "counterparty_alias":{
         "type":"EMAIL",
         "value":"sugardaddy@bunq.com"
      },
      "description":"My scheduled payment description"
   },
   "schedule":{
      "time_start":"2019-12-13T18:25:43.511Z",
      "time_end":"2019-12-14T18:25:43.511Z",
      "recurrence_unit":"MONTHLY",
      "recurrence_size":1
   }
}

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

{
"payment":{
      "amount":{
         "value":"55.10",
         "currency":"EUR"
      },
      "counterparty_alias":{
         "type":"IBAN",
         "value":"NL10RABO0123456789",
         "name":"John Doe and Sons"
      },
      "description":"My scheduled payment description"
   },
   "schedule":{
      "time_start":"2019-12-13T11:25:43.511Z",
      "time_end":"2019-12-14T11:25:43.511Z",
      "recurrence_unit":"MONTHLY",
      "recurrence_size":1
   }
}

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:

{
   "payments":[
      {
         "amount":{
            "value":"5.00",
            "currency":"EUR"
         },
         "counterparty_alias":{
            "type":"EMAIL",
            "value":"sugardaddy@bunq.com"
         },
         "description":"My scheduled payment 1"
      },
      {
         "amount":{
            "value":"12.30",
            "currency":"EUR"
         },
         "counterparty_alias":{
            "type":"PHONE_NUMBER",
            "value":"+31649727382"
         },
         "description":"My scheduled payment 2"
      },
      {
         "amount":{
            "value":"19.95",
            "currency":"EUR"
         },
         "counterparty_alias":{
            "type":"IBAN",
            "value":"NL35BUNQ9900341392",
            "name":"Sabine Paston-Cooper"
         },
         "description":"My scheduled payment 3"
      }
   ],
   "schedule":{
      "time_start":"2019-12-16T12:25:43.511Z",
      "time_end":"2019-12-17T12:25:43.511Z",
      "recurrence_unit":"MONTHLY",
      "recurrence_size":1
   }
}

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:

{
   "payments":[
      {
         "amount":{
            "value":"5.00",
            "currency":"EUR"
         },
         "counterparty_alias":{
            "type":"EMAIL",
            "value":"sugardaddy@bunq.com"
         },
         "description":"My scheduled payment 1"
      },
      {
         "amount":{
            "value":"12.30",
            "currency":"EUR"
         },
         "counterparty_alias":{
            "type":"PHONE_NUMBER",
            "value":"+31649727382"
         },
         "description":"My scheduled payment 2"
      },
      {
         "amount":{
            "value":"19.95",
            "currency":"EUR"
         },
         "counterparty_alias":{
            "type":"IBAN",
            "value":"NL35BUNQ9900341392",
            "name":"Sabine Paston-Cooper"
         },
         "description":"My scheduled payment 3"
      }
   ],
   "schedule":{
      "time_start":"2019-12-16T12:25:43.511Z",
      "time_end":"2019-12-17T12:25:43.511Z",
      "recurrence_unit":"MONTHLY",
      "recurrence_size":1
   }
}

Once created, draft scheduled payments won’t appear in the responses to the GET requests sent to the endpoints of the schedule-paymentschedule-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 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)

First published through Medium.

Share
Share on facebook
Share on google
Share on twitter
Share on linkedin
Related Posts
Featured
Widening the scope across borders this new production will not only include the Dutch fintech scene but highlight developments on a European level as well.
Weekly fintech update in your mailbox? Sign up for our Global Fintech Update, sent every friday.

This website uses cookies to ensure you get the best experience on our website.
To learn more, read our privacy policy.

X
X
X