Geolocations

Overview

The bunq API allows you to attach a geolocation to a payment using the X-Bunq-Geolocation request header. This metadata can then be queried later via payment-related endpoints.

Adding Geolocation to a Payment

To include geolocation data with a payment, set the X-Bunq-Geolocation header when making a payment request.

Header format

X-Bunq-Geolocation: {latitude} {longitude} {altitude} {radius} {country}

Example:

X-Bunq-Geolocation: 52.0907 5.1214 0 50 NL

Field	Type	Description
latitude	float	Latitude in decimal degrees
longitude	float	Longitude in decimal degrees
altitude	float	Altitude in meters (can be 0)
radius	float	Accuracy radius in meters
country	string	2-letter ISO country code (e.g. NL)

Example: Creating a Payment with Geolocation

POST /v1/user/{userID}/monetary-account/{monetaryAccountID}/payment

Headers:
X-Bunq-Geolocation: 52.0907 5.1214 0 50 NL


Body:
{
  "amount": {
    "currency": "EUR",
    "value": "10.00"
  },
  "counterparty_alias": {
    "type": "EMAIL",
    "value": "[email protected]"
  },
  "description": "Lunch"
}

---

Retrieving Payments with Geolocation

Geolocation is attached to:

• /payment

• /draft-payment

• /mastercard-action

To fetch this metadata:

GET /v1/user/{userID}/monetary-account/{monetaryAccountID}/payment/{paymentID}

Response (excerpt)

Payments that do have a location will have a geolocation property filled like so:

{
  "payment": {
    "description": "Lunch",
    ...
    "geolocation": {
      "latitude": 52.3676,
      "longitude": 4.9041,
      "altitude": 0,
      "radius": 30
    }
  }
}

🧠 Only payments made with the geolocation header will include this metadata.

---

Limitations

• There is no API to retrieve the current geolocation of a user.

• There is no geolocation API. You'll have to collect all payments and filter in your own implementation for payments and locations you're interested in

• Geolocation is only stored at the time of certain actions (e.g. making a payment). bunq only adds the geolocation to payments where it is available. So account for the field missing even on payments made by bunq.