How to work with Travel and Green cards via the bunq API
Last year, we shared some insights with you on what composition bunq cards have. This time, we’re focusing on practical knowledge on how to work with a specific subset of them — a range that keeps growing, credit cards.
As of today, bunq offers two credit cards: bunq Travel Card and bunq Green Card. Both are shiny on the outside ✨and programmable at the core ⚛️. Is there anything you can do with one bunq credit card you can’t do with another? Let’s find out!
bunq credit cards in essence
All credit cards are CardCredit objects with type set to MasterCard. You can tell whether it’s a Travel or a Green card by looking at the value of the product_type field: it’s MASTERCARD_TRAVEL for Travel cards and MASTERCARD_GREEN for Green cards. The number of possible values might grow over time. Everything else, as well as compatibility with Google Pay and Apple Pay, is shared.
Ordering bunq credit cards
To get and start using a bunq credit card via the bunq API, you need to do 3 things:
- Create a new credit card request by making a POST /user/{userID}/card-credit call. Specify the card in
product_type
: MASTERCARD_TRAVEL or MASTERCARD_GREEN. - Wait for the card to be delivered. The order status of the card will change to
ACCEPTED_FOR_PRODUCTION
. - Activate the card by changing status to
ACTIVE
viaPUT /user/{userID}/card/{cardID}
.
HINT: the easiest way to order a bunq credit card is by using our SDKs. You only need to pass the right values.
- Nail bunq credit cards via our PHP SDK
- Nail bunq credit cards via our Java SDK
- Nail bunq credit cards via our C# SDK
- Nail bunq credit cards via our Python SDK
Retrieving bunq credit cards
You can list and read credit cards by sending the following API requests, no request body required:
GET /user/{userID}/card
(look for a CardCredit object)GET /user/{userID}/card/{cardID}
Updating bunq credit cards
Using PUT with /user/{userID}/card/{cardID}
gives you the power to not only update card limits and fallback sub-accounts but also change PIN code and freeze/block cards. You must be especially careful when changing the status of the card because some statuses are permanent and irreversible. To help you avoid trouble here’s a little helper:
Changing the status of
- If you want to freeze a card, change its status to
DEACTIVATED
. - If you want to permanently block a card, change the status of the card to
CANCELLED
.
TRIVIA: Virtual cards are designed as placeholders for card numbers. When listing your cards, you’ll notice that all the virtual cards are contained in the primary_account_numbers wrapper.
- If you want to delete a virtual card, set the status in the
primary_account_numbers
wrapper (❗not card) toCANCELLED
.
Here are the irreversible statuses:
LOST
STOLEN
CANCELLED
They can only be used when order_status is one of these:
ACCEPTED_FOR_PRODUCTION
DELIVERED_TO_CUSTOMER
CARD_UPDATE_REQUESTED
CARD_UPDATE_SENT
/CARD_UPDATE_ACCEPTED
The statuses you can change anytime include the following:
ACTIVE
DEACTIVATED
NOTE: A card can only be set to DEACTIVATED
after initial activation when order_status is either of these:
DELIVERED_TO_CUSTOMER
CARD_UPDATE_REQUESTED
CARD_UPDATE_SENT
CARD_UPDATE_ACCEPTED
.
BONUS: How to track your tree progress 🌳🌲via the bunq API
You can retrieve the number of trees you have planted to make the world a greener place via GET /user/{userID}/tree-progress. Here’s an example of what you’ll get in return:
Haven’t tried banking with full API access yet? Do it by just running a 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)