> For the complete documentation index, see [llms.txt](https://doc.bunq.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.bunq.com/token-qr-request-ideal.md).

# Token QR Request iDeal

Use this endpoint to initiate an outgoing iDEAL payment from a bunq user's account. The user presents a token obtained from an iDEAL merchant website or QR code, and bunq creates a payment request on their behalf.

### Endpoint

```
POST /v1/user/{userID}/token-qr-request-ideal
```

### Request body

| Field   | Type   | Required | Description                                                   |
| ------- | ------ | -------- | ------------------------------------------------------------- |
| `token` | string | Yes      | The iDEAL token obtained from the merchant website or QR code |

### Response

Returns a `RequestResponse` object with:

| Field              | Description                    |
| ------------------ | ------------------------------ |
| `status`           | Always `PENDING` on creation   |
| `amount_responded` | The payment amount             |
| `redirect_url`     | URL to complete the iDEAL flow |
| `time_expiry`      | Token expiry timestamp         |

### How it works

1. bunq validates the token — it must be active, unexpired, and of type `IDEAL`
2. bunq selects the appropriate account for the payment (standard, light, or joint account in the correct currency)
3. The iDEAL transaction is assigned to the user
4. The token is marked as used
5. A payment request is created and returned with status `PENDING`

The user then completes the payment by following the `redirect_url`.

### Important notes

**Single-use tokens** — each token can only be used once. A second attempt with the same token returns an error: `Token was used previously and cannot be used again.`

**Account requirements** — the bunq user must have a standard, light, or joint account in the correct currency. Savings accounts cannot be used for iDEAL payments.

**Token expiry** — tokens expire after a set period. An expired token cannot be used and returns a not found error.

### Next step

After creating the request, accept it using the `request-response` endpoint:

```
PUT /v1/user/{userID}/monetary-account/{monetary-accountID}/request-response/{itemID}
```

Set `status` to `ACCEPTED` to confirm the payment.

## POST /user/{userID}/token-qr-request-ideal

> Create a request from an ideal transaction.

```json
{"openapi":"3.0.0","info":{"title":"bunq API","version":"1.0"},"tags":[{"name":"token-qr-request-ideal","description":""}],"servers":[{"url":"https://public-api.sandbox.bunq.com/{basePath}","description":"Sandbox server","variables":{"basePath":{"default":"v1"}}},{"url":"https://api.bunq.com/{basePath}","description":"Production server","variables":{"basePath":{"default":"v1"}}}],"paths":{"/user/{userID}/token-qr-request-ideal":{"post":{"tags":["token-qr-request-ideal"],"summary":"","operationId":"CREATE_TokenQrRequestIdeal_for_User","description":"Create a request from an ideal transaction.","parameters":[{"in":"path","name":"userID","description":"","required":true,"schema":{"type":"integer"}},{"$ref":"#/components/parameters/Cache-Control"},{"$ref":"#/components/parameters/User-Agent"},{"$ref":"#/components/parameters/X-Bunq-Language"},{"$ref":"#/components/parameters/X-Bunq-Region"},{"$ref":"#/components/parameters/X-Bunq-Client-Request-Id"},{"$ref":"#/components/parameters/X-Bunq-Geolocation"},{"$ref":"#/components/parameters/X-Bunq-Client-Authentication"}],"requestBody":{"description":"","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenQrRequestIdeal"}}}},"responses":{"200":{"description":"Using this call you create a request for payment from an external token provided with an ideal transaction. Make sure your iDEAL payments are compliant with the iDEAL standards, by following the following manual: https:/www.bunq.com/terms-idealstandards. It's very important to keep these points in mind when you are using the endpoint to make iDEAL payments from your application.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenQrRequestIdealCreate"}}},"headers":{"X-Bunq-Client-Response-Id":{"$ref":"#/components/headers/X-Bunq-Client-Response-Id"},"X-Bunq-Client-Request-Id":{"$ref":"#/components/headers/X-Bunq-Client-Request-Id"},"X-Bunq-Server-Signature":{"$ref":"#/components/headers/X-Bunq-Server-Signature"}}},"400":{"$ref":"#/components/responses/GenericError"}}}}},"components":{"parameters":{"Cache-Control":{"description":"The standard HTTP Cache-Control header is required for all signed requests.","schema":{"type":"string"},"required":false,"in":"header","name":"Cache-Control"},"User-Agent":{"description":"The User-Agent header field should contain information about the user agent originating the request. There are no restrictions on the value of this header.","schema":{"type":"string"},"required":true,"in":"header","name":"User-Agent"},"X-Bunq-Language":{"description":"The X-Bunq-Language header must contain a preferred language indication. The value of this header is formatted as a ISO 639-1 language code plus a ISO 3166-1 alpha-2 country code, separated by an underscore. Currently only the languages en_US and nl_NL are supported. Anything else will default to en_US.","schema":{"type":"string"},"required":false,"in":"header","name":"X-Bunq-Language"},"X-Bunq-Region":{"description":"The X-Bunq-Region header must contain the region (country) of the client device. The value of this header is formatted as a ISO 639-1 language code plus a ISO 3166-1 alpha-2 country code, separated by an underscore.","schema":{"type":"string"},"required":false,"in":"header","name":"X-Bunq-Region"},"X-Bunq-Client-Request-Id":{"description":"This header must specify an ID with each request that is unique for the logged in user. There are no restrictions for the format of this ID. However, the server will respond with an error when the same ID is used again on the same DeviceServer.","schema":{"type":"string"},"required":false,"in":"header","name":"X-Bunq-Client-Request-Id"},"X-Bunq-Geolocation":{"description":"This header must specify the geolocation of the device. The format of this value is longitude latitude altitude radius country. The country is expected to be formatted of an ISO 3166-1 alpha-2 country code. When no geolocation is available or known the header must still be included but can be zero valued.","schema":{"type":"string"},"required":false,"in":"header","name":"X-Bunq-Geolocation"},"X-Bunq-Client-Authentication":{"description":"The authentication token is used to authenticate the source of the API call. It is required by all API calls except for POST /v1/installation. It is important to note that the device and session calls are using the token from the response of the installation call, while all the other calls use the token from the response of the session-server call","schema":{"type":"string"},"required":true,"in":"header","name":"X-Bunq-Client-Authentication"}},"schemas":{"TokenQrRequestIdeal":{"type":"object","properties":{"token":{"type":"string","description":"The token passed from a site or read from a QR code.","readOnly":false,"writeOnly":true}},"required":["token"]},"TokenQrRequestIdealCreate":{"type":"object","properties":{"id":{"type":"integer","description":"The id of the RequestResponse.","readOnly":true,"writeOnly":false},"time_responded":{"type":"string","description":"The timestamp of when the RequestResponse was responded to.","readOnly":true,"writeOnly":false},"time_expiry":{"type":"string","description":"The timestamp of when the RequestResponse expired or will expire.","readOnly":true,"writeOnly":false},"monetary_account_id":{"type":"integer","description":"The id of the MonetaryAccount the RequestResponse was received on.","readOnly":true,"writeOnly":false},"amount_inquired":{"type":"object","description":"The requested Amount.","readOnly":true,"writeOnly":false,"$ref":"#/components/schemas/Amount"},"amount_responded":{"type":"object","description":"The Amount the RequestResponse was accepted with.","readOnly":true,"writeOnly":false,"$ref":"#/components/schemas/Amount"},"alias":{"type":"object","description":"The LabelMonetaryAccount with the public information of the MonetaryAccount this RequestResponse was received on.","readOnly":true,"writeOnly":false,"$ref":"#/components/schemas/LabelMonetaryAccount"},"counterparty_alias":{"type":"object","description":"The LabelMonetaryAccount with the public information of the MonetaryAccount that is requesting money with this RequestResponse.","readOnly":true,"writeOnly":false,"$ref":"#/components/schemas/LabelMonetaryAccount"},"description":{"type":"string","description":"The description for the RequestResponse provided by the requesting party. Maximum 9000 characters.","readOnly":true,"writeOnly":false},"attachment":{"type":"array","description":"The Attachments attached to the RequestResponse.","readOnly":true,"writeOnly":false,"items":{"$ref":"#/components/schemas/Attachment"}},"status":{"type":"string","description":"The status of the created RequestResponse. Can only be PENDING.","readOnly":true,"writeOnly":false},"minimum_age":{"type":"integer","description":"The minimum age the user accepting the RequestResponse must have.","readOnly":true,"writeOnly":false},"require_address":{"type":"string","description":"Whether or not an address must be provided on accept.","readOnly":true,"writeOnly":false},"address_shipping":{"type":"object","description":"The shipping address provided by the accepting user if an address was requested.","readOnly":true,"writeOnly":false,"$ref":"#/components/schemas/Address"},"address_billing":{"type":"object","description":"The billing address provided by the accepting user if an address was requested.","readOnly":true,"writeOnly":false,"$ref":"#/components/schemas/Address"},"geolocation":{"type":"object","description":"The Geolocation where the RequestResponse was created.","readOnly":true,"writeOnly":false,"$ref":"#/components/schemas/Geolocation"},"redirect_url":{"type":"string","description":"The URL which the user is sent to after accepting or rejecting the Request.","readOnly":true,"writeOnly":false},"type":{"type":"string","description":"The type of the RequestResponse. Can be only be IDEAL.","readOnly":true,"writeOnly":false},"sub_type":{"type":"string","description":"The subtype of the RequestResponse. Can be only be NONE.","readOnly":true,"writeOnly":false},"eligible_whitelist_id":{"type":"integer","description":"The whitelist id for this action or null.","readOnly":true,"writeOnly":false}}},"Amount":{"type":"object","properties":{"value":{"type":"string","description":"The amount formatted to two decimal places.","readOnly":false,"writeOnly":false},"currency":{"type":"string","description":"The currency of the amount. It is an ISO 4217 formatted currency code.","readOnly":false,"writeOnly":false}}},"LabelMonetaryAccount":{"type":"object","properties":{"iban":{"type":"string","description":"The IBAN of the monetary account.","readOnly":true,"writeOnly":false},"display_name":{"type":"string","description":"The name to display with this monetary account.","readOnly":true,"writeOnly":false},"avatar":{"type":"object","description":"The avatar of the monetary account.","readOnly":true,"writeOnly":false,"$ref":"#/components/schemas/Avatar"},"label_user":{"type":"object","description":"The user this monetary account belongs to.","readOnly":true,"writeOnly":false,"$ref":"#/components/schemas/LabelUser"},"country":{"type":"string","description":"The country of the user. Formatted as a ISO 3166-1 alpha-2 country code.","readOnly":true,"writeOnly":false},"bunq_me":{"type":"object","description":"Bunq.me pointer with type and value.","readOnly":true,"writeOnly":false,"$ref":"#/components/schemas/Pointer"},"is_light":{"type":"boolean","description":"Whether or not the monetary account is light.","readOnly":true,"writeOnly":false},"swift_bic":{"type":"string","description":"The BIC used for a SWIFT payment.","readOnly":true,"writeOnly":false},"swift_account_number":{"type":"string","description":"The account number used for a SWIFT payment. May or may not be an IBAN.","readOnly":true,"writeOnly":false},"transferwise_account_number":{"type":"string","description":"The account number used for a Transferwise payment. May or may not be an IBAN.","readOnly":true,"writeOnly":false},"transferwise_bank_code":{"type":"string","description":"The bank code used for a Transferwise payment. May or may not be a BIC.","readOnly":true,"writeOnly":false},"merchant_category_code":{"type":"string","description":"The merchant category code.","readOnly":true,"writeOnly":false}}},"Avatar":{"type":"object","properties":{"uuid":{"type":"string","description":"The public UUID of the avatar.","readOnly":false,"writeOnly":false},"anchor_uuid":{"type":"string","description":"The public UUID of object this avatar is anchored to.","readOnly":true,"writeOnly":false},"image":{"type":"array","description":"The actual image information of this avatar.","readOnly":true,"writeOnly":false,"items":{"$ref":"#/components/schemas/Image"}},"style":{"type":"string","description":"The style (if applicable) for this Avatar.","readOnly":true,"writeOnly":false}}},"Image":{"type":"object","properties":{"attachment_public_uuid":{"type":"string","description":"The public UUID of the public attachment containing the image.","readOnly":true,"writeOnly":false},"content_type":{"type":"string","description":"The content-type as a MIME filetype.","readOnly":true,"writeOnly":false},"height":{"type":"integer","description":"The image height in pixels.","readOnly":true,"writeOnly":false},"width":{"type":"integer","description":"The image width in pixels.","readOnly":true,"writeOnly":false}}},"LabelUser":{"type":"object","properties":{"uuid":{"type":"string","description":"The public UUID of the label-user.","readOnly":false,"writeOnly":false},"display_name":{"type":"string","description":"The name to be displayed for this user, as it was given on the request.","readOnly":false,"writeOnly":false},"country":{"type":"string","description":"The country of the user. 000 stands for \"unknown\"","readOnly":false,"writeOnly":false},"avatar":{"type":"object","description":"The current avatar of the user.","readOnly":true,"writeOnly":false,"$ref":"#/components/schemas/Avatar"},"public_nick_name":{"type":"string","description":"The current nickname of the user.","readOnly":true,"writeOnly":false}}},"Pointer":{"type":"object","properties":{"type":{"type":"string","description":"The alias type, can be: EMAIL|PHONE_NUMBER|IBAN.","readOnly":false,"writeOnly":false},"value":{"type":"string","description":"The alias value.","readOnly":false,"writeOnly":false},"name":{"type":"string","description":"The alias name.","readOnly":false,"writeOnly":false},"service":{"type":"string","description":"The pointer service. Only required for external counterparties.","readOnly":false,"writeOnly":true}}},"Attachment":{"type":"object","properties":{"description":{"type":"string","description":"The description of the attachment.","readOnly":true,"writeOnly":false},"content_type":{"type":"string","description":"The content type of the attachment's file.","readOnly":true,"writeOnly":false},"urls":{"type":"array","description":"The URLs where the file can be downloaded.","readOnly":true,"writeOnly":false,"items":{"$ref":"#/components/schemas/AttachmentUrl"}}}},"AttachmentUrl":{"type":"object","properties":{"type":{"type":"string","description":"The file type of attachment.","readOnly":true,"writeOnly":false},"url":{"type":"string","description":"The URL where the attachment can be downloaded.","readOnly":true,"writeOnly":false}}},"Address":{"type":"object","properties":{"street":{"type":"string","description":"The street.","readOnly":false,"writeOnly":false},"house_number":{"type":"string","description":"The house number.","readOnly":false,"writeOnly":false},"po_box":{"type":"string","description":"The PO box.","readOnly":false,"writeOnly":false},"postal_code":{"type":"string","description":"The postal code.","readOnly":false,"writeOnly":false},"city":{"type":"string","description":"The city.","readOnly":false,"writeOnly":false},"country":{"type":"string","description":"The country as an ISO 3166-1 alpha-2 country code.","readOnly":false,"writeOnly":false},"extra":{"type":"string","description":"The apartment, building or other extra information for addresses.","readOnly":false,"writeOnly":false},"mailbox_name":{"type":"string","description":"The name on the mailbox (only used for Postal and Shipping addresses).","readOnly":false,"writeOnly":false},"province":{"type":"string","description":"The province according to local standard.","readOnly":true,"writeOnly":false},"is_user_address_updated":{"type":"boolean","description":"To show whether user created or updated her address for app event listing.","readOnly":true,"writeOnly":false}}},"Geolocation":{"type":"object","properties":{"latitude":{"type":"integer","description":"The latitude for a geolocation restriction.","readOnly":false,"writeOnly":false},"longitude":{"type":"integer","description":"The longitude for a geolocation restriction.","readOnly":false,"writeOnly":false},"altitude":{"type":"integer","description":"The altitude for a geolocation restriction.","readOnly":false,"writeOnly":false},"radius":{"type":"integer","description":"The radius for a geolocation restriction.","readOnly":false,"writeOnly":false}}},"Error":{"type":"array","items":{"type":"object","properties":{"error_description":{"type":"string","description":"The error description in English."},"error_description_translated":{"type":"string","description":"The error description translated to the user's language."}}}}},"headers":{"X-Bunq-Client-Response-Id":{"description":"A unique ID for the response formatted as a UUID. Clients can use it to add extra protection against replay attacks.","schema":{"type":"string"}},"X-Bunq-Client-Request-Id":{"description":"This header must specify an ID with each request that is unique for the logged in user. There are no restrictions for the format of this ID. However, the server will respond with an error when the same ID is used again on the same DeviceServer.","schema":{"type":"string"},"required":false},"X-Bunq-Server-Signature":{"description":"The server's signature for this response. See the signing page for details on how to verify this signature.","schema":{"type":"string"}}},"responses":{"GenericError":{"description":"This is how the error response looks like for 4XX response codes","headers":{"X-Bunq-Client-Response-Id":{"$ref":"#/components/headers/X-Bunq-Client-Response-Id"},"X-Bunq-Client-Request-Id":{"$ref":"#/components/headers/X-Bunq-Client-Request-Id"},"X-Bunq-Server-Signature":{"$ref":"#/components/headers/X-Bunq-Server-Signature"}},"content":{"application/json":{"schema":{"type":"object","properties":{"Error":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://doc.bunq.com/token-qr-request-ideal.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.