``` curl -X GET "https://public-api.sandbox.bunq.com/v1/user/{user_apikey_id}/monetary-account-bank" \ -H "User-Agent: text" \ -H "X-Bunq-Client-Authentication: {session_token}" \ -H "Content-Type: application/json" ``` # Register OAuth Client Before you can start the OAuth authorization flow with bunq, you need to register an OAuth client. This client represents your application and provides the necessary credentials (`client_id` and `client_secret`) to securely authenticate users. #### How to Create an OAuth Client To create an OAuth client, send a `POST` request to: ``` POST /user/{user_id}/oauth-client ``` Replace `{user_id}` with your bunq user ID. Then it will look like this:
``` curl -X POST "https://api.bunq.com/v1/user/{user_id}/oauth-client" \ -H "Content-Type: application/json" \ -H "Cache-Control: no-cache" \ -H "User-Agent: YourServiceName" \ -H "X-Bunq-Language: en_US" \ -H "X-Bunq-Region: nl_NL" \ -H "X-Bunq-Geolocation: 0 0 0 0 000" \ -H "X-Bunq-Client-Authentication: your_session_token" \ -H "X-Bunq-Client-Request-Id: 550e8400-e29b-41d4-a716-446655440000" \ -H "X-Bunq-Client-Signature: base64_encoded_signature_of_payload" \ -d '[{ "status": "ACTIVE", "display_name": "My Cool App", "redirect_url": "https://myapp.com/oauth/callback" }]' ``` Once you have that oauth client registered you can retrieve it's details by repeating the same API call but then as a GET request the response will contain the client\_id and client\_secret. Another item to keep track of is the ID of the oauth client. You may want to use it later in a PUT request to update the redirect URL {% hint style="warning" %} Be aware that each bunq user can only have 1 oauth client at a time. You'll get errors if you try to register a second one. As such you want to keep track of the ID so you can update the initial oauth client. {% endhint %} # Redirect Users to Authorize your app Once you’ve successfully registered your OAuth client ( [Register OAuth Client](/basics/authentication/oauth/register-oauth-client)), you will have a **client\_id** and **client\_secret**. These credentials allow your application to request access on behalf of your users. What we want now is to redirect the end-user to a page where they can give away the access to ther bank account. This is done by redirecting them to the authorization page.
From there you can run \`uvicorn main:app --reload' this will kick off a uvicorn server, serving a FastAPI app on port 8000 to start the server ## Initializing your installation We prepared a endpoint that you'll have to run 1x it will set up the [Broken mention](broken://pages/O5LLvymwcVpljw1lv1dN). It will also register your [OAuth](/oauth)client and register a [Callback URL OAuth](/api-reference/callback-url-oauth). You can do so by hitting the localhost:8000/setup\_one\_time it will take a minute. Finally that script will create a .env file that can be used going forward. This is a great step to remove your API key from the `main.py` file. From now on it will be read from the `.env` file. ## Using Oauth You can now go to your localhost:8000/auth endpoint which will trigger a oauth request. If you have the [Android Emulator](/getting-started/tools/android-emulator) on a physical device you'll be able to scan the QR code that is generated and complete the oauth flow. What happens in the background is: 1. The app created a oauth client in the set up. This allows us to now generate a oauth session. It is a screen with a QR code that the end-user scans with their bunq app 2. In the app the bunq user can select which monetary accounts they grant access to. 3. When the user completes the steps they are redirected to our app. With a authorization code from bunq. This code is immidiatly used by the app to request a access token. The app stores that access token in a database. and assosciates it to a user. We did not build a pretty page but if the oauth flow was successful you'll see a json response with:
``` {"message":"OAuth success","new_user_id":1} ``` This means that we stored a user in our local database with id 1 that has a bunq oauth access token associated to it. 4. So now we can retrieve data on that user. One way to do that is to visit the /docs endpoint. FastApi offers a interactive API documentation. You can also simply visit the localhost:8000/user/1 url. If you request data on behalf of a user then this happens:\ 1\. We look up the bunq access token for that user 1 in our database\ 2\. We request a session token with the access token\ 3\. We make the API call we want with that session token\ 4\. Return the results to the end-user For instance: if you go to the user/2/accounts endpoint you'll get a summary of the [Monetary Account](/monetary-account)for that user: ```json { "Response": [ { "MonetaryAccountBank": { "id": 2083712, "created": "2025-04-14 00:00:00.811318", "updated": "2025-04-14 00:00:00.811318", "alias": [ { "type": "PHONE_NUMBER", "value": "+31611019364", "name": "+31611019364" }, { "type": "EMAIL", "value": "testers+1744621019@bunq.com", "name": "testers+1744621019@bunq.com" }, { "type": "IBAN", "value": "NL65BUNQ2090411945", "name": "Jodi Walker" } ], "avatar": { "uuid": "2ef45ffc-67e9-44ac-a432-a8987c5d4e9d", "image": [ { "attachment_public_uuid": "3f3a3d92-b646-463c-ae8d-6a0393e45500", "height": 1023, "width": 1024, "content_type": "image/png", "urls": [ { "type": "ORIGINAL", "url": "https://bunq-triage-model-storage-public.s3.eu-central-1.amazonaws.com/bunq_file/File/content/921ece497cd00f4e0cef3f0f63a962c31cf3f8e35311d127d5a7b23be3d074d5.png" } ] } ], "anchor_uuid": "5e758d81-add9-4510-89e1-ff2bd5a04146", "style": "NONE" }, "balance": { "currency": "EUR", "value": "4118.00" }, "country": "NL", "currency": "EUR", "display_name": "J. Walker", "daily_limit": { "currency": "EUR", "value": "5000.00" }, "description": "Main", "public_uuid": "5e758d81-add9-4510-89e1-ff2bd5a04146", "status": "ACTIVE", "sub_status": "NONE", "timezone": "europe/amsterdam", "user_id": 1864430, "monetary_account_profile": null, "setting": { "color": "#FF7819", "icon": null, "default_avatar_status": "AVATAR_DEFAULT", "restriction_chat": "ALLOW_INCOMING", "sdd_expiration_action": "AUTO_ACCEPT" }, "connected_cards": [], "budget": [], "all_access": [ { "MonetaryAccountAccess": { "id": 2268800, "created": "2025-04-14 00:00:00.822699", "updated": "2025-04-14 00:00:00.822699", "access_type": "FULL_PERMANENT" } } ], "overdraft_limit": { "currency": "EUR", "value": "0.00" }, "all_auto_save_id": [] } }, { "MonetaryAccountBank": { "id": 2083715, "created": "2025-04-14 09:12:06.578796", "updated": "2025-06-03 09:48:46.647401", "alias": [ { "type": "IBAN", "value": "NL55BUNQ2090409118", "name": "Jodi Walker" } ], "avatar": { "uuid": "f8217171-567f-4034-ac5e-5fc281b611a6", "image": [ { "attachment_public_uuid": "fa99b3bf-7121-4d23-9fe9-6ce48ff76285", "height": 1024, "width": 1024, "content_type": "image/jpeg", "urls": [ { "type": "ORIGINAL", "url": "https://bunq-triage-model-storage-public.s3.eu-central-1.amazonaws.com/bunq_file/File/content/1fcb8573f717dc6406dbbb170367f98cbed175ca4d3bee3aeaa772fdcf284c1a.jpg" } ] } ], "anchor_uuid": "0477b9c1-ff11-4fcb-9bf1-9b84b1b5c27d", "style": "NONE" }, "balance": { "currency": "EUR", "value": "1900.00" }, "country": "NL", "currency": "EUR", "display_name": "J. Walker", "daily_limit": { "currency": "EUR", "value": "5000.00" }, "description": "Main", "public_uuid": "0477b9c1-ff11-4fcb-9bf1-9b84b1b5c27d", "status": "ACTIVE", "sub_status": "NONE", "timezone": "europe/amsterdam", "user_id": 1864430, "monetary_account_profile": null, "setting": { "color": "#ff7819", "icon": "FINANCE", "default_avatar_status": "AVATAR_ICON", "restriction_chat": "ALLOW_INCOMING", "sdd_expiration_action": "AUTO_ACCEPT" }, "connected_cards": [], "budget": [], "all_access": [ { "MonetaryAccountAccess": { "id": 2268802, "created": "2025-04-14 09:12:06.599804", "updated": "2025-04-14 09:12:06.599804", "access_type": "FULL_PERMANENT" } } ], "overdraft_limit": { "currency": "EUR", "value": "0.00" }, "all_auto_save_id": [] } }, { "MonetaryAccountBank": { "id": 2083719, "created": "2025-04-14 09:12:58.553604", "updated": "2025-04-14 09:14:06.776031", "alias": [ { "type": "IBAN", "value": "NL17BUNQ2090415428", "name": "Jodi Walker" } ], "avatar": { "uuid": "48bb720a-6baf-4482-a78c-b8592e5fde08", "image": [ { "attachment_public_uuid": "0e76b824-36ef-4680-9554-0c2da11f6ed9", "height": 1024, "width": 1024, "content_type": "image/jpeg", "urls": [ { "type": "ORIGINAL", "url": "https://bunq-triage-model-storage-public.s3.eu-central-1.amazonaws.com/bunq_file/File/content/4c90f8a578279abd53b06840a4dd619009c2f4b9ddc4342dbf12e4fbf11bbd4a.jpg" } ] } ], "anchor_uuid": "fbb765b0-2eef-4c91-8060-37950b65694a", "style": "NONE" }, "balance": { "currency": "EUR", "value": "954.00" }, "country": "NL", "currency": "EUR", "display_name": "J. Walker", "daily_limit": { "currency": "EUR", "value": "5000.00" }, "description": "Car", "public_uuid": "fbb765b0-2eef-4c91-8060-37950b65694a", "status": "ACTIVE", "sub_status": "NONE", "timezone": "europe/amsterdam", "user_id": 1864430, "monetary_account_profile": null, "setting": { "color": "#47bfff", "icon": "TRANSPORT", "default_avatar_status": "AVATAR_ICON", "restriction_chat": "ALLOW_INCOMING", "sdd_expiration_action": "AUTO_ACCEPT" }, "connected_cards": [], "budget": [], "all_access": [ { "MonetaryAccountAccess": { "id": 2268806, "created": "2025-04-14 09:12:58.575972", "updated": "2025-04-14 09:12:58.575972", "access_type": "FULL_PERMANENT" } } ], "overdraft_limit": { "currency": "EUR", "value": "0.00" }, "all_auto_save_id": [] } }, { "MonetaryAccountBank": { "id": 2083721, "created": "2025-04-14 09:13:51.146459", "updated": "2025-04-14 09:13:51.146459", "alias": [ { "type": "IBAN", "value": "NL09BUNQ2090405775", "name": "Jodi Walker" } ], "avatar": { "uuid": "5ac4305a-846b-46c0-bff7-b383db308acf", "image": [ { "attachment_public_uuid": "b312f25b-fb29-4fd0-a971-79c6eaf8b8e0", "height": 1024, "width": 1024, "content_type": "image/jpeg", "urls": [ { "type": "ORIGINAL", "url": "https://bunq-triage-model-storage-public.s3.eu-central-1.amazonaws.com/bunq_file/File/content/854e26c59d732cf32e7187f7ee4bcc11f8415d06f99ed59780fcc21883bd0f62.jpg" } ] } ], "anchor_uuid": "81802c69-3039-4d73-8138-da6e43acb7f0", "style": "NONE" }, "balance": { "currency": "EUR", "value": "1643.00" }, "country": "NL", "currency": "EUR", "display_name": "J. Walker", "daily_limit": { "currency": "EUR", "value": "5000.00" }, "description": "Medical", "public_uuid": "81802c69-3039-4d73-8138-da6e43acb7f0", "status": "ACTIVE", "sub_status": "NONE", "timezone": "europe/amsterdam", "user_id": 1864430, "monetary_account_profile": null, "setting": { "color": "#ff2d55", "icon": "HEALTHCARE", "default_avatar_status": "AVATAR_ICON", "restriction_chat": "ALLOW_INCOMING", "sdd_expiration_action": "AUTO_ACCEPT" }, "connected_cards": [], "budget": [], "all_access": [ { "MonetaryAccountAccess": { "id": 2268808, "created": "2025-04-14 09:13:51.163604", "updated": "2025-04-14 09:13:51.163604", "access_type": "FULL_PERMANENT" } } ], "overdraft_limit": { "currency": "EUR", "value": "0.00" }, "all_auto_save_id": [] } } ], "Pagination": { "future_url": null, "newer_url": null, "older_url": null } } ```
# bunq API Objects No matter what kind of integration you’re building, you’ll be working with a few essential objects that make up the bunq ecosystem. While the general idea behind each one is straightforward, some names or relationships might seem a little unexpected—mainly because the public API is built on top of the same system that powers the bunq app itself. Here are the main objects you’ll need to get familiar with (by ID): * [**User**](/basics/bunq-api-objects/user) * [**MonetaryAccount**](/basics/bunq-api-objects/monetary-account) * [**Payment**](/basics/bunq-api-objects/payment) * [**RequestInquiry**](/basics/bunq-api-objects/requestinquiry) * [**Card**](/basics/bunq-api-objects/card) * [**Attachment**](/basics/bunq-api-objects/attachment-and-note-attachment) * [**NoteAttachment**](/basics/bunq-api-objects/attachment-and-note-attachment) Let’s take a closer look at each of them and see how they fit together.
Entity relation graph
```python """ This is a continuation of the bunq_lib.py file we were writting """ def create_installation(self): if self.device_token is not None: print("bunq - Device token already created.") return url = f"{self.base_url}/installation" payload = json.dumps({"client_public_key": self.public_key_pem}) headers = { 'Content-Type': 'application/json', 'User-Agent': self.service_name, 'X-Bunq-Language': 'en_US', 'X-Bunq-Region': 'nl_NL', 'X-Bunq-Geolocation': '0 0 0 0 000', } response = requests.post(url, headers=headers, data=payload) data = response.json() self.device_token = next(item["Token"]["token"] for item in data["Response"] if "Token" in item) self.server_public_key = next(item["ServerPublicKey"]["server_public_key"] for item in data["Response"] if "ServerPublicKey" in item) self.save_device_token() # Save the token for future use def create_device_server(self): if not self.device_token: print("bunq - Device token is required to create device server.") return url = f"{self.base_url}/device-server" payload = json.dumps({ "description": self.service_name, "secret": self.api_key, "permitted_ips": ["*"] }) signed_payload_signature = sign_data(payload, self.private_key_pem) headers = { 'Content-Type': 'application/json', 'Cache-Control': 'no-cache', 'User-Agent': self.service_name, 'X-Bunq-Language': 'en_US', 'X-Bunq-Region': 'nl_NL', 'X-Bunq-Geolocation': '0 0 0 0 000', 'X-Bunq-Client-Authentication': self.device_token, 'X-Bunq-Client-Signature': signed_payload_signature } response = requests.post(url, headers=headers, data=payload) self.device_server_id = response.text def create_session(self): if not self.device_token: print("bunq - Device token is required to create session.") return url = f"{self.base_url}/session-server" payload_dict = {"secret": self.api_key} payload_json = json.dumps(payload_dict, separators=(',', ':')) signed_payload_signature = sign_data(payload_json, self.private_key_pem) headers = { 'Content-Type': 'application/json', 'Cache-Control': 'no-cache', 'User-Agent': self.service_name, 'X-Bunq-Language': 'en_US', 'X-Bunq-Region': 'nl_NL', 'X-Bunq-Geolocation': '0 0 0 0 000', 'X-Bunq-Client-Authentication': self.device_token, 'X-Bunq-Client-Signature': signed_payload_signature } response = requests.post(url, headers=headers, data=payload_json) data = response.json() print(data) # Extract and save session token self.session_token = next(item["Token"]["token"] for item in data["Response"] if "Token" in item) self.user_id = next(item["UserPerson"]["id"] for item in data["Response"] if "UserPerson" in item) print(f"bunq - Session Token: {self.session_token}") print(f"bunq - User ID: {self.user_id}") ``` At this point your you could run the fastapi server with the command ``` uvicorn main:app --reload ``` That will start the server and will register your device and create the private and public keys. Your file tree should now look like this ``` ├── device_token.json ├── lib │ └── bunq_lib.py ├── main.py ├── private_key.pem ├── public_key.pem └── signing.py ``` {% hint style="warning" %} Be aware that both the device\_token.json as the private\_key.pem contain credentials that should not be commited to source control or be shared in general. We recommend adding them to your environment variables. We created them as files here to be transparent on what the content looks like {% endhint %} Given that we now have a session and can make calls we can finish the rest of our file. ## Let's make a payment and a request In the rest of the file you can see 2 methods\ 1\. request. This is just a generic function that can create a API call to a endpoint of your choosing. 2. The second function is to create a payment. This one is a bit more tricky as it requires us to sign. ```python """ This is a continuation of the bunq_lib.py file we were writting """ def request(self, endpoint: str, method: str = "GET", data: dict = None): url = f"{self.base_url}/user/{self.user_id}/{endpoint}" print(f"[DEBUG] bunq - Requesting: {method} {url}") # Default headers headers = { 'Content-Type': 'application/json', 'Cache-Control': 'no-cache', 'User-Agent': self.service_name, 'X-Bunq-Language': 'en_US', 'X-Bunq-Region': 'nl_NL', 'X-Bunq-Geolocation': '0 0 0 0 000', 'X-Bunq-Client-Authentication': self.session_token, 'X-Bunq-Client-Request-Id': str(uuid.uuid4()) # Should be unique for each request } payload = None if data and method == "POST": # Ensure consistent JSON formatting by using separators payload = json.dumps(data, separators=(',', ':')) signed_payload_signature = sign_data(payload, self.private_key_pem) headers["X-Bunq-Client-Signature"] = signed_payload_signature print(f"[DEBUG] Request Payload: {payload}") print(f"[DEBUG] Signed Payload Signature: {signed_payload_signature}") try: response = requests.request(method, url, headers=headers, data=payload) print(f"[DEBUG] Response Status Code: {response.status_code}") if response.status_code == 401: print("[WARNING] Unauthorized (401) - Refreshing session...") self.refresh_session() response = requests.request(method, url, headers=headers, data=payload) print(f"[DEBUG] Retried Response Status Code: {response.status_code}") if response.status_code == 200: response_body = response.text server_signature = response.headers.get('X-Bunq-Server-Signature') if server_signature and self.server_public_key: # Verify the response signature if not verify_response(response_body, server_signature, self.server_public_key): raise Exception("Response signature verification failed") print("[DEBUG] Response signature verified successfully") return response.json() print(f"[ERROR] Request failed: {response.status_code} - {response.text}") response.raise_for_status() except requests.exceptions.RequestException as e: print(f"[ERROR] Request error: {e}") raise def create_payment(self, amount: str, recipient_iban: str, currency: str, from_monetary_account_id: str, description: str): url = f"{self.base_url}/user/{self.user_id}/monetary-account/{from_monetary_account_id}/payment" payload = json.dumps({ "amount": { "value": str(amount), "currency": str(currency) }, "counterparty_alias": { "type": "EMAIL", "value": "sugardaddy@bunq.com", "name": "Sugar Daddy" }, "description": str(description) }, separators=(',', ':')) # Ensure consistent JSON formatting signature = sign_data(payload, self.private_key_pem) headers = { 'Content-Type': 'application/json', 'Cache-Control': 'no-cache', 'User-Agent': self.service_name, 'X-Bunq-Language': 'en_US', 'X-Bunq-Region': 'nl_NL', 'X-Bunq-Client-Request-Id': str(uuid.uuid4()), 'X-Bunq-Geolocation': '0 0 0 0 000', 'X-Bunq-Client-Authentication': self.session_token, 'X-Bunq-Client-Signature': signature } response = requests.post(url, headers=headers, data=payload) if response.status_code == 200: response_body = response.text server_signature = response.headers.get('X-Bunq-Server-Signature') if server_signature and self.server_public_key: # Verify the response signature if not verify_response(response_body, server_signature, self.server_public_key): raise Exception("Response signature verification failed") print("[DEBUG] Response signature verified successfully") return response.json() ``` ## Making a generic API call In our main.py file we started a fastAPI server which has 2 endpoints\ 1\. /get\_cards - Which returns the cards\ 2\. /monetary-account which returns the monetary accounts of the user. You can see they both use the .request() method that we defined in the bunq\_lib.py. They just call a different endpoint. ```python @app.get("/get_cards") def get_cards(): response = bunq_client.request(endpoint='card',method='GET',data={}) return response @app.get("/monetary_account") def get_monetary_account(): response = bunq_client.request(endpoint='monetary-account',method='GET',data={}) return response ``` If we go to our browser and type:\
``` { "Response": [ { "Id": { "id": 25083708 } } ] } ``` Let's go through it step-by step. To explain the signing in depth. When we go to the /payment route we trigger this code:
```python @app.get("/payment") def payment(): payment = bunq_client.create_payment( amount='0.10', recipient_iban='NL14RABO0169202917', currency='EUR', from_monetary_account_id='18375', description='test' ) return payment ``` This calls the create\_payment() function from the bunq\_client class in our bunq\_lib.py file. It sends along some payment details, like the receiver IBAN, the monetary account to pay from, a description and an amount. Now what happens in the create\_payment() function
```python def create_payment(self, amount: str, recipient_iban: str, currency: str, from_monetary_account_id: str, description: str): url = f"{self.base_url}/user/{self.user_id}/monetary-account/{from_monetary_account_id}/payment" payload = json.dumps({ "amount": { "value": str(amount), "currency": str(currency) }, "counterparty_alias": { "type": "EMAIL", "value": "sugardaddy@bunq.com", "name": "Sugar Daddy" }, "description": str(description) }, separators=(',', ':')) # Ensure consistent JSON formatting signature = sign_data(payload, self.private_key_pem) headers = { 'Content-Type': 'application/json', 'Cache-Control': 'no-cache', 'User-Agent': self.service_name, 'X-Bunq-Language': 'en_US', 'X-Bunq-Region': 'nl_NL', 'X-Bunq-Client-Request-Id': str(uuid.uuid4()), 'X-Bunq-Geolocation': '0 0 0 0 000', 'X-Bunq-Client-Authentication': self.session_token, 'X-Bunq-Client-Signature': signature } response = requests.post(url, headers=headers, data=payload) if response.status_code == 200: response_body = response.text server_signature = response.headers.get('X-Bunq-Server-Signature') if server_signature and self.server_public_key: # Verify the response signature if not verify_response(response_body, server_signature, self.server_public_key): raise Exception("Response signature verification failed") print("[DEBUG] Response signature verified successfully") return response.json() ``` 1. We first create a payload. We have to be very specific in the exact formatting of the payload. That's why we specify the separators. We do this to ensure the payload that we sign and the payload that we send with the request match exactly. Else the signature will fail. 2. Now we call the sign\_data() function from our signing.py file this will return a signature based on our private key and the payload. 3. We add that signature to our 'X-Bunq-Client-Signature'. 4. From there it is exactly like any API call where you wait for a 200 response status 5. We included 1 final step which is to also validate the 'X-Bunq-Server-Signature' signature. by calling the verify\_response() function and comparing the signature bunq returned to the public key we stored in the installation step. # Full main.py ```python from fastapi import FastAPI from lib.bunq_lib import BunqClient USER_API_KEY = "sandbox_83f4f88a10706750ec2fdcbc1ce97b582a986f2846d33dcaaa974d95" bunq_client = BunqClient(USER_API_KEY, service_name='PeterScript') # Run these 1x to initialize your application bunq_client.create_installation() bunq_client.create_device_server() bunq_client.create_session() app = FastAPI() @app.get("/monetary_account") def get_monetary_account(): response = bunq_client.request(endpoint='monetary-account',method='GET',data={}) return response @app.get("/request") def request(): endpoint = f"monetary-account/" response = bunq_client.request(endpoint=endpoint, method='GET', data=None) return response @app.get("/payment") def payment(): payment = bunq_client.create_payment( amount='0.10', recipient_iban='NL14RABO0169202917', currency='EUR', from_monetary_account_id='1989601', description='test' ) return payment ``` # Full bunq\_lib.py ```python import json import requests from signing import generate_rsa_key_pair, sign_data, verify_response import uuid class BunqClient: def __init__(self, api_key, service_name, base_url="https://public-api.sandbox.bunq.com/v1"): self.service_name = service_name self.api_key = api_key self.private_key_pem, self.public_key_pem = generate_rsa_key_pair() self.device_token = None self.server_public_key = None self.device_server_id = None self.session_token = None self.user_id = None self.base_url = base_url # Try to load device token from file self.load_device_token() def save_device_token(self): """Save the device token to a file.""" with open('device_token.json', 'w') as file: json.dump({"device_token": self.device_token}, file) def load_device_token(self): """Load the device token from a file if it exists.""" try: with open('device_token.json', 'r') as file: data = json.load(file) self.device_token = data.get("device_token") print(f"bunq - Loaded device token from file [KEEP THIS SAFE!]") except FileNotFoundError: print("bunq - No device token found, need to create a new one.") def create_installation(self): if self.device_token is not None: print("bunq - Device token already created.") return url = f"{self.base_url}/installation" payload = json.dumps({"client_public_key": self.public_key_pem}) headers = { 'Content-Type': 'application/json', 'User-Agent': self.service_name, 'X-Bunq-Language': 'en_US', 'X-Bunq-Region': 'nl_NL', 'X-Bunq-Geolocation': '0 0 0 0 000', } response = requests.post(url, headers=headers, data=payload) data = response.json() self.device_token = next(item["Token"]["token"] for item in data["Response"] if "Token" in item) self.server_public_key = next(item["ServerPublicKey"]["server_public_key"] for item in data["Response"] if "ServerPublicKey" in item) self.save_device_token() # Save the token for future use def create_device_server(self): if not self.device_token: print("bunq - Device token is required to create device server.") return url = f"{self.base_url}/device-server" payload = json.dumps({ "description": self.service_name, "secret": self.api_key, "permitted_ips": ["*"] }) signed_payload_signature = sign_data(payload, self.private_key_pem) headers = { 'Content-Type': 'application/json', 'Cache-Control': 'no-cache', 'User-Agent': self.service_name, 'X-Bunq-Language': 'en_US', 'X-Bunq-Region': 'nl_NL', 'X-Bunq-Geolocation': '0 0 0 0 000', 'X-Bunq-Client-Authentication': self.device_token, 'X-Bunq-Client-Signature': signed_payload_signature } response = requests.post(url, headers=headers, data=payload) self.device_server_id = response.text def create_session(self): if not self.device_token: print("bunq - Device token is required to create session.") return url = f"{self.base_url}/session-server" payload_dict = {"secret": self.api_key} payload_json = json.dumps(payload_dict, separators=(',', ':')) signed_payload_signature = sign_data(payload_json, self.private_key_pem) headers = { 'Content-Type': 'application/json', 'Cache-Control': 'no-cache', 'User-Agent': self.service_name, 'X-Bunq-Language': 'en_US', 'X-Bunq-Region': 'nl_NL', 'X-Bunq-Geolocation': '0 0 0 0 000', 'X-Bunq-Client-Authentication': self.device_token, 'X-Bunq-Client-Signature': signed_payload_signature } response = requests.post(url, headers=headers, data=payload_json) data = response.json() print(data) # Extract and save session token self.session_token = next(item["Token"]["token"] for item in data["Response"] if "Token" in item) self.user_id = next(item["UserPerson"]["id"] for item in data["Response"] if "UserPerson" in item) print(f"bunq - Session Token: {self.session_token}") print(f"bunq - User ID: {self.user_id}") def request(self, endpoint: str, method: str = "GET", data: dict = None): url = f"{self.base_url}/user/{self.user_id}/{endpoint}" print(f"[DEBUG] bunq - Requesting: {method} {url}") # Default headers headers = { 'Content-Type': 'application/json', 'Cache-Control': 'no-cache', 'User-Agent': self.service_name, 'X-Bunq-Language': 'en_US', 'X-Bunq-Region': 'nl_NL', 'X-Bunq-Geolocation': '0 0 0 0 000', 'X-Bunq-Client-Authentication': self.session_token, 'X-Bunq-Client-Request-Id': str(uuid.uuid4()) # Should be unique for each request } payload = None if data and method == "POST": # Ensure consistent JSON formatting by using separators payload = json.dumps(data, separators=(',', ':')) signed_payload_signature = sign_data(payload, self.private_key_pem) headers["X-Bunq-Client-Signature"] = signed_payload_signature print(f"[DEBUG] Request Payload: {payload}") print(f"[DEBUG] Signed Payload Signature: {signed_payload_signature}") try: response = requests.request(method, url, headers=headers, data=payload) print(f"[DEBUG] Response Status Code: {response.status_code}") if response.status_code == 401: print("[WARNING] Unauthorized (401) - Refreshing session...") self.refresh_session() response = requests.request(method, url, headers=headers, data=payload) print(f"[DEBUG] Retried Response Status Code: {response.status_code}") if response.status_code == 200: response_body = response.text server_signature = response.headers.get('X-Bunq-Server-Signature') if server_signature and self.server_public_key: # Verify the response signature if not verify_response(response_body, server_signature, self.server_public_key): raise Exception("Response signature verification failed") print("[DEBUG] Response signature verified successfully") return response.json() print(f"[ERROR] Request failed: {response.status_code} - {response.text}") response.raise_for_status() except requests.exceptions.RequestException as e: print(f"[ERROR] Request error: {e}") raise def create_payment(self, amount: str, recipient_iban: str, currency: str, from_monetary_account_id: str, description: str): url = f"{self.base_url}/user/{self.user_id}/monetary-account/{from_monetary_account_id}/payment" payload = json.dumps({ "amount": { "value": str(amount), "currency": str(currency) }, "counterparty_alias": { "type": "EMAIL", "value": "sugardaddy@bunq.com", "name": "Sugar Daddy" }, "description": str(description) }, separators=(',', ':')) # Ensure consistent JSON formatting signature = sign_data(payload, self.private_key_pem) headers = { 'Content-Type': 'application/json', 'Cache-Control': 'no-cache', 'User-Agent': self.service_name, 'X-Bunq-Language': 'en_US', 'X-Bunq-Region': 'nl_NL', 'X-Bunq-Client-Request-Id': str(uuid.uuid4()), 'X-Bunq-Geolocation': '0 0 0 0 000', 'X-Bunq-Client-Authentication': self.session_token, 'X-Bunq-Client-Signature': signature } response = requests.post(url, headers=headers, data=payload) if response.status_code == 200: response_body = response.text server_signature = response.headers.get('X-Bunq-Server-Signature') if server_signature and self.server_public_key: # Verify the response signature if not verify_response(response_body, server_signature, self.server_public_key): raise Exception("Response signature verification failed") print("[DEBUG] Response signature verified successfully") return response.json() ``` # Full signing.py ```python import os from cryptography.hazmat.primitives import hashes, serialization from cryptography.hazmat.primitives.asymmetric import padding, rsa from cryptography.hazmat.backends import default_backend from cryptography.hazmat.primitives.serialization import load_pem_private_key import base64 import hashlib # Function to generate RSA key pair def generate_rsa_key_pair(): private_key_file = 'private_key.pem' public_key_file = 'public_key.pem' # Check if the key files exist if os.path.exists(private_key_file) and os.path.exists(public_key_file): # Read the existing keys from the text files with open(private_key_file, 'r') as private_file: private_key_pem = private_file.read() with open(public_key_file, 'r') as public_file: public_key_pem = public_file.read() print("bunq - using existing keypair") else: # Generate new RSA keys with 2048 bits as required by Bunq private_key = rsa.generate_private_key( public_exponent=65537, key_size=2048, backend=default_backend() ) public_key = private_key.public_key() # Serialize private key to PEM format (PKCS#8 as required by Bunq) private_key_pem = private_key.private_bytes( encoding=serialization.Encoding.PEM, format=serialization.PrivateFormat.PKCS8, encryption_algorithm=serialization.NoEncryption() ).decode('utf-8') # Serialize public key to PEM format public_key_pem = public_key.public_bytes( encoding=serialization.Encoding.PEM, format=serialization.PublicFormat.SubjectPublicKeyInfo ).decode('utf-8') # Save the keys to text files with open(private_key_file, 'w') as private_file: private_file.write(private_key_pem) with open(public_key_file, 'w') as public_file: public_file.write(public_key_pem) print("bunq - creating new keypair [KEEP THESE FILES SAFE]") return private_key_pem, public_key_pem def load_private_key(private_key_pem): """Load a private key from PEM format.""" return load_pem_private_key(private_key_pem.encode(), password=None, backend=default_backend()) def load_public_key(public_key_pem): """Load a public key from PEM format.""" return serialization.load_pem_public_key( public_key_pem.encode(), backend=default_backend() ) def sign_data(data, private_key_pem): """Signs the given data with the provided private key using SHA256 and PKCS#1 v1.5 padding. Args: data (str): The data to sign (should be the JSON request body) private_key_pem (str): The private key in PEM format Returns: str: Base64 encoded signature """ private_key = load_private_key(private_key_pem) # Ensure the data is encoded in UTF-8 exactly as it will be sent encoded_data = data.encode('utf-8') # Debug: Print exact bytes being signed print("\n[DEBUG] Signing Data Bytes:", encoded_data) print("[DEBUG] SHA256 Hash of Data:", hashlib.sha256(encoded_data).hexdigest()) # Generate signature using SHA256 and PKCS#1 v1.5 padding as required by Bunq signature = private_key.sign( encoded_data, padding.PKCS1v15(), hashes.SHA256() ) # Encode in Base64 (as required by Bunq API) encoded_signature = base64.b64encode(signature).decode('utf-8') # Debug: Print signature print("[DEBUG] Base64 Encoded Signature:", encoded_signature) return encoded_signature def verify_response(response_body, signature, server_public_key_pem): """Verifies the server's response signature. Args: response_body (str): The response body as a string signature (str): The base64 encoded signature from X-Bunq-Server-Signature header server_public_key_pem (str): The server's public key in PEM format Returns: bool: True if signature is valid, False otherwise """ try: # Load the server's public key public_key = load_public_key(server_public_key_pem) # Decode the base64 signature decoded_signature = base64.b64decode(signature) # Verify the signature public_key.verify( decoded_signature, response_body.encode('utf-8'), padding.PKCS1v15(), hashes.SHA256() ) return True except Exception as e: print(f"[ERROR] Signature verification failed: {e}") return False ``` # PHP Code Example #### Signing a Request (Example in PHP) 1️⃣ Take the request body: ```json { "amount": { "value": "12.50", "currency": "EUR" }, "counterparty_alias": { "type": "EMAIL", "value": "bravo@bunq.com" }, "description": "Payment for drinks." } ``` 2️⃣ Sign it using your private key: ```php openssl_sign($dataToSign, $signature, $privateKey, OPENSSL_ALGO_SHA256); $encodedSignature = base64_encode($signature); ``` 3️⃣ Add the signature to the request headers: ```http X-Bunq-Client-Signature: [your base64-encoded signature] ``` 4️⃣ Send it! 🎉 # Whitelisting and Updating IP addresses ### Why Whitelist IP Addresses? Whitelisting IP addresses is a critical security measure that restricts which API calls are accepted by our backend. By explicitly listing trusted IP addresses, you minimize the risk of unauthorized access from unknown or malicious locations. This ensures that even if someone obtains your password credential, they cannot authenticate unless their IP is authorized. In short: **IP whitelisting helps protect your account by allowing server authentication only from trusted networks.** ### Default Behavior The IP address you pass along in you [Device Registration](/tutorials/your-first-payment/creating-the-api-context/device-registration) is automatically whitelisted to be used for API calls and set to ACTIVE. If you pass in a wildcard `["*"]` then we chose the IP address used for the API call. Whitelisting IP addresses is risky and only possible from within our app. So if you don't change anything this will be the default behavior * The IP address you use during device registeration will be immidiatly usable. * Other IPs are not allowed until explicitly added. * This default auto-whitelisting ensures smooth onboarding without manual IP setup. *** ### Key Concepts #### CredentialPasswordIp This is your credential linked to your [Devices](/devices) used for server-side authentication. Each credential has IP addresses associated with it. #### IP Entries Each credential can have multiple IP addresses whitelisted, with the following attributes: * **ip**: The IP address allowed to authenticate. * **status**: Either * `ACTIVE`: This IP is allowed to authenticate (and will be billed). * `INACTIVE`: This IP is blocked and cannot be used. > **Note:** IP addresses cannot be changed once created. To update an IP, you must mark the old one as `INACTIVE` and add a new one. *** ### Important Notes * The wildcard IP `*` (which disables IP filtering, allowing all IPs) **cannot be created or managed via the API** — only via the bunq app. This is to prevent accidental security risks through API misuse. * Only `ACTIVE` IP addresses can be used to authenticate. * Carefully manage your IP whitelist to control access and reduce attack surface. *** ### API Operations Overview #### Reference Visit this page for all the API calls related to IP whitelisting: [Credential Password IP](/credential-password-ip) #### Credentials Management * **List Credentials**\ `GET /v1/user/{user_id}/credential-password-ip`\ Lists all password credentials for your user. * **Get Credential**\ `GET /v1/user/{user_id}/credential-password-ip/{credential_password_ip_id}`\ Retrieves details for a specific credential. #### IP Addresses Management * **List IPs for a Credential**\ `GET /v1/user/{user_id}/credential-password-ip/{credential_password_ip_id}/ip`\ Lists all IPs whitelisted for the credential. * **Get a Single IP Entry**\ `GET /v1/user/{user_id}/credential-password-ip/{credential_password_ip_id}/ip/{item_id}`\ Retrieves details of a specific IP entry. * **Add a New IP**\ `POST /v1/user/{user_id}/credential-password-ip/{credential_password_ip_id}/ip`\ Adds a new IP address with a status (`ACTIVE` or `INACTIVE`). * **Update IP Status**\ `PUT /v1/user/{user_id}/credential-password-ip/{credential_password_ip_id}/ip/{item_id}`\ Updates the status from `ACTIVE` to `INACTIVE` of an existing IP.\ \&#xNAN;*Note:* The IP address itself **cannot** be changed. *** ### Security Best Practices * Regularly review and update your IP whitelist to remove unused or suspicious IPs. * Avoid using the wildcard IP `*` unless absolutely necessary and only via the bunq app. * Set inactive IPs to `INACTIVE` rather than deleting immediately for audit trails. * Use distinct credentials per environment (dev, staging, prod) with tailored IP whitelists. *** # Chapter 0 setting up the API context When integrating with the bunq API, security is a top priority. Instead of relying solely on API keys, bunq uses a **three-step authentication process:** * installation, * device registration, * session creation to ensure secure and controlled access. This approach prevents unauthorized use, protects sensitive financial data, and aligns with banking security standards like PSD2. Here’s how each step enhances security while keeping API access flexible and manageable. {% hint style="info" %} **Pro Tip: Simplify with Postman** Using our Postman examples makes API integration super easy. We've pre-filled all the requests with environment variables, streamlining the process and reducing the risk of errors. It's by far the quickest way to get a live session, to play around with until you fully commit to a integration in your own application.This setup allows you to focus more on development and less on configuration, ensuring a smoother experience Check it out here : [Postman](/getting-started/tools/postman) {% endhint %} **Setting up the API context** We documented the API context in the following pages * [Creating the Installation](/tutorials/your-first-payment/creating-the-api-context/creating-the-installation) * [Device Registration](/tutorials/your-first-payment/creating-the-api-context/device-registration) * [Start a Session](/tutorials/your-first-payment/creating-the-api-context/start-a-session) ### Host URL for the API endpoints One change for partners, compared to regular API users is the base URL. Make sure to target * Sandbox: `https://partner-api.sandbox.bunq.com` * Production: `https://api.partner.bunq.com` # Chapter 1 Setting up oauth client **This chapter goes into the setting up of the oauth client for user provisioning.** {% hint style="info" %} Our default API documentation has additional material related to setting up[OAuth](/basics/authentication/oauth). {% endhint %} **Endpoint:** ```http POST /v1/user/{user_id}/oauth-client {} ``` **Response:** ```json { "Response": [ { "Id": { "id": 789 } } ] } ``` *** ## Step 2: Read OAuth Client Details **Endpoint:** ```http GET /v1/user/{user_id}/oauth-client/{client_id} ``` **Response:** ```json { "Response": [ { "OauthClient": { "id": 789, "status": "ACTIVE", "display_name": null, "client_id": "client_abc123def456", "secret": "secret_xyz789uvw012", "callback_url": [] } } ] } ``` **Fields:** | Field | Type | Description | | -------------- | ------- | -------------------------------------- | | `id` | integer | Unique identifier for the OAuth client | | `status` | string | Status (e.g., `ACTIVE`) | | `display_name` | string | Human-readable name | | `client_id` | string | OAuth client ID | | `secret` | string | OAuth client secret | | `callback_url` | array | Registered callback URLs | *** ## Step 3: Register OAuth Callback URL **Endpoint:** ```http POST /v1/user/{user_id}/oauth-client/{client_id}/callback-url { "url": "https://yourpartner.com/oauth/callback" } ``` **Response:** ```json { "Response": [ { "Id": { "id": 456 } } ] } ``` | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------------------------ | | `url` | string | Yes | HTTPS callback URL to register | *** ## Step 4: Read Callback URL Details **Endpoint:** ```http GET /v1/user/{user_id}/oauth-client/{client_id}/callback-url/{callback_url_id} ``` **Response:** ```json { "Response": [ { "OauthCallbackUrl": { "id": 456, "created": "2025-08-13 14:45:20.123456", "updated": "2025-08-13 14:45:20.123456", "url": "https://yourpartner.com/oauth/callback" } } ] } ``` # Chapter 2 Creating a user provision Provisioning a user is the initial step in the process of creating a user account within the bunq platform. This step involves assigning basic user attributes and configurations, such as unique identifiers, contact method, and necessary personal details. By completing this step, you obtain an API Key in order to do actions on-behalf-of the user (such as finalizing the onboarding and then creating monetary accounts, cards, payments etc). **Endpoint:** ```http POST /v1/partner-user-provision { "external_uuid": "550e8400-e29b-41d4-a716-446655440000", "pointer": { "type": "EMAIL", "value": "user@example.com", "name": "user@example.com" }, "products": ["USER_VERIFIED"] } ``` **Parameters:** | Field | Type | Required | Description | | --------------- | ------ | -------- | ------------------------------------------------------------------------------------------------- | | `external_uuid` | string | Yes | Unique identifier for this provision request. Must be a valid UUID. | | `pointer` | object | Yes | User identification pointer (email, phone, etc.) | | `pointer.type` | string | Yes |
Type of pointer.
Can either be:
EMAIL, PHONE\_NUMBER
{
"Response": [
{
"Id": {
"id": 260
}
}
]
}
](broken://spaces/DAjxE0NLYI3ib2scBvPQ/pages/docx9pwt7rvEACyx4trK) # Chapter 4 Webhooks / Callbacks On top of our regular [Callbacks (Webhooks)](/basics/callbacks-webhooks) documentation there are some special options for User Provision users. **NotificationUrl Object:** | `target_url` | Your configured webhook endpoint URL | | ------------ | -------------------------------------------------------- | | `category` | Notification category (e.g., `USER_INFORMATION_INQUIRY`) | | `event_type` | Specific event type within the category | | `object` | The actual object that triggered the notification | **UserInformationInquiry Object:** | `id` | Unique identifier for the inquiry | | ------------------------ | ------------------------------------------------------------------ | | `created` | Timestamp when the inquiry was created | | `updated` | Timestamp when the inquiry was last updated | | `user_id` | ID of the user for whom the inquiry was created | | `title` | Title of the inquiry (e.g., "We need additional information") | | `subtitle` | Subtitle explaining the inquiry purpose | | `purpose` | Purpose of the inquiry (e.g., `COMPLIANCE_TRANSACTION_MONITORING`) | | `all_entry` | Array of inquiry entries with specific information requests | | `assistant_conversation` | Conversation details for user interaction | **UserInformationInquiryEntry Object:** | `id` | Unique identifier for the inquiry entry | | ------------------------ | ------------------------------------------------------------------ | | `type` | Type of information requested (e.g., `USER_PERSON_SOURCE_OF_FUND`) | | `status` | Status of the entry (e.g., `PENDING`) | | `all_data_submitted` | Array of data submitted by the user | | `assistant_conversation` | Conversation context for this specific entry | | `context` | Additional context information | | `reject_reason` | Reason for rejection (if applicable) | **Webhook Body Example (`PARTNER_USER_PROVISION`):** ```json { "NotificationUrl": { "target_url": "https://webhook.site/73fef6b5-f7ba-419b-b65f-f66199489903", "category": "PARTNER_USER_PROVISION", "event_type": "PARTNER_USER_PROVISION_PROCESS_UPDATED", "object": { "PartnerUserProvision": { "id": 7, "created": "2025-09-03 08:24:13.795007", "updated": "2025-09-03 08:24:14.266407", "external_uuid": "f8b69bdd-e2fa-4161-9ff7-f4c597f8be8e", "status": "ACTIVE", "sub_status": "NONE", "action_required": "NONE", "products": [ "USER_ANONYMOUS_TRANSACTION_AUDIT" ], "label_user": { "uuid": "ae92e7da-59d6-4dcd-a99b-0109baa5aebc", "display_name": "New bunqer", "country": "NL", "avatar": { "uuid": "353e5068-1254-4422-b949-596b9f86ebeb", "image": [ { "attachment_public_uuid": "229705c3-9d5c-424f-abc4-3f84559abd6f", "height": 640, "width": 640, "content_type": "image/png", "urls": [ { "type": "ORIGINAL", "url": "https://bunq-triage-model-storage-public.s3.eu-central-1.amazonaws.com/bunq_file/File/content/e627dab1418debb69a8ab983e7cd99a7b0cb8c289892dde90a8b2f12d5e23140.png" } ] } ], "anchor_uuid": "ae92e7da-59d6-4dcd-a99b-0109baa5aebc", "style": "NONE" }, "public_nick_name": "New bunqer", "type": "PERSON" }, "oauth_request": { "uuid": "c59a2b0d-1a16-4a5e-9ad7-93f4921d5b52", "created": "2025-09-03 08:24:14.110949", "updated": "2025-09-03 08:24:14.182413", "oauth_client_id": 13383, "oauth_client_display_name": null, "response_type": "code", "callback_url": "https://yourpartner.com/oauth/callback", "status": "ACCEPTED", "state": null, "authorization_code": "b967643d4c76956b550553a0ebd94f1024c734d0ebaefdca00d42d1f1bfae274", "user_alias_created": { "uuid": "490f019f-6e1c-4891-b2de-da9e85a12644", "display_name": "Sutton Onderlinge Waarborgmaatschappij", "country": "000", "avatar": { "uuid": "9debf55b-70b1-4d43-8d51-d6e7bd42fb5b", "image": [ { "attachment_public_uuid": "4b7e0d1d-9167-48ac-990a-70e342c87812", "height": 126, "width": 200, "content_type": "image/jpeg", "urls": [ { "type": "ORIGINAL", "url": "https://bunq-triage-model-storage-public.s3.eu-central-1.amazonaws.com/bunq_file/File/content/6979a145b7ea9ecc3459358122cb560608f02d36d4b8cd6b770f50e36aa35512.jpg" } ] } ], "anchor_uuid": "490f019f-6e1c-4891-b2de-da9e85a12644", "style": "NONE" }, "public_nick_name": "Sutton Onderlinge Waarborgmaatschappij", "type": "COMPANY" }, "redirect_url": "https://yourpartner.com/oauth/callback?code=b967643d4c76956b550553a0ebd94f1024c734d0ebaefdca00d42d1f1bfae274", "type": "BUNQ" }, "credential": { "id": 2412203, "created": "2025-09-03 08:24:14.178726", "updated": "2025-09-03 08:24:14.178726", "status": "PENDING_FIRST_USE", "expiry_time": "2025-09-03 09:24:14.178685", "token_value": "a0239a79b1a8d4429062bbcbdccf30cfda06eb6a2a8effc041085135e36d63d4", "permitted_device": null } } } } } ``` #### Callback categories Category Description BILLING notifications for all bunq invoices CARD\_TRANSACTION\_SUCCESSFUL notifications for successful card transactions CARD\_TRANSACTION\_FAILED notifications for failed card transaction CHAT notifications for received chat messages DRAFT\_PAYMENT notifications for creation and updates of draft payments IDEAL notifications for iDEAL-deposits towards a bunq account SOFORT notifications for SOFORT-deposits towards a bunq account MUTATION notifications for any action that affects a monetary account’s balance OAUTH notifications for revoked OAuth connections PAYMENT notifications for payments created from, or received on a bunq account (doesn’t include payments that result out of paying a Request, iDEAL, Sofort or Invoice). Outgoing payments have a negative value while incoming payments have a positive value REQUEST notifications for incoming requests and updates on outgoing requests SCHEDULE\_RESULT notifications for when a scheduled payment is executed SCHEDULE\_STATUS notifications about the status of a scheduled payment, e.g. when the scheduled payment is updated or cancelled SHARE notifications for any updates or creation of Connects (ShareInviteBankInquiry) TAB\_RESULT notifications for updates on Tab payments BUNQME\_TAB notifications for updates on bunq.me Tab (open request) payments SUPPORT notifications for messages received from us through support chat #### Mutation Category A *Mutation* is a change in the balance of a monetary account. A *Mutation* is created for each payment-like object, such as a request, iDEAL-payment or a regular payment. Therefore, the `MUTATION`category can be used to keep track of a monetary account's balance change. #### Receiving Callbacks * Callbacks for the sandbox environment will be made from different IP's at AWS. * Callbacks for the production environment will be made from 185.40.108.0/22. *The IP addresses might change*. We will notify you in a timely fashion if such a change is planned. #### Removing callbacks To remove callbacks for an object, send a POST request to the `notification_filters` endpoint with a JSON request body with an emtpy list. ``` { "notification_filters": [] } ``` ### Retry Mechanisms When the execution of a callback fails (e.g. the callback server is down or the response contains an error), we try to resend it for a maximum of 5 times, with an interval of one minute between each try. If your server is not reachable by the callback after the 6th total try, the callback is not sent anymore. #### Listing of failed callbacks After the sixth attempt of callback executing, the failed entry is stored and can be listed by UserApiKey ``` GET /v1/user/762/notification-filter-failure { "Response": [ { "NotificationFilterFailure": { "id": 1, "created": "2023-05-22 06:47:22.043906", "updated": "2023-05-22 06:47:22.043906", "category": "MUTATION", "event_type": "MUTATION_CREATED", "object_id": 1278, "notification_filters": [ { "notification_delivery_method": "URL", "notification_target": "https://coolbank.com/notification", "category": "MUTATION" }, { "notification_delivery_method": "URL", "notification_target": "https://coolbank.com/notification", "category": "CARD_TRANSACTION_SUCCESSFUL" } ] } } ], "Pagination": { "future_url": "/v1/user/762/notification-filter-failure?newer_id=1", "newer_url": null, "older_url": null } } ``` \* the category & object\_id can be used to verify if the callback has failed and should be retried \*\* the id of the NotificationFilterFailure object should be used to trigger the retry #### Retry of failed callbacks Copy ``` POST /v1/user/762/notification-filter-failure { "notification_filter_failed_ids": "1" } ``` \* multiple ids can be given in the same field, comma separated. Maximum of 100 ids are allowed \*\* response will be empty with code 200 (OK) #### Certificate Pinning We recommend that you use certificate pinning as an extra security measure. We will check if the certificate of the recipient server matches the pinned certificate that you provided and cancel the callback if the check fails or we detect a mismatch. #### How to set up certificate pinning 1. Retrieve the SSL certificate of your server using the following command: `openssl s_client -servername www.example.com -connect www.example.com:443 < /dev/null | sed -n "/-----BEGIN/,/-----END/p" > www.example.com.pem` 2. `POST` the certificate to the `certificate-pinned`endpoint. Once ready, every callback will be checked against the pinned certificate that you provided. Note that if the SSL certificate on your server expires or is changed, our callbacks will fail. # Getting Started with Banking As A Service # Introduction & Core Paradigms Before you make your first API call, it's worth spending a few minutes understanding how bunq thinks about banking. The API is consistent and predictable — but only once the underlying model clicks. *** ### bunq is the bank. You are the platform. When you integrate bunq BaaS, you're not connecting to a ledger or a payment processor. You're connecting to a licensed bank. That distinction matters in two ways: 1. **Regulation is handled for you.** bunq holds the banking license, manages AML obligations, safeguards funds, and sits on the payment rails. You don't need your own EMI license to issue IBANs or cards through bunq. 2. **You stay in control.** Everything bunq does for your users — opening accounts, issuing cards, verifying identity, moving money — is driven by API calls your platform makes. bunq executes; you orchestrate. *** ### The user hierarchy The most important concept in the bunq data model is the **user hierarchy**. ``` bunq (the bank) └── Your platform (API key holder) └── Sub-user A ← KYC-verified individual │ ├── Monetary Account (IBAN) │ │ └── Payments │ └── Card └── Sub-user B ├── Monetary Account └── Card ``` Everything in bunq lives under a `user`. When you use BaaS, you create and manage **sub-users** — one per end-user on your platform. Each sub-user goes through KYC, gets their own monetary accounts, and can have cards issued against those accounts. Your API credentials sit at the top of this tree. You act on behalf of sub-users using the user ID in your API paths: `/v1/user/{userID}/monetary-account`, `/v1/user/{userID}/payment`, and so on. *** ### Everything is an object bunq's API is resource-oriented. The key objects you'll work with in BaaS, and how they relate: | Object | What it is | Lives under | | ------------------ | --------------------------------------- | --------------------------------------- | | `User` | A verified identity (your end-user) | Your platform credentials | | `MonetaryAccount` | A bank account with an IBAN | A `User` | | `Payment` | A money movement (in or out) | A `MonetaryAccount` | | `Card` | A Mastercard debit card | A `User`, linked to a `MonetaryAccount` | | `MastercardAction` | A card transaction (auth or settlement) | A `MonetaryAccount` | Objects reference each other by ID. A card points to its linked monetary account. A payment points to the account it moved money on. When something goes wrong or you need to reconcile, you can always trace the chain back. *** ### The session model bunq uses a **signed-request, session-token** authentication pattern. You set it up once per integration, then manage short-lived sessions. The flow has three steps: 1. **Installation** — register your public key with bunq via `POST /v1/installation`. Receive an installation token. 2. **Device registration** — identify your server via `POST /v1/device-server` using the installation token. 3. **Session** — start a session via `POST /v1/session-server`. Receive a session token valid for the duration of that session. Use the session token in the `X-Bunq-Client-Authentication` header on every subsequent request. Sessions expire after inactivity — your integration should handle re-authentication gracefully. Every request must also be **signed** with your private key and include the signature in the `X-Bunq-Client-Signature` header. bunq verifies this signature server-side, and signs its responses so you can verify them too. For the full authentication walkthrough, see [Basics → Getting Started](https://doc.bunq.com/basics). *** ### The lifecycle pattern Most objects in bunq move through a predictable lifecycle: created → active → closed. The key states to handle in your integration: | Object | States to handle | | --------------- | ----------------------------------------------------------- | | Sub-user | `PENDING` → `VERIFIED` (KYC complete) / `REJECTED` | | MonetaryAccount | `PENDING` → `ACTIVE` → `CANCELLED` | | Payment | `PENDING` → `EXECUTED` / `REJECTED` / `REVERTED` | | Card | `ACTIVE` → `SUSPENDED` (frozen) → `DEACTIVATED` / `EXPIRED` | Design your platform logic around these states. Don't assume an object is active just because you created it — always check status before acting on it. *** ### Callbacks, not polling bunq is event-driven. Instead of polling for changes, register a **notification filter** (webhook) on the user or account you care about. bunq will `POST` to your endpoint when something happens — a payment arrives, a KYC result comes in, a card transaction is authorised. ``` POST /v1/user/{userID}/notification-filter-url { "notification_filters": [ { "notification_delivery_method": "URL", "notification_target": "https://your-platform.com/webhooks/bunq", "category": "PAYMENT" } ] } ``` Always verify the `X-Bunq-Server-Signature` header on incoming callbacks before processing them. Respond with a `200` quickly — do your processing asynchronously. Available callback categories relevant to BaaS: `PAYMENT`, `MUTATION`, `CARD_TRANSACTION_AUTHORISED`, `CARD_TRANSACTION_DECLINED`, `KYC`. *** ### Idempotency Network failures happen. For any state-changing request (creating a payment, issuing a card), always include a unique `X-Bunq-Client-Request-Id` header. If you retry a failed request with the same ID, bunq will return the original result rather than executing the action twice. ``` X-Bunq-Client-Request-Id: your-unique-uuid-here ``` Generate a fresh UUID per request and store it alongside the pending operation. If the request times out, retry with the same ID. Once you have a confirmed response, the ID can be retired. *** ### Sandbox vs production bunq provides a full sandbox environment at `public-api.sandbox.bunq.com`. It mirrors the production API exactly — same endpoints, same object model, same authentication flow — but uses test money and synthetic identity verification. Build and test your entire integration in sandbox before going live. The only things that differ in production are real IBANs, real card networks, and real KYC checks. | | Sandbox | Production | | -------- | ------------------------------ | ------------------------------- | | Base URL | `public-api.sandbox.bunq.com` | `api.bunq.com` | | API key | Generated via sandbox tools | Issued by bunq after onboarding | | KYC | Synthetic (always passes) | Real identity verification | | Payments | Test money, no real settlement | Live SEPA rails | | Cards | Virtual test cards | Real Mastercard-network cards | *** ### What to build first If you're starting a new BaaS integration, the recommended sequence is: 1. **Authentication** — get your sandbox credentials, complete the installation → device → session flow. 2. **KYC** — create a test sub-user and verify them through the sandbox KYC flow. 3. **Monetary account** — open an account for the verified user and note the IBAN. 4. **Payments** — send a test payment out; trigger an incoming payment to the IBAN. 5. **Cards** — issue a virtual card and generate a CVC2. 6. **Callbacks** — register a webhook and verify you're receiving events for each of the above. Once all six work end-to-end in sandbox, you're ready to go through the production onboarding process with your bunq BaaS account manager. # Overview ## Banking as a Service bunq is a fully licensed European bank — and we're opening the entire stack to developers and businesses who want to build financial products without starting from scratch. With bunq's Banking as a Service (BaaS) APIs, you get direct access to the same core infrastructure that powers millions of bunq accounts: real IBANs, payment rails, card issuing, and identity verification. No middleware, no workarounds — just clean REST APIs backed by a real bank. {% hint style="info" %} BaaS APIs are available to approved partners. [Get in touch](mailto:sales@bunq.com) to discuss access. {% endhint %} *** ### What you can build Whether you're embedding financial services into an existing product or building a fintech from the ground up, bunq BaaS gives you the building blocks to do it: * **KYC as a Service** — verify your users' identities using bunq's regulated onboarding flow, without building your own compliance infrastructure. * **Monetary Accounts** — open and manage euro bank accounts (with real IBANs) on behalf of your users, programmatically. * **Payments** — initiate SEPA credit transfers, handle incoming payments, and manage payment flows end-to-end. * **Cards** — issue and manage virtual and physical Mastercard debit cards linked to bunq accounts. *** ### How it works bunq BaaS is built on the same public bunq API that powers our consumer and business products. It uses standard REST over HTTPS, with signed requests for security. The key paradigm to understand is the **user hierarchy**: every account, card, and payment lives under a `user` object. When you use BaaS, you act on behalf of sub-users that your platform creates and manages — giving you full programmatic control while bunq handles the regulatory and banking layer underneath. Authentication follows the same installation → session pattern used across the bunq API. You'll set up your API credentials once, then use session tokens for all subsequent calls. For the full authentication flow, see [Basics → Getting Started](https://doc.bunq.com/basics). *** ### BaaS vs the standard bunq API | | Standard bunq API | BaaS | | ------------------ | ------------------------------------ | ----------------------------------------------- | | Use case | Automate your own bunq account | Build white label financial products for others | | User model | Your own bunq user | Sub-users managed by your platform | | KYC | bunq handles it for your account | You trigger it via API for your users | | Card issuing | Manage your own cards | Issue cards on behalf of sub-users | | Typical integrator | Developer, fintech, accountancy tool | Neobank, SaaS platform, marketplace | *** ### Next steps Pick the capability you want to integrate and follow the dedicated guide: {% content-ref url="/pages/w1uOfaXHLlimhRKx2d36" %} [Bank Accounts - As a Service](/banking-as-a-service/bank-accounts-as-a-service) {% endcontent-ref %} {% content-ref url="/pages/eiSPRVVyVUwjsvhGKt0A" %} [Cards - As a Service](/banking-as-a-service/cards-as-a-service) {% endcontent-ref %} {% content-ref url="/pages/axDXpXkhimhuhCDgGEyn" %} [Payments - As a Service](/banking-as-a-service/payments-as-a-service) {% endcontent-ref %} {% content-ref url="/pages/uNLOGz6ZH2eq7e0gb9wf" %} [Know Your Customer - As a Service](/banking-as-a-service/know-your-customer-as-a-service) {% endcontent-ref %} # Cards - As a Service ## Cards bunq's card issuing API lets you create and manage Mastercard debit cards linked directly to your users' monetary accounts. Cards work everywhere Mastercard is accepted — online, in-store, and in digital wallets. *** ### The paradigm In bunq, every card is linked to a monetary account. Spending on the card debits that account in real time. You control the card lifecycle — from creation and PIN management to spending limits, freezing, and cancellation — entirely through the API. bunq issues two card types: * **Virtual cards** — available immediately after creation, delivered as a card number, expiry, and CVC. Ideal for online purchases, subscriptions, and digital wallet provisioning. * **Physical cards** — shipped to the cardholder's address. Same API creation flow; delivery typically takes 5–7 business days within the EU. Key things to understand: * **One card, one account.** A card is always linked to exactly one monetary account. Changing the linked account is supported — useful if you want to redirect spending to a different balance. * **Spending limits.** You can set daily, weekly, or monthly spending limits per card via the API. You can also restrict the card to specific MCC (merchant category) codes. * **CVC2 generation.** For virtual cards, you generate a fresh CVC2 on demand via API. CVC2s are valid for a short window and regenerated each time — there is no stored static CVC. * **Freezing and unfreezing.** Cards can be frozen instantly via API (e.g. if a user reports it missing) and unfrozen just as quickly. * **Callbacks.** Register a notification filter to receive real-time events for authorisations, settlements, and declines. *** ### Flow overview **Issuing a virtual card:** ``` Your platform bunq API ───────────── ──────── POST /card-virtual → Creates card, returns PAN + expiry POST /generated-cvc2 → Returns a fresh CVC2 for the card ← Card ready for use ``` **Handling a transaction:** ``` Cardholder makes a purchase bunq API Your platform ────────────────────────── ──────── ───────────── Card presented at merchant → Authorisation → Callback: CARD_TRANSACTION_AUTHORISED → Your webhook Settlement (T+1) → Payment object created on account ``` *** ### Relevant API endpoints | Action | Endpoint | | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ | | Issue a virtual card | [`POST /v1/user/{userID}/card-virtual`](https://doc.bunq.com/api-reference/cards) | | List cards for a user | [`GET /v1/user/{userID}/card`](https://doc.bunq.com/api-reference/cards) | | Get card details | [`GET /v1/user/{userID}/card/{itemID}`](https://doc.bunq.com/api-reference/cards) | | Update card (limits, freeze, link account) | [`PUT /v1/user/{userID}/card/{itemID}`](https://doc.bunq.com/api-reference/cards) | | Generate a CVC2 | [`POST /v1/user/{userID}/card/{cardID}/generated-cvc2`](https://doc.bunq.com/api-reference/generated-cvc2) | | List card transactions | [`GET /v1/user/{userID}/monetary-account/{accountID}/mastercard-action`](https://doc.bunq.com/api-reference/mastercard-action) | | Register card callbacks | [`POST /v1/user/{userID}/notification-filter-url`](https://doc.bunq.com/api-reference/notification-filter-url) | *** ### Card object highlights The card object returned after creation includes: * `id` — your persistent reference for this card * `pan_link` — a link to the card's full PAN (fetched separately for PCI compliance reasons) * `expiry_date` — in `YYYY-MM` format * `status` — `ACTIVE`, `DEACTIVATED`, `SUSPENDED`, `EXPIRED` * `limit` — array of spending limit objects, each with `value`, `currency`, and `type` (daily/weekly/monthly) * `primary_account_number_four_digit` — last four digits, safe to display in your UI *** ### Common integration patterns **Pattern 1 — Instant virtual card per user.** Issue a virtual card at the end of KYC + account creation. The user gets a card they can add to Apple Pay / Google Pay immediately, without waiting for a physical card. **Pattern 2 — Expense cards with limits.** Issue cards to employees or contractors with a fixed monthly spending limit and MCC restrictions. Adjust limits dynamically as budgets change — no need to reissue the card. **Pattern 3 — Disposable cards.** Issue a virtual card for a single transaction or campaign, then cancel it. Eliminates the risk of recurring merchant charges or data exposure from a compromised PAN. **Pattern 4 — Freeze on suspicious activity.** Use your own fraud signals to freeze a card instantly via `PUT /card/{id}` with `status: SUSPENDED`. Unfreeze just as quickly once verified. Pair with transaction callbacks to act in near-real-time. *** {% hint style="info" %} Physical card orders require a verified postal address on the sub-user's profile. Make sure the user's address is set before calling the physical card creation endpoint. {% endhint %} {% hint style="info" %} CVC2 values must not be stored. Generate them on demand and display them directly to the cardholder. Storing CVC2s violates PCI DSS requirements. {% endhint %} # Payments - As a Service ## Payments Once a user has a verified monetary account, they can send and receive money on the SEPA network. bunq's payments API gives you full programmatic control over both sides of that flow. *** ### The paradigm Payments in bunq are always scoped to a monetary account. To initiate a payment, you specify the source account, the destination (an IBAN or bunq alias), the amount, and a description. bunq handles the routing — internal transfers between bunq accounts settle instantly; external SEPA payments follow standard rail timelines. Incoming payments arrive on the account's IBAN. Your integration receives them via callbacks and can query the transaction history at any time. Key things to understand: * **Payment types.** The `Payment` object covers both outgoing and incoming transfers. Filter by `type` (`IDEAL`, `SEPA`, `INTERNAL`, etc.) to distinguish them. * **Draft payments.** For flows that require a second approval step (e.g. a human signs off before money moves), use `DraftPayment`. The payment is created but not executed until explicitly confirmed. * **Batch payments.** You can send multiple payments in a single API call using `PaymentBatch`. Useful for payroll runs, mass payouts, or invoice settlements. * **Idempotency.** Use the `X-Bunq-Client-Request-Id` header to safely retry failed requests without risk of double payments. * **Callbacks.** Register a notification filter on the account to receive a webhook whenever a payment arrives or a payment status changes. *** ### Flow overview **Outgoing payment:** ``` Your platform bunq API ───────────── ──────── POST /payment → Validates and queues payment ← Payment object (status: PENDING) ← Callback: PAYMENT_CREATED / PAYMENT_EXECUTED ``` **Incoming payment:** ``` External sender bunq API Your platform ─────────────── ──────── ───────────── Sends SEPA to user's IBAN → Credits account → Callback: MUTATION → Your webhook GET /payment/{id} ← Full transaction detail ``` *** ### Relevant API endpoints | Action | Endpoint | | --------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | Send a payment | [`POST /v1/user/{userID}/monetary-account/{accountID}/payment`](https://doc.bunq.com/api-reference/payment) | | List payments (history) | [`GET /v1/user/{userID}/monetary-account/{accountID}/payment`](https://doc.bunq.com/api-reference/payment) | | Get a specific payment | [`GET /v1/user/{userID}/monetary-account/{accountID}/payment/{itemID}`](https://doc.bunq.com/api-reference/payment) | | Create a draft payment | [`POST /v1/user/{userID}/monetary-account/{accountID}/draft-payment`](https://doc.bunq.com/api-reference/draft-payment) | | Send a batch of payments | [`POST /v1/user/{userID}/monetary-account/{accountID}/payment-batch`](https://doc.bunq.com/api-reference/payment-batch) | | Register a payment callback | [`POST /v1/user/{userID}/notification-filter-url`](https://doc.bunq.com/api-reference/notification-filter-url) | *** ### Payment object highlights The payment response includes: * `amount` — object with `value` (string decimal) and `currency` * `counterparty_alias` — the other party's IBAN or bunq alias * `description` — the payment reference (appears on the recipient's statement) * `type` — payment rail used (`SEPA_CREDIT_TRANSFER`, `INTERNAL`, etc.) * `status` — current state (`PENDING`, `EXECUTED`, `REJECTED`, `REVERTED`) * `created` / `updated` — timestamps in `YYYY-MM-DD HH:MM:SS.SSSSSS` format *** ### Common integration patterns **Pattern 1 — Instant payouts.** Trigger a payment immediately when an event occurs in your platform (e.g. a gig worker completes a task). Use callbacks to confirm execution and update your own records. **Pattern 2 — Scheduled / batch payroll.** Collect payment instructions throughout the week, then fire a `PaymentBatch` on payday. Simpler to manage than individual calls and easier to reconcile. **Pattern 3 — Incoming payment reconciliation.** Each account has a unique IBAN. Assign one account per customer or invoice, so incoming payments self-identify by destination. Query the payment's `description` field for additional reference matching. **Pattern 4 — Two-step approval.** Use `DraftPayment` for high-value transactions that require a human review step before execution. Your platform surfaces the draft, an authorised user confirms it, and you send the confirmation via API. *** {% hint style="warning" %} Always store the `X-Bunq-Client-Request-Id` you send with each payment request. If a request times out, resubmit the same ID — bunq will deduplicate and return the original result rather than creating a second payment. {% endhint %} # Bank Accounts - As a Service ## Monetary Accounts A monetary account is the core object in the bunq data model. It's a real euro bank account with its own IBAN, capable of sending and receiving SEPA payments, holding a balance, and being linked to one or more cards. With bunq BaaS, you can open monetary accounts programmatically on behalf of your verified sub-users. Each account is a fully functional bank account — not a virtual ledger or a pre-paid balance, but a real account at a regulated Dutch bank. *** ### The paradigm Every monetary account belongs to a `user`. Before you can create an account for someone, that user must be KYC-verified (see [KYC as a Service](https://doc.bunq.com/banking-as-a-service/know-your-customer-as-a-service)). A single user can hold multiple monetary accounts — for example, a main account and a savings pot, or accounts in different currencies. Each account has its own IBAN and tracks its own transaction history. The main account type you'll use for BaaS is `MonetaryAccountBank` — a standard IBAN-bearing euro account. Key things to understand: * **IBANs are real.** Every `MonetaryAccountBank` gets a dedicated IBAN that works on all SEPA payment rails. Third parties can send money directly to your user's IBAN. * **Account status.** Accounts move through `PENDING`, `ACTIVE`, `CANCELLED`, and `CANCELLED_PENDING_SETTLEMENT` states. Most of your logic will act on `ACTIVE` accounts. * **Balance and transactions.** The balance and full transaction history are queryable at any time via the account ID. * **Limits.** Account limits (transaction volume, balance caps) are set at the BaaS agreement level. Contact your account manager to adjust them. *** ### Flow overview ``` Your platform bunq API ───────────── ──────── (KYC verified sub-user exists) POST /monetary-account-bank → Opens account, returns IBAN GET /monetary-account/{id} → Fetch balance and status GET /payment → List transactions on account ``` *** ### Relevant API endpoints | Action | Endpoint | | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | Create a bank account (IBAN) | [`POST /v1/user/{userID}/monetary-account-bank`](https://doc.bunq.com/monetary-account/monetary-account-bank) | | List all accounts for a user | [`GET /v1/user/{userID}/monetary-account`](https://doc.bunq.com/api-reference/monetary-account) | | Get a specific account | [`GET /v1/user/{userID}/monetary-account-bank/{itemID}`](https://doc.bunq.com/monetary-account/monetary-account-bank) | | Close / cancel an account | [`PUT /v1/user/{userID}/monetary-account-bank/{itemID}`](https://doc.bunq.com/monetary-account/monetary-account-bank) (set `status` to `CANCELLED`) | | Get account balance | Included in the account object — see `balance` field | | List transactions | [`GET /v1/user/{userID}/monetary-account/{accountID}/payment`](https://doc.bunq.com/api-reference/payment) | *** ### Account object highlights When you `GET` a monetary account, the response includes: * `iban` — the account's full IBAN (share this with your user or third parties for incoming payments) * `balance` — current balance object with `value` and `currency` * `status` — account lifecycle state * `display_name` — human-readable label you set at creation * `alias` — additional payment aliases (e.g. phone number, email) if configured *** ### Common integration patterns **Pattern 1 — One account per user.** The simplest model. Create one `MonetaryAccountBank` per verified sub-user. Works well for platforms where each user has a single wallet or balance. **Pattern 2 — Multiple accounts per user.** Create separate accounts for different purposes (e.g. "spending" vs "savings", or separate accounts per project/invoice). Users and your platform can move money between these accounts using internal transfers. **Pattern 3 — Shared or pooled accounts.** For marketplaces or escrow-like flows, a single account can receive funds from many parties. Use transaction metadata and callbacks to reconcile incoming payments to the correct source. *** {% hint style="info" %} Monetary account creation requires the sub-user to have `VERIFIED` KYC status. Attempting to create an account for an unverified user will return a `400` error. {% endhint %} # Know Your Customer - As a Service ## KYC as a Service Know Your Customer (KYC) is a regulatory requirement for any business that holds money or moves it on behalf of people. Building a compliant onboarding flow from scratch — identity document checks, liveness detection, sanctions screening, PEP lists — is expensive, slow, and requires maintaining your own compliance program. With bunq's KYC as a Service, you delegate that entire process to a regulated bank. bunq handles the verification, stores the compliance record, and issues a verified user that your platform can immediately act on. *** ### The paradigm When a new user signs up to your platform, you create a **sub-user** via the bunq API and kick off the KYC flow. bunq guides your user through identity verification (document upload + liveness check). Once verified, that user gets a bunq identity tied to your platform — ready to open accounts, receive payments, and use cards. You never handle raw identity documents. bunq does the regulated heavy lifting; you get a simple boolean: verified or not. Key things to understand: * **Sub-user model.** Each end-user on your platform maps to a bunq sub-user object. KYC status lives on that sub-user. * **Verification is asynchronous.** After initiating KYC, use a callback URL to receive the result rather than polling. * **Retries and failure states.** A user can fail verification (e.g. blurry document) and retry. Your integration should handle `PENDING`, `VERIFIED`, and `REJECTED` states. * **Regulatory scope.** bunq's KYC covers EU individuals. For corporate onboarding (KYB) or non-EU users, contact your bunq BaaS account manager. *** ### Flow overview ``` Your platform bunq API ───────────── ──────── POST /user → Creates sub-user shell POST /kyc-request → Triggers identity verification flow ← Callback: KYC_RESULT (VERIFIED / REJECTED) GET /user/{id} → Fetch verified user object ``` *** ### Relevant API endpoints | Action | Endpoint | | ----------------------------- | -------------------------------------------------------------------------------------------------------------- | | Create a sub-user | [`POST /v1/user`](https://doc.bunq.com/api-reference/user) | | Get user details / KYC status | [`GET /v1/user/{userID}`](https://doc.bunq.com/api-reference/user) | | Set a callback URL for events | [`POST /v1/user/{userID}/notification-filter-url`](https://doc.bunq.com/api-reference/notification-filter-url) | {% hint style="info" %} The full KYC initiation endpoint and request schema are available upon request. Contact your BaaS account manager for the specific endpoint path for your integration tier. {% endhint %} *** ### Callback payload When verification completes, bunq sends a `POST` to your registered callback URL. The payload includes the user ID, the new KYC status, and a timestamp. Always verify the `X-Bunq-Server-Signature` header before processing. *** ### Common integration patterns **Pattern 1 — Verify before account creation.** Gate monetary account creation on `VERIFIED` status. This is the safest approach and the most common for financial-product builders. **Pattern 2 — Optimistic onboarding.** Let users start a limited flow (e.g. receive a payment link) before full KYC, and upgrade their permissions once verified. Requires careful UX design to avoid confusing users about what they can and can't do yet. # Are you a Third Party Provider (TPP)? Start here! If you're a PSD2-certified third-party provider (TPP), you can integrate directly with the bunq Public API using your **eIDAS certificate**. This guide walks you through the step-by-step process to register and authenticate with the bunq environment. {% hint style="danger" %} PSD2 providers do **not** have access to the bunq Developers Portal. Integration is done entirely through API calls. {% endhint %} ### 🚀 What Do You Need to Integrate with bunq? Getting started with the bunq Public API is simple! Here’s what you’ll need to build, test, and simulate your integration from start to finish: {% hint style="info" %} If you get stuck or have questions, you can always reach out to [our support team](/support/api-support-team). We're here to help! {% endhint %} #### 🧪 Test Your Integration with Postman Want to explore the API before writing a single line of code? We’ve got you covered. Our official **Postman collection** lets you: * Send requests to any bunq endpoint * Simulate real API behavior * Inspect responses and debug easily * Automate tests as you go Perfect for learning the API or validating your integration logic. You can find more info here: {% content-ref url="/pages/N4PEtvluykQpcB57RnKI" %} [Postman](/getting-started/tools/postman) {% endcontent-ref %} #### 📱 Simulate User Behavior with Our APK Need to see how things work from a user’s perspective? Use our **bunq APK** to simulate real user actions like logging in, approving payments, or accepting requests. This is especially useful for: * End-to-end testing * Mimicking user approvals for DraftPayments or OAuth flows * Validating UX before going live Please check here how to use our Android APK: {% content-ref url="/pages/cTVOKghIW3JAaoiKgWSA" %} [Android Emulator](/getting-started/tools/android-emulator) {% endcontent-ref %} # Register as a TPP ## Register as a TPP This guide will walk you through the steps to register as a Third-Party Provider (TPP) with bunq. If you're a PSD2-certified company, you'll learn how to authenticate with the bunq API, register your certificate, and start using your credentials to access the data and services you're authorized for. Pre-Requisite You must generate a 2048-bit RSA key pair beforehand. You'll need your QSeal certificate (Qualified Seal Certificate), including intermediate and root certificate chain. OpenSSL and curl installed Basic knowledge of command line The easiest way to register is via command line, but you can also implement this in your code. If you're in a hurry and just want to test in the Sandbox environment. We bundled all commands on this page into 1 bash script that creates a PSD2 user and registers it for you. You'll just get an API key for that created user that you can use for the rest of your implementation Although a script provides you with a quick way to get started, we do recommend you read this page thorougly before moving into production. Link to script 🛠️ Step-by-Step Integration 1. Generate Installation Key Pair These keys are used to register your app installation with bunq: ## Public key: installation.pub ## Private key: installation.key openssl genrsa -out installation.key && openssl rsa -in installation.key -outform PEM -pubout -out installation.pub 2. (Sandbox only) Generate a test PSD2 Certificate The certificate is not validated in sandbox, so you can create as many as you need. Just make sure to use the qSEAL certificate when moving to production. Replace the subject /CN=.../C=... with your own details as needed. ## Certificate: psd2.cert ## Private key: psd2.key openssl req -x509 -newkey rsa:4096 -keyout psd2.key -out psd2.cert -days 365 -nodes -subj "/CN=Test PISP AISP $(uuidgen)/C=NL" 3. Create Installation This step registers your public key with bunq and returns an installation token. The client\_public\_key is the public part of the key pair you generated earlier using OpenSSL. This key is sent to bunq so we know how to verify future requests from your integration. What the API expects here is: A PEM-formatted public key (typically starting with -----BEGIN PUBLIC KEY----- and ending with -----END PUBLIC KEY-----) All line breaks and formatting preserved correctly as a single escaped string (so it fits into the JSON payload) Here's an example of a formatted public key: "-----BEGIN PUBLIC KEY-----\nMIIBITANBgkqhkiG9w0BAQEFAAOCAQ4AMIIBCQKCAQBKvVUm/gMi7NmTQImtpX1K\nTFMy3BQPvi6uYWMIIy/YHlZNGZbseKyo/dSa22VnFitjoJAt1S6iy04iuiYKCo4p\nUT9jNhn+JW7+U5Ptia6Y1yDwAqioeuL90suO6XLk35Vj7uuyXxlZO3u79/nPJrmp\nmYx2kEhEEISVWd9+TAFrFjImdGVd6DXK4d3D8/tH4GwILcmL7PbigbFLjeCVbkUi\nFqSiMgtQJkHVHhwedwLehuNg/oL3MRBw1bIxrYnjpO6qfyWoYNmCKYo3KgZYrQZ8\nVUjD0bpyfZEWX3+c849nemRdDa8eUZqjzneV2P/m96iiLWbve5KKSklSz2UtCecD\nAgMBAAE=\n-----END PUBLIC KEY-----\n" You can call the installation endpoint by using the following command line: INSTALLATION=$(curl -X POST
If you are a bunq user
#### What do I need to integrate bunq's API? To integrate with bunq's API, you'll need: * An **API key**, which you can generate from the bunq app. * A **public/private key pair** to securely sign requests. * To complete the **installation, device, and session setup** process to authenticate your API calls. The API uses standard REST principles and communicates via JSON. You can find setup guides and examples here: \ [bunq API documentation](https://doc.bunq.com/) #### What is PSD2? PSD2 (Payment Services Directive 2) is an EU regulation designed to make electronic payments more secure and to encourage innovation in financial services. It allows **licensed third-party providers (TPPs)**—such as fintech apps or financial aggregators—to access bank account information and initiate payments on behalf of users, with their explicit consent. In the context of the **bunq API**, PSD2 is especially relevant if you plan to: * Access **user account information** (AIS — Account Information Services) * Initiate **payments on a user’s behalf** (PIS — Payment Initiation Services) If you are a licensed TPP operating under PSD2, you can integrate with bunq using a **PSD2 certificate**. This grants you direct access to user accounts in a regulated and compliant way. Alternatively, if you're **not a licensed TPP**, but still want users to connect their bunq accounts to your app (for example, to show their balance or history), keep in mind that you might need a certification for those operations.If you are a PSD2 provider
#### **What certificate types does bunq accept?** We accept QSEAL certificates. #### **How do I get an API key as a PSD2 user?** You’ll receive a token in return to passing your QSEAL certificate. You’ll then be able to use it as an API key. #### **What do I need to register my QSEAL certificate?** You need to send a POST /payment-service-provider-credential request passing your QSEAL certificate, QSEAL certificate chain, and a signature of the device registration key with the QSEAL private key. Check the full authentication flow here. #### **How does the PSD2 API request signing work?** The request signature requirement is the same for all types of API users. You can read more about it here. #### **How do I get an OAuth client as a PSD2 user?** You can create an OAuth Client using `POST /user/userId/oauth-client` and read it using its id (`GET /user/userId/oauth-client/oauth-clientId`). Once you have it, you can add a redirect url using `POST /user/{userID}/oauth-client/{oauth-clientID}/callback-url`. From there, you can move to creating an authorization request and token exchange. Check more about it here: [OAuth](/basics/authentication/oauth) #### **Where do I find the AISP, PISP and CBPIII API reference?** bunq offers one API to both our users and companies with PSD2 permit:| Call | Needs in the header | Needs in the body | Returns |
|---|---|---|---|
| /installation | Nothing | The public key (generated by you) of your server | 1. installation token 2. public key of the server |
| /device-server | The installation token | the API key of your user and you server IP that will have access to bunq's API | A device ID |
| /session-server | Installation token | the API key of your user | Session token and user object |
1. Start the wizard by clicking on "+ Create Virtual Device". 2. Select a device (recommendation: "Pixel 5.0" or "Nexus 6") and press "Next". 3. Select an x86 system image (recommendation: Nougat, API Level 25, Android 7.1.1 with Google APIs) and press "Next". The image needs to have Google Play Services 10.0.1 or higher. 4. In the bottom left corner, select "Show Advanced Settings". 5. Scroll to "Memory and Storage". 6. Change "Internal Storage" to "2048 MB". 7. Change "SD card" to "200 MB". 8. Press "Finish".
{
"amount": {
"value": 10,
"currency": "EUR"
},
"counterparty_alias": {
"type": "EMAIL",
"value": "sugardaddy@bunq.com",
"name": "Sugar Daddy"
},
"description": "here is your money back"
}
```json { "pin_code": "1234", "card_limit": { "value": "100.00", "currency": "EUR" }, "card_limit_atm": { "value": "0.00", "currency": "EUR" } } ``` This sets our pincode to 1234 (assuming that's the code our friend wants). And we set the limit on the card to €100 , and €0 for ATM withdrawels so our friend does not grab a bunch of cash. If you want to change other values (e.g. allowed countries or the monetary account connected then we can but it's outside of the scope for this tutorial). ### Here is the the request with all parameters {% openapi src="/files/xJ3v0GinyfONRbxz8Srh" path="/user/{userID}/card/{itemId}" method="put" %} [swagger.json](https://346554585-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGE9Y1hc6C24r4Hen6KFH%2Fuploads%2Fgit-blob-218d6e618d396b5e315e30f903e92e143f7a4cc1%2Fswagger.json?alt=media) {% endopenapi %} ## Now Let's assume our friend made his card payment, how will we know? After our friend made his card payment we would like to revert back to our own spending limits and our own pin code. We can do this simply by redoing the API call we just did and updating the body. So ```json { "pin_code": "your pin code", "card_limit": { "value": "your preferred limit", "currency": "EUR" }, "card_limit_atm": { "value": "your ATM limit", "currency": "EUR" } } ``` The issue is more, how will we know when to make that call, as in the ideal situation for this tutorial we want to make it as soon as the card payment comes in. As with everything at bunq we can do this near instant. The crude way of doing it is by polling our payments with the GET [Payment](/payment)method, that returns a list of payments. There is a more sophisticated design pattern we could use which is using Callbacks. To set up callbacks we need to register a notification filter [Notification Filter](/notification-filter) ## Setting up a callback so we know when card transactions are made Your app can subscribe to events that happen on the bunq API by using [Callbacks (Webhooks)](/basics/callbacks-webhooks). These are POST requests our server will make towards your server when an event happens. One of the events we could listen to is `CARD_TRANSACTION_SUCCESSFUL` which will tell us about succesful card transactions. This is done by a POST request from bunq to a URL we specify (usually on our server). To do this we can add a callback url by adding a notification filter url. And passing a body like:
```json { "notification_filters": [ {"category": "CARD_TRANSACTION_SUCCESSFUL", "notification_target": "THE URL OF YOUR SERVER THAT WILL PROCESS THE POST REQUEST"} ] } ``` This registers the URL and now bunq will call that endpoint everytime there's a successful card transaction. Your server will have to to check the `card_id`in the event to match it to the card ID that we borrowed our friend. But if that matches you can simply make the API call that we did before, and revert to the pin\_code and card\_limits of your choice. And the card will be unusable by your friend after that. ## API Call and response for the notificiation filter {% openapi src="/files/xJ3v0GinyfONRbxz8Srh" path="/user/{userID}/notification-filter-url" method="post" %} [swagger.json](https://346554585-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGE9Y1hc6C24r4Hen6KFH%2Fuploads%2Fgit-blob-218d6e618d396b5e315e30f903e92e143f7a4cc1%2Fswagger.json?alt=media) {% endopenapi %} ### The response of such a callback looks like this: ] ``` { "NotificationUrl": { "target_url": "https://webhook.site/994964bb-7a4c-4be3-836a-da65231b907d", "category": "CARD_TRANSACTION_SUCCESSFUL", "event_type": "CARD_PAYMENT_ALLOWED", "object": { "MasterCardAction": { "id": 491965, "created": "2025-04-09 14:14:27.584029", "updated": "2025-04-09 14:14:28.483979", "monetary_account_id": 2078790, "card_id": 449304, "card_authorisation_id_response": "FHF728", "amount_local": { "currency": "EUR", "value": "1.00" }, "amount_converted": { "currency": "EUR", "value": "1.00" }, "amount_billing": { "currency": "EUR", "value": "1.00" }, "amount_original_local": { "currency": "EUR", "value": "1.00" }, "amount_original_billing": { "currency": "EUR", "value": "1.00" }, "amount_fee": { "currency": "EUR", "value": "0.00" }, "decision": "ALLOWED", "payment_status": "PAYMENT_SUCCESSFUL_PENDING_SETTLEMENT", "decision_description": "Card transaction is successfully authorised. Your money has been reserved for the merchant to claim.", "decision_description_translated": "Card transaction is successfully authorized. Your money has been reserved for the merchant to claim.", "decision_together_url": "https://together.bunq.com/d/16793-what-does-the-status-of-my-card-payment-mean", "description": "CCV*KA Sloterdijk Amsterdam, NL\n", "authorisation_status": "AUTHORISED", "authorisation_type": "NORMAL_AUTHORISATION", "settlement_status": "OPEN", "clearing_status": "PENDING", "maturity_date": "2025-05-01", "city": "Amsterdam", "alias": { "iban": "NL52BUNQ2090374640", "is_light": false, "display_name": "A. Luu", "avatar": { "uuid": "27234277-30d4-46c8-80cf-d975a6c6b21d", "image": [ { "attachment_public_uuid": "60a6d2d5-5080-4c02-a2b6-52c8beeafd56", "height": 1023, "width": 1024, "content_type": "image/png", "urls": [ { "type": "ORIGINAL", "url": "https://bunq-triage-model-storage-public.s3.eu-central-1.amazonaws.com/bunq_file/File/content/921ece497cd00f4e0cef3f0f63a962c31cf3f8e35311d127d5a7b23be3d074d5.png" } ] } ], "anchor_uuid": null, "style": "NONE" }, "label_user": { "uuid": "a3f43087-9139-47ec-9453-0609afc0dbdd", "display_name": "A. Luu", "country": "NL", "avatar": { "uuid": "9debf55b-70b1-4d43-8d51-d6e7bd42fb5b", "image": [ { "attachment_public_uuid": "4b7e0d1d-9167-48ac-990a-70e342c87812", "height": 126, "width": 200, "content_type": "image/jpeg", "urls": [ { "type": "ORIGINAL", "url": "https://bunq-triage-model-storage-public.s3.eu-central-1.amazonaws.com/bunq_file/File/content/6979a145b7ea9ecc3459358122cb560608f02d36d4b8cd6b770f50e36aa35512.jpg" } ] } ], "anchor_uuid": "a3f43087-9139-47ec-9453-0609afc0dbdd", "style": "EASY_GREEN" }, "public_nick_name": "Ada", "type": "PERSON" }, "country": "NL" }, "counterparty_alias": { "iban": null, "is_light": null, "display_name": "Koffie Academie", "avatar": null, "label_user": { "uuid": null, "display_name": "Koffie Academie", "country": "NL", "avatar": null, "public_nick_name": "Koffie Academie", "type": null }, "country": "NL", "merchant_category_code": "5411" }, "label_card": { "uuid": "dee4bf0a-8f9c-4387-be82-db0b4d02c4d5", "type": "MASTERCARD", "second_line": "", "expiry_date": "2029-04-30", "status": "ACTIVE", "label_user": { "uuid": "a3f43087-9139-47ec-9453-0609afc0dbdd", "display_name": "Ada", "country": "000", "avatar": { "uuid": "9debf55b-70b1-4d43-8d51-d6e7bd42fb5b", "image": [ { "attachment_public_uuid": "4b7e0d1d-9167-48ac-990a-70e342c87812", "height": 126, "width": 200, "content_type": "image/jpeg", "urls": [ { "type": "ORIGINAL", "url": "https://bunq-triage-model-storage-public.s3.eu-central-1.amazonaws.com/bunq_file/File/content/6979a145b7ea9ecc3459358122cb560608f02d36d4b8cd6b770f50e36aa35512.jpg" } ] } ], "anchor_uuid": "a3f43087-9139-47ec-9453-0609afc0dbdd", "style": "EASY_GREEN" }, "public_nick_name": "Ada", "type": "PERSON" }, "label_user_owner": { "uuid": "a3f43087-9139-47ec-9453-0609afc0dbdd", "display_name": "Ada", "country": "000", "avatar": { "uuid": "9debf55b-70b1-4d43-8d51-d6e7bd42fb5b", "image": [ { "attachment_public_uuid": "4b7e0d1d-9167-48ac-990a-70e342c87812", "height": 126, "width": 200, "content_type": "image/jpeg", "urls": [ { "type": "ORIGINAL", "url": "https://bunq-triage-model-storage-public.s3.eu-central-1.amazonaws.com/bunq_file/File/content/6979a145b7ea9ecc3459358122cb560608f02d36d4b8cd6b770f50e36aa35512.jpg" } ] } ], "anchor_uuid": "a3f43087-9139-47ec-9453-0609afc0dbdd", "style": "EASY_GREEN" }, "public_nick_name": "Ada", "type": "PERSON" }, "label_user_holder": { "uuid": "a3f43087-9139-47ec-9453-0609afc0dbdd", "display_name": "A. Luu", "country": "NL", "avatar": { "uuid": "9debf55b-70b1-4d43-8d51-d6e7bd42fb5b", "image": [ { "attachment_public_uuid": "4b7e0d1d-9167-48ac-990a-70e342c87812", "height": 126, "width": 200, "content_type": "image/jpeg", "urls": [ { "type": "ORIGINAL", "url": "https://bunq-triage-model-storage-public.s3.eu-central-1.amazonaws.com/bunq_file/File/content/6979a145b7ea9ecc3459358122cb560608f02d36d4b8cd6b770f50e36aa35512.jpg" } ] } ], "anchor_uuid": "a3f43087-9139-47ec-9453-0609afc0dbdd", "style": "EASY_GREEN" }, "public_nick_name": "Ada", "type": "PERSON" }, "label_primary_account_number": { "uuid": "d1e42007-a01e-497a-a88d-c40ca7abf154", "description": "", "last_four_digit": "8069", "mastercard_product": "MCS" } }, "merchant_id": "21914428", "token_status": null, "reservation_expiry_time": null, "clearing_expiry_time": "2025-04-16 14:14:27.584029", "pan_entry_mode_user": "ICC", "secure_code_id": null, "wallet_provider_id": "420", "request_reference_split_the_bill": [], "card_tokenization_event": null, "all_auto_save_entry": [], "all_mastercard_action_refund": [], "applied_limit": "CARD_LIMIT_POS_ICC", "tree": null, "pos_card_presence": "0", "pos_card_holder_presence": "0", "eligible_whitelist_id": null, "cashback_payout_item": null, "point_mutation": { "id": 203039, "created": "2025-04-09 14:14:29.755610", "updated": "2025-04-09 14:14:29.755610", "number_of_point": 2 }, "blacklist": null, "transaction_dispute_available": "NONE", "additional_authentication_status": "NONE", "pin_status": "VALID_ONLINE", "mastercard_action_report": null, "merchant_category_code": "5411", "company_employee_card_receipt": null } } } } ``` # Access end user acount information through OAuth ### Goal of this tutorial In this tutorial we'll walk you through the steps to get access to a bunq users bank account. We'll register your application, create a OAuth client and set it up in such a way so that: * You can generate a QR code - this QR code can be used by a bunq user to connect to the app you're building * How to set up that connection between the bunq user and your app * Retrieve end-user information For OAuth to work there are 3 parties involved * The bunq user - that is likely also a user of your app * Your app - that is trying to access information about the end users' bunq account * bunq - which stores all the information in our database and that your app wants to access on behalf of a end user. {% hint style="info" %} A common example for a usecase with oauth is if your app is an accounting tool. You want to be able to read transactions on the account of the end user. Connecting through oauth helps you get this set up. {% endhint %} At the end of this tutorial you'll have: * An app with oauth client * A way to retrieve payments on behalf of other users ### What is OAuth OAuth 2.0 is an industry-standard protocol that allows third-party applications to securely access bunq user accounts without exposing credentials. This method enables seamless authorization while maintaining user control over permissions.6 {% hint style="danger" %} **Important Note** If you, as a developer, intend to access data belonging to **other bunq users** (e.g., account information, transaction history, or initiate payments on their behalf), you must ensure that you: * ✅ **Fully comply with** [**bunq’s Terms and Conditions**](https://static.bunq.com/framer/documents/Terms-Conditions-API-EN-20200805.pdf) for API usage. * ✅ **Obtain explicit user consent** as required. * ⚖️ **May be subject to** [**PSD2 regulations**](https://eur-lex.europa.eu/legal-content/EN/LSU/?uri=oj:JOL_2015_337_R_0002), including registration as an AISP (Account Information Service Provider) or PISP (Payment Initiation Service Provider) with your national competent authority. Misuse or non-compliance may lead to access being revoked or legal consequences. ### {% endhint %} ### What is next Next up we'll get started with setting up the OAuth client. # Setting up the Oauth Client For this tutorial we want to read the transactions on behalf of a end user. Te first thing we need to do is register a oauth client. There are 2 ways to do this and we'll dive into both of them. In this chapter we try to register the client and retrieve the client ID and Client Secret that belong to your oauth client. ## 1. Register oauth client as a bunq user If you have access to a bunq account then it's fairly straight forward to set up an oauth client. You can simply retrieve your oauth client ID and Secret from the bunq app. This is also the easiest way to set up a redirect URL (More on this later).
Screen in bunq app where you can set up your oauth client
{% endhint %}
## 2. Register as a PSD2 user
In some cases you may not be a bunq user yourself but still want access to bunq user data. For instance when you're a PSD2-certified third-party provider (TPP), you can integrate directly with the bunq Public API using your **eIDAS certificate**.
This guide walks you through the step-by-step process to register and authenticate with the bunq environment.
This method to register a oauth client may not be applicable to you, if you're unsure refer to [PSD2](/psd2/are-you-a-third-party-provider-tpp-start-here). and [Are you a Third Party Provider (TPP)? Start here!](/psd2/are-you-a-third-party-provider-tpp-start-here) # Hidden references # Company {% openapi src="