Payment Service Provider Issuer Transaction
The Payment Service Provider Issuer Transaction enables you to initiate a payment to any bank account of your choice. This feature is particularly useful if you want to allow bunq users to pay directly through your platform while providing a seamless, branded experience via a bunq-hosted payment portal—without relying on third-party payment providers.
The typical flow works as follows:
Create the payment You start by sending a POST request to the endpoint, including essential details such as the payment amount, a redirect URL, and the counterparty information. This request sets up the payment and its parameters in the bunq system.
Receive the payment ID The response will include a unique ID for the transaction. This ID allows you to retrieve the full details of the payment at any time using a GET request.
Retrieve the public UUID From the payment details response, you should capture the
public_uuid. This identifier is necessary to generate the direct link to the bunq payment portal.Redirect your user Once you have the
public_uuid, you can redirect your users to the payment portal using the following URL structure:
For sandbox use:
https://psp.triage.bunq.com/?transactionId=<public_uuid>For Production
https://psp.bunq.com/?transactionId=<public_uuid>This portal provides a secure and user-friendly interface for completing the payment.
Handle post-payment After the user completes the payment, they will be redirected to the URL you specified in the original request. You can then make another GET request to fetch the latest status and details of the payment, such as the payer information, payment status, and any other metadata.
This flow ensures that payments are both secure and easy to integrate into your platform, giving your users a smooth and reliable experience from initiation to completion.
This is the body you'll POST notice the expiry time
{
"counterparty_alias": {
"type": "IBAN",
"value": "NL52BUNQ2090374640",
"name": "Jacob Bell"
},
"amount": {
"value": "10.00",
"currency": "EUR"
},
"description": "Payment description",
"url_redirect": "https://yourapp.com/redirect",
"time_expiry": "2025-08-15 14:07:01.397234",
"status": "PENDING"
}
This is the object you'll get returned when you do the GET request
"Response": {
"PaymentServiceProviderIssuerTransaction": {
"id": 450,
"created": "2025-08-15 13:57:11.163840",
"updated": "2025-08-15 14:07:31.409463",
"public_uuid": "7ee2dd93-9792-4faf-95a7-812bdf4b5961",
"counterparty_alias": {
"iban": "NL52BUNQ2090374640",
"is_light": false,
"display_name": "Jacob Bell",
"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": null,
"display_name": "peter van doorn",
"country": "NL",
"avatar": null,
"public_nick_name": "peter van doorn",
"type": null
},
"country": "NL"
},
"amount": {
"currency": "EUR",
"value": "10.00"
},
"description": "Payment description",
"url_redirect": "https://yourapp.com/redirect",
"time_expiry": "2025-08-15 14:07:01.397234",
"status": "EXPIRED",
"alias": null
}
}
}
The endpoint for payment service provider issuer transactions
The standard HTTP Cache-Control header is required for all signed requests.
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.
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.
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.
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.
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.
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
The description of this transaction, to be shown to the user and to the counter party.
The url to which the user should be redirected once the transaction is accepted or rejected.
The (optional) expiration time of the transaction. Defaults to 10 minutes.
The status of the transaction. Can only be used for cancelling the transaction.
The endpoint for payment service provider issuer transactions
This is how the error response looks like for 4XX response codes
POST /v1/user/{userID}/payment-service-provider-issuer-transaction HTTP/1.1
Host: public-api.sandbox.bunq.com
User-Agent: text
X-Bunq-Client-Authentication: text
Content-Type: application/json
Accept: */*
Content-Length: 208
{
"counterparty_alias": {
"type": "text",
"value": "text",
"name": "text",
"service": "text"
},
"amount": {
"value": "text",
"currency": "text"
},
"description": "text",
"url_redirect": "text",
"time_expiry": "text",
"status": "text"
}{
"Id": {
"id": 1
}
}The endpoint for payment service provider issuer transactions
The standard HTTP Cache-Control header is required for all signed requests.
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.
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.
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.
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.
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.
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
The endpoint for payment service provider issuer transactions
This is how the error response looks like for 4XX response codes
GET /v1/user/{userID}/payment-service-provider-issuer-transaction HTTP/1.1
Host: public-api.sandbox.bunq.com
User-Agent: text
X-Bunq-Client-Authentication: text
Accept: */*
[
{
"id": 1,
"created": "text",
"updated": "text",
"public_uuid": "text",
"counterparty_alias": {
"iban": "text",
"display_name": "text",
"avatar": {
"uuid": "text",
"anchor_uuid": "text",
"image": [
{
"attachment_public_uuid": "text",
"content_type": "text",
"height": 1,
"width": 1
}
],
"style": "text"
},
"label_user": {
"uuid": "text",
"display_name": "text",
"country": "text",
"avatar": {
"uuid": "text",
"anchor_uuid": "text",
"image": [
{
"attachment_public_uuid": "text",
"content_type": "text",
"height": 1,
"width": 1
}
],
"style": "text"
},
"public_nick_name": "text"
},
"country": "text",
"bunq_me": {
"type": "text",
"value": "text",
"name": "text"
},
"is_light": true,
"swift_bic": "text",
"swift_account_number": "text",
"transferwise_account_number": "text",
"transferwise_bank_code": "text",
"merchant_category_code": "text"
},
"amount": {
"value": "text",
"currency": "text"
},
"description": "text",
"url_redirect": "text",
"time_expiry": "text",
"status": "text",
"alias": {
"iban": "text",
"display_name": "text",
"avatar": {
"uuid": "text",
"anchor_uuid": "text",
"image": [
{
"attachment_public_uuid": "text",
"content_type": "text",
"height": 1,
"width": 1
}
],
"style": "text"
},
"label_user": {
"uuid": "text",
"display_name": "text",
"country": "text",
"avatar": {
"uuid": "text",
"anchor_uuid": "text",
"image": [
{
"attachment_public_uuid": "text",
"content_type": "text",
"height": 1,
"width": 1
}
],
"style": "text"
},
"public_nick_name": "text"
},
"country": "text",
"bunq_me": {
"type": "text",
"value": "text",
"name": "text"
},
"is_light": true,
"swift_bic": "text",
"swift_account_number": "text",
"transferwise_account_number": "text",
"transferwise_bank_code": "text",
"merchant_category_code": "text"
}
}
]The endpoint for payment service provider issuer transactions
The standard HTTP Cache-Control header is required for all signed requests.
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.
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.
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.
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.
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.
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
The endpoint for payment service provider issuer transactions
This is how the error response looks like for 4XX response codes
GET /v1/user/{userID}/payment-service-provider-issuer-transaction/{itemId} HTTP/1.1
Host: public-api.sandbox.bunq.com
User-Agent: text
X-Bunq-Client-Authentication: text
Accept: */*
{
"id": 1,
"created": "text",
"updated": "text",
"public_uuid": "text",
"counterparty_alias": {
"iban": "text",
"display_name": "text",
"avatar": {
"uuid": "text",
"anchor_uuid": "text",
"image": [
{
"attachment_public_uuid": "text",
"content_type": "text",
"height": 1,
"width": 1
}
],
"style": "text"
},
"label_user": {
"uuid": "text",
"display_name": "text",
"country": "text",
"avatar": {
"uuid": "text",
"anchor_uuid": "text",
"image": [
{
"attachment_public_uuid": "text",
"content_type": "text",
"height": 1,
"width": 1
}
],
"style": "text"
},
"public_nick_name": "text"
},
"country": "text",
"bunq_me": {
"type": "text",
"value": "text",
"name": "text"
},
"is_light": true,
"swift_bic": "text",
"swift_account_number": "text",
"transferwise_account_number": "text",
"transferwise_bank_code": "text",
"merchant_category_code": "text"
},
"amount": {
"value": "text",
"currency": "text"
},
"description": "text",
"url_redirect": "text",
"time_expiry": "text",
"status": "text",
"alias": {
"iban": "text",
"display_name": "text",
"avatar": {
"uuid": "text",
"anchor_uuid": "text",
"image": [
{
"attachment_public_uuid": "text",
"content_type": "text",
"height": 1,
"width": 1
}
],
"style": "text"
},
"label_user": {
"uuid": "text",
"display_name": "text",
"country": "text",
"avatar": {
"uuid": "text",
"anchor_uuid": "text",
"image": [
{
"attachment_public_uuid": "text",
"content_type": "text",
"height": 1,
"width": 1
}
],
"style": "text"
},
"public_nick_name": "text"
},
"country": "text",
"bunq_me": {
"type": "text",
"value": "text",
"name": "text"
},
"is_light": true,
"swift_bic": "text",
"swift_account_number": "text",
"transferwise_account_number": "text",
"transferwise_bank_code": "text",
"merchant_category_code": "text"
}
}The endpoint for payment service provider issuer transactions
The standard HTTP Cache-Control header is required for all signed requests.
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.
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.
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.
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.
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.
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
The description of this transaction, to be shown to the user and to the counter party.
The url to which the user should be redirected once the transaction is accepted or rejected.
The (optional) expiration time of the transaction. Defaults to 10 minutes.
The status of the transaction. Can only be used for cancelling the transaction.
The endpoint for payment service provider issuer transactions
This is how the error response looks like for 4XX response codes
PUT /v1/user/{userID}/payment-service-provider-issuer-transaction/{itemId} HTTP/1.1
Host: public-api.sandbox.bunq.com
User-Agent: text
X-Bunq-Client-Authentication: text
Content-Type: application/json
Accept: */*
Content-Length: 208
{
"counterparty_alias": {
"type": "text",
"value": "text",
"name": "text",
"service": "text"
},
"amount": {
"value": "text",
"currency": "text"
},
"description": "text",
"url_redirect": "text",
"time_expiry": "text",
"status": "text"
}{
"Id": {
"id": 1
}
}Last updated
Was this helpful?