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.
A: If the counterparty has a bunq account
There are three alias types that you can use to send money to another bunq account:
- 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).
B: If the recipient doesn’t have a bunq account
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":"[email protected]"
},
"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":"[email protected]"
},
"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":"[email protected]"
},
"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-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 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.
