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 https://public-api.sandbox.bunq.com/v1/installation \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "X-Bunq-Client-Request-Id: $(uuidgen)" \
--data "{\"client_public_key\": \"$(awk 'NF {sub(/\r/, ""); printf "%s\\n", $0;}' installation.pub)\"}")

Here is the full specification of the endpoint:

post

/installation

This is the only API call that does not require you to use the "X-Bunq-Client-Authentication" and "X-Bunq-Client-Signature" headers. You provide the server with the public part of the key pair that you are going to use to create the value of the signature header for all future API calls. The server creates an installation for you. Store the Installation Token and ServerPublicKey from the response. This token is used in the "X-Bunq-Client-Authentication" header for the creation of a DeviceServer and SessionServer.

Header parameters

Cache-ControlstringOptional

The standard HTTP Cache-Control header is required for all signed requests.

User-AgentstringRequired

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.

X-Bunq-LanguagestringOptional

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.

X-Bunq-RegionstringOptional

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.

X-Bunq-Client-Request-IdstringOptional

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.

X-Bunq-GeolocationstringOptional

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.

X-Bunq-Client-AuthenticationstringRequired

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

Body

client_public_keystringWrite-onlyRequired

Your public key. This is the public part of the key pair that you are going to use to create value of the "X-Bunq-Client-Signature" header for all future API calls.

Responses

200

Installation is used to tell the server about the public key of your key pair. The server uses this key to verify your subsequent calls, which need to be signed with your own private key. Additionally, you can use the token you get from an Installation to authenticate the registration of a new device.

application/json

400

This is how the error response looks like for 4XX response codes

application/json

post

/installation

POST /v1/installation HTTP/1.1
Host: public-api.sandbox.bunq.com
User-Agent: text
X-Bunq-Client-Authentication: text
Content-Type: application/json
Accept: */*
Content-Length: 28

{
  "client_public_key": "text"
}

{
  "Id": {
    "id": 1
  },
  "Token": {
    "id": 1,
    "created": "text",
    "updated": "text",
    "token": "text"
  },
  "ServerPublicKey": {
    "server_public_key": "text"
  }
}

4. Generate the Signature

This proves ownership of your PSD2 certificate by signing the public key and token.

Make sure there is NO new line at the end of the file! Otherwise, the signature will be invalid.

Extract the installation_token from the previous step:

TOKEN=$(echo $INSTALLATION | grep -o '"token":"[A-Za-z0-9]*"' | cut -d '"' -f 4)
echo -n $TOKEN > installation.token

Take the server_public_key of the installation you also received in the previous step.
Append the token
Sign the string using the private key of your PSD2 certificate

openssl dgst -sign psd2.key -keyform PEM -sha256 -out signature <(cat installation.pub installation.token)

This base64 string should be passed as value of client_public_key_signature in the next step.

6. Create Payment Service Provider Credential

Need to update your PSD2 certificate? No problem, just repeat this step with the new certificate 😄

Use your certificate and signature to request your TPP credentials in bunq's API.

Here is the command line code:

CREDENTIAL=$(curl -X POST https://public-api.sandbox.bunq.com/v1/payment-service-provider-credential \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "X-Bunq-Client-Request-Id: $(uuidgen)" \
-H "X-Bunq-Client-Authentication: $TOKEN" \
--data "{
  \"client_payment_service_provider_certificate\": \"$(awk 'NF {sub(/\r/, ""); printf "%s\\n", $0;}' psd2.cert)\",
  \"client_payment_service_provider_certificate_chain\": \"$(awk 'NF {sub(/\r/, ""); printf "%s\\n", $0;}' psd2.cert)\",
  \"client_public_key_signature\": \"$(cat signature | base64)\"
}")

You can repeat the same value on the client_payment_service_provider_certificate and client_payment_service_provider_certificate_chain in sandbox, but please ensure you have your certificate chain ready when going to production, otherwise the call will fail.

Save the response for the next step:

echo $CREDENTIAL > credential.json

Here is the full specification of the endpoint:

post

/payment-service-provider-credential

Header parameters

Cache-ControlstringOptional

The standard HTTP Cache-Control header is required for all signed requests.

User-AgentstringRequired

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.

X-Bunq-LanguagestringOptional

X-Bunq-RegionstringOptional

X-Bunq-Client-Request-IdstringOptional

X-Bunq-GeolocationstringOptional

X-Bunq-Client-AuthenticationstringRequired

Body

client_payment_service_provider_certificatestringWrite-onlyRequired

Payment Services Directive 2 compatible QSEAL certificate

client_payment_service_provider_certificate_chainstringWrite-onlyRequired

Intermediate and root certificate belonging to the provided certificate.

client_public_key_signaturestringWrite-onlyRequired

The Base64 encoded signature of the public key provided during installation and with the installation token appended as a nonce. Signed with the private key belonging to the QSEAL certificate.

Responses

200

application/json

400

This is how the error response looks like for 4XX response codes

application/json

post

/payment-service-provider-credential

POST /v1/payment-service-provider-credential HTTP/1.1
Host: public-api.sandbox.bunq.com
User-Agent: text
X-Bunq-Client-Authentication: text
Content-Type: application/json
Accept: */*
Content-Length: 150

{
  "client_payment_service_provider_certificate": "text",
  "client_payment_service_provider_certificate_chain": "text",
  "client_public_key_signature": "text"
}

{
  "Id": {
    "id": 1
  }
}

It's good to know that if you register as a Payment Server Provider you will not be a 'typical' USER_PERSON or USER_COMPANY ( bunq API Objects). Instead you'll become a UserPaymentServiceProvider - this is a special kind of user that only serves as a user for your OAuth installation. This user type will not have any bank accounts or payments of it's own. You can only manage that user through our API

7. Extract Credential Token and register Your Device

After creating a credential in the previous step, you'll receive a credential_token, which acts as a unique secret. This token is required when registering your device using POST /device-server. Registering the device is an important security step—it lets bunq know where the API calls are coming from and links your setup to a specific environment (like your server or app).

By sending the credential token as the secret, you're proving that your device is authorized to operate under your PSD2 certificate and credentials. Without this step, bunq can’t associate API activity with a verified, trusted source.

Here's the bash code to extract your credential_token from the credential.json (saved in the last step):

CREDENTIAL_TOKEN=$(cat credential.json | grep -o '"token_value":"[A-Za-z0-9]*"' | cut -d '"' -f 4)

With that value in hands, you can then call the endpoint POST /device-server and register your device:

curl -X POST https://public-api.sandbox.bunq.com/v1/device-server \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "X-Bunq-Client-Request-Id: $(uuidgen)" \
-H "X-Bunq-Client-Authentication: $TOKEN" \
--data "{\"secret\":\"$CREDENTIAL_TOKEN\", \"description\": \"My server\"}"

IP addresses

When using a standard API Key the DeviceServer and Installation that are created in this process are bound to the IP address they are created from.

Using a Wildcard API Key gives you the freedom to make API calls from any IP address after the POST device-server. You can switch to a Wildcard API Key by tapping on “Allow All IP Addresses” in your API Key menu inside the bunq app.

You can also programatically switch to a Wildcard API Key by passing your current ip and a * (asterisk) in the permitted_ips field of the device-server POST call. E.g: ["1.2.3.4", "*"].

Here is the full specification of the endpoint:

post

/device-server

Create a new DeviceServer providing the installation token in the header and signing the request with the private part of the key you used to create the installation. The API Key that you are using will be bound to the IP address of the DeviceServer which you have created.Using a Wildcard API Key gives you the freedom to make API calls even if the IP address has changed after the POST device-server.Find out more at this link https:/bunq.com/en/apikey-dynamic-ip.

Header parameters

Cache-ControlstringOptional

The standard HTTP Cache-Control header is required for all signed requests.

User-AgentstringRequired

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.

X-Bunq-LanguagestringOptional

X-Bunq-RegionstringOptional

X-Bunq-Client-Request-IdstringOptional

X-Bunq-GeolocationstringOptional

X-Bunq-Client-AuthenticationstringRequired

Body

descriptionstringRequired

The description of the DeviceServer. This is only for your own reference when reading the DeviceServer again.

secretstringWrite-onlyRequired

The API key. You can request an API key in the bunq app.

permitted_ipsstring[]Write-onlyOptional

An array of IPs (v4 or v6) this DeviceServer will be able to do calls from. These will be linked to the API key.

Responses

200

After having created an Installation you can now create a DeviceServer. A DeviceServer is needed to do a login call with session-server.

application/json

400

This is how the error response looks like for 4XX response codes

application/json

post

/device-server

POST /v1/device-server HTTP/1.1
Host: public-api.sandbox.bunq.com
User-Agent: text
X-Bunq-Client-Authentication: text
Content-Type: application/json
Accept: */*
Content-Length: 63

{
  "description": "text",
  "secret": "text",
  "permitted_ips": [
    "text"
  ]
}

{
  "id": 1
}

9. Sign the Session Request

We are legally required to protect our users and their data from malicious attacks and intrusions. That is why we beyond having a secure https connection, we use asymmetric cryptography for signing requests that create a session or payment. The use of signatures ensures the data is coming from the trusted party and was not modified after sending and before receiving.

In this step, you're preparing to create a session with bunq's API, which requires proving your identity using a digital signature.

SESSION_REQUEST_BODY="{\"secret\":\"$CREDENTIAL_TOKEN\"}"
echo -n $SESSION_REQUEST_BODY > session.request

Make sure there is NO new line at the end of the file! Otherwise, the signature will be invalid.

Then you'll digitally sign the contents of the request body using your installation private key. This proves to bunq that the request really comes from someone in control of the private key tied to your public key.

After, you'll encode the binary signature into base64 so it can be safely sent in the signature HTTP header from the next step.

openssl dgst -sign installation.key -keyform PEM -sha256 -out signature < session.request
SESSION_REQUEST_SIGNATURE=$(cat signature | base64)

Troubleshooting

If you get an error telling you "The request signature is invalid", please check the following:

There are no redundant characters (extra spaces, trailing line breaks, etc.) in the data to sign.
Make sure the body is appended to the data to sign exactly as you're adding it to the request.
You have added the full body to the data to sign.
You use the data to sign to create a SHA256 hash signature.
You have base64 encoded the SHA256 hash signature before adding it to the request under X-Bunq-Client-Signature.

You can find more info about signing the request body in this link here.

11. Create Session

The POST /session-server endpoint is used to start a new session with the bunq API. Once your device is registered and you've created a valid credential, this call creates an authenticated session. The session ensures secure, time-limited access to the bunq API on behalf of your registered device and credentials.

curl -X POST https://public-api.sandbox.bunq.com/v1/session-server \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "X-Bunq-Client-Request-Id: $(uuidgen)" \
-H "X-Bunq-Client-Signature: $SESSION_REQUEST_SIGNATURE" \
-H "X-Bunq-Client-Authentication: $TOKEN" \
--data "$SESSION_REQUEST_BODY"

The response will contain a session_token. Use this token in the X-Bunq-Client-Authentication header for all subsequent API calls.

Here is the full specification of the endpoint:

post

/session-server

Create a new session for a DeviceServer. Provide the Installation token in the "X-Bunq-Client-Authentication" header. And don't forget to create the "X-Bunq-Client-Signature" header. The response contains a Session token that should be used for as the "X-Bunq-Client-Authentication" header for all future API calls. The ip address making this call needs to match the ip address bound to your API key.

Header parameters

Cache-ControlstringOptional

The standard HTTP Cache-Control header is required for all signed requests.

User-AgentstringRequired

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.

X-Bunq-LanguagestringOptional

X-Bunq-RegionstringOptional

X-Bunq-Client-Request-IdstringOptional

X-Bunq-GeolocationstringOptional

X-Bunq-Client-AuthenticationstringRequired

Body

secretstringWrite-onlyRequired

The API key of the user you want to login. If your API key has not been used before, it will be bound to the ip address of this DeviceServer.

Responses

200

Once you have created an Installation and a DeviceServer with that Installation, then you are ready to start a session! A session expires after the same amount of time you have set for Auto Logout in your user account. By default this is 1 week. If a request is made 30 seconds before a session expires, it will be extended from that moment by your auto logout time, but never by more than 5 minutes.

application/json

400

This is how the error response looks like for 4XX response codes

application/json

post

/session-server

POST /v1/session-server HTTP/1.1
Host: public-api.sandbox.bunq.com
User-Agent: text
X-Bunq-Client-Authentication: text
Content-Type: application/json
Accept: */*
Content-Length: 17

{
  "secret": "text"
}

{
  "Id": {
    "id": 1
  },
  "Token": {
    "id": 1,
    "token": "text"
  },
  "UserCompany": {
    "name": "text",
    "public_nick_name": "text",
    "address_main": {
      "street": "text",
      "house_number": "text",
      "po_box": "text",
      "postal_code": "text",
      "city": "text",
      "country": "text",
      "extra": "text",
      "mailbox_name": "text",
      "province": "text",
      "is_user_address_updated": true
    },
    "address_postal": {
      "street": "text",
      "house_number": "text",
      "po_box": "text",
      "postal_code": "text",
      "city": "text",
      "country": "text",
      "extra": "text",
      "mailbox_name": "text",
      "province": "text",
      "is_user_address_updated": true
    },
    "language": "text",
    "region": "text",
    "country": "text",
    "ubo": [
      {
        "name": "text",
        "date_of_birth": "text",
        "nationality": "text"
      }
    ],
    "chamber_of_commerce_number": "text",
    "legal_form": "text",
    "status": "text",
    "sub_status": "text",
    "session_timeout": 1,
    "daily_limit_without_confirmation_login": {
      "value": "text",
      "currency": "text"
    },
    "id": 1,
    "created": "text",
    "updated": "text",
    "public_uuid": "text",
    "display_name": "text",
    "alias": [
      {
        "type": "text",
        "value": "text",
        "name": "text"
      }
    ],
    "type_of_business_entity": "text",
    "sector_of_industry": "text",
    "counter_bank_iban": "text",
    "avatar": {
      "uuid": "text",
      "anchor_uuid": "text",
      "image": [
        {
          "attachment_public_uuid": "text",
          "content_type": "text",
          "height": 1,
          "width": 1
        }
      ],
      "style": "text"
    },
    "version_terms_of_service": "text",
    "directors": [
      {
        "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"
      }
    ],
    "notification_filters": [
      {
        "notification_delivery_method": "text",
        "notification_target": "text",
        "category": "text"
      }
    ],
    "customer": {
      "billing_account_id": "text",
      "invoice_notification_preference": "text",
      "id": 1,
      "created": "text",
      "updated": "text"
    },
    "customer_limit": {
      "limit_monetary_account": 1,
      "limit_monetary_account_remaining": 1,
      "limit_card_debit_maestro": 1,
      "limit_card_debit_mastercard": 1,
      "limit_card_debit_wildcard": 1,
      "limit_card_wildcard": 1,
      "limit_card_replacement": 1,
      "limit_amount_monthly": {
        "value": "text",
        "currency": "text"
      },
      "spent_amount_monthly": {
        "value": "text",
        "currency": "text"
      }
    },
    "billing_contract": [
      {
        "subscription_type": "text",
        "id": 1,
        "created": "text",
        "updated": "text",
        "contract_date_start": "text",
        "contract_date_end": "text",
        "contract_version": 1,
        "subscription_type_downgrade": "text",
        "status": "text",
        "sub_status": "text"
      }
    ],
    "deny_reason": "text",
    "relations": [
      {
        "user_id": "text",
        "counter_user_id": "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"
        },
        "counter_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"
        },
        "relationship": "text",
        "status": "text",
        "user_status": "text",
        "counter_user_status": "text"
      }
    ],
    "tax_resident": [
      {
        "country": "text",
        "tax_number": "text",
        "status": "text",
        "id": 1
      }
    ]
  },
  "UserPerson": {
    "first_name": "text",
    "middle_name": "text",
    "last_name": "text",
    "public_nick_name": "text",
    "address_main": {
      "street": "text",
      "house_number": "text",
      "po_box": "text",
      "postal_code": "text",
      "city": "text",
      "country": "text",
      "extra": "text",
      "mailbox_name": "text",
      "province": "text",
      "is_user_address_updated": true
    },
    "address_postal": {
      "street": "text",
      "house_number": "text",
      "po_box": "text",
      "postal_code": "text",
      "city": "text",
      "country": "text",
      "extra": "text",
      "mailbox_name": "text",
      "province": "text",
      "is_user_address_updated": true
    },
    "tax_resident": [
      {
        "country": "text",
        "tax_number": "text",
        "status": "text",
        "id": 1
      }
    ],
    "date_of_birth": "text",
    "nationality": "text",
    "all_nationality": [
      "text"
    ],
    "language": "text",
    "region": "text",
    "gender": "text",
    "status": "text",
    "sub_status": "text",
    "session_timeout": 1,
    "daily_limit_without_confirmation_login": {
      "value": "text",
      "currency": "text"
    },
    "display_name": "text",
    "id": 1,
    "created": "text",
    "updated": "text",
    "public_uuid": "text",
    "legal_name": "text",
    "alias": [
      {
        "type": "text",
        "value": "text",
        "name": "text"
      }
    ],
    "place_of_birth": "text",
    "country_of_birth": "text",
    "avatar": {
      "uuid": "text",
      "anchor_uuid": "text",
      "image": [
        {
          "attachment_public_uuid": "text",
          "content_type": "text",
          "height": 1,
          "width": 1
        }
      ],
      "style": "text"
    },
    "version_terms_of_service": "text",
    "notification_filters": [
      {
        "notification_delivery_method": "text",
        "notification_target": "text",
        "category": "text"
      }
    ],
    "relations": [
      {
        "user_id": "text",
        "counter_user_id": "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"
        },
        "counter_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"
        },
        "relationship": "text",
        "status": "text",
        "user_status": "text",
        "counter_user_status": "text"
      }
    ]
  },
  "UserApiKey": {
    "id": 1,
    "created": "text",
    "updated": "text",
    "requested_by_user": {
      "UserPerson": {
        "first_name": "text",
        "middle_name": "text",
        "last_name": "text",
        "public_nick_name": "text",
        "address_main": {
          "street": "text",
          "house_number": "text",
          "po_box": "text",
          "postal_code": "text",
          "city": "text",
          "country": "text",
          "extra": "text",
          "mailbox_name": "text",
          "province": "text",
          "is_user_address_updated": true
        },
        "address_postal": {
          "street": "text",
          "house_number": "text",
          "po_box": "text",
          "postal_code": "text",
          "city": "text",
          "country": "text",
          "extra": "text",
          "mailbox_name": "text",
          "province": "text",
          "is_user_address_updated": true
        },
        "tax_resident": [
          {
            "country": "text",
            "tax_number": "text",
            "status": "text",
            "id": 1
          }
        ],
        "date_of_birth": "text",
        "nationality": "text",
        "all_nationality": [
          "text"
        ],
        "language": "text",
        "region": "text",
        "gender": "text",
        "status": "text",
        "sub_status": "text",
        "session_timeout": 1,
        "daily_limit_without_confirmation_login": {
          "value": "text",
          "currency": "text"
        },
        "display_name": "text",
        "id": 1,
        "created": "text",
        "updated": "text",
        "public_uuid": "text",
        "legal_name": "text",
        "alias": [
          {
            "type": "text",
            "value": "text",
            "name": "text"
          }
        ],
        "place_of_birth": "text",
        "country_of_birth": "text",
        "avatar": {
          "uuid": "text",
          "anchor_uuid": "text",
          "image": [
            {
              "attachment_public_uuid": "text",
              "content_type": "text",
              "height": 1,
              "width": 1
            }
          ],
          "style": "text"
        },
        "version_terms_of_service": "text",
        "notification_filters": [
          {
            "notification_delivery_method": "text",
            "notification_target": "text",
            "category": "text"
          }
        ],
        "relations": [
          {
            "user_id": "text",
            "counter_user_id": "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"
            },
            "counter_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"
            },
            "relationship": "text",
            "status": "text",
            "user_status": "text",
            "counter_user_status": "text"
          }
        ]
      },
      "UserCompany": {
        "name": "text",
        "public_nick_name": "text",
        "address_main": {
          "street": "text",
          "house_number": "text",
          "po_box": "text",
          "postal_code": "text",
          "city": "text",
          "country": "text",
          "extra": "text",
          "mailbox_name": "text",
          "province": "text",
          "is_user_address_updated": true
        },
        "address_postal": {
          "street": "text",
          "house_number": "text",
          "po_box": "text",
          "postal_code": "text",
          "city": "text",
          "country": "text",
          "extra": "text",
          "mailbox_name": "text",
          "province": "text",
          "is_user_address_updated": true
        },
        "language": "text",
        "region": "text",
        "country": "text",
        "ubo": [
          {
            "name": "text",
            "date_of_birth": "text",
            "nationality": "text"
          }
        ],
        "chamber_of_commerce_number": "text",
        "legal_form": "text",
        "status": "text",
        "sub_status": "text",
        "session_timeout": 1,
        "daily_limit_without_confirmation_login": {
          "value": "text",
          "currency": "text"
        },
        "id": 1,
        "created": "text",
        "updated": "text",
        "public_uuid": "text",
        "display_name": "text",
        "alias": [
          {
            "type": "text",
            "value": "text",
            "name": "text"
          }
        ],
        "type_of_business_entity": "text",
        "sector_of_industry": "text",
        "counter_bank_iban": "text",
        "avatar": {
          "uuid": "text",
          "anchor_uuid": "text",
          "image": [
            {
              "attachment_public_uuid": "text",
              "content_type": "text",
              "height": 1,
              "width": 1
            }
          ],
          "style": "text"
        },
        "version_terms_of_service": "text",
        "directors": [
          {
            "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"
          }
        ],
        "notification_filters": [
          {
            "notification_delivery_method": "text",
            "notification_target": "text",
            "category": "text"
          }
        ],
        "customer": {
          "billing_account_id": "text",
          "invoice_notification_preference": "text",
          "id": 1,
          "created": "text",
          "updated": "text"
        },
        "customer_limit": {
          "limit_monetary_account": 1,
          "limit_monetary_account_remaining": 1,
          "limit_card_debit_maestro": 1,
          "limit_card_debit_mastercard": 1,
          "limit_card_debit_wildcard": 1,
          "limit_card_wildcard": 1,
          "limit_card_replacement": 1,
          "limit_amount_monthly": {
            "value": "text",
            "currency": "text"
          },
          "spent_amount_monthly": {
            "value": "text",
            "currency": "text"
          }
        },
        "billing_contract": [
          {
            "subscription_type": "text",
            "id": 1,
            "created": "text",
            "updated": "text",
            "contract_date_start": "text",
            "contract_date_end": "text",
            "contract_version": 1,
            "subscription_type_downgrade": "text",
            "status": "text",
            "sub_status": "text"
          }
        ],
        "deny_reason": "text",
        "relations": [
          {
            "user_id": "text",
            "counter_user_id": "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"
            },
            "counter_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"
            },
            "relationship": "text",
            "status": "text",
            "user_status": "text",
            "counter_user_status": "text"
          }
        ],
        "tax_resident": [
          {
            "country": "text",
            "tax_number": "text",
            "status": "text",
            "id": 1
          }
        ]
      },
      "UserPaymentServiceProvider": {
        "id": 1,
        "created": "text",
        "updated": "text",
        "certificate_distinguished_name": "text",
        "alias": [
          {
            "type": "text",
            "value": "text",
            "name": "text"
          }
        ],
        "avatar": {
          "uuid": "text",
          "anchor_uuid": "text",
          "image": [
            {
              "attachment_public_uuid": "text",
              "content_type": "text",
              "height": 1,
              "width": 1
            }
          ],
          "style": "text"
        },
        "status": "text",
        "sub_status": "text",
        "public_uuid": "text",
        "display_name": "text",
        "public_nick_name": "text",
        "language": "text",
        "region": "text",
        "session_timeout": 1
      }
    },
    "granted_by_user": {
      "UserPerson": {
        "first_name": "text",
        "middle_name": "text",
        "last_name": "text",
        "public_nick_name": "text",
        "address_main": {
          "street": "text",
          "house_number": "text",
          "po_box": "text",
          "postal_code": "text",
          "city": "text",
          "country": "text",
          "extra": "text",
          "mailbox_name": "text",
          "province": "text",
          "is_user_address_updated": true
        },
        "address_postal": {
          "street": "text",
          "house_number": "text",
          "po_box": "text",
          "postal_code": "text",
          "city": "text",
          "country": "text",
          "extra": "text",
          "mailbox_name": "text",
          "province": "text",
          "is_user_address_updated": true
        },
        "tax_resident": [
          {
            "country": "text",
            "tax_number": "text",
            "status": "text",
            "id": 1
          }
        ],
        "date_of_birth": "text",
        "nationality": "text",
        "all_nationality": [
          "text"
        ],
        "language": "text",
        "region": "text",
        "gender": "text",
        "status": "text",
        "sub_status": "text",
        "session_timeout": 1,
        "daily_limit_without_confirmation_login": {
          "value": "text",
          "currency": "text"
        },
        "display_name": "text",
        "id": 1,
        "created": "text",
        "updated": "text",
        "public_uuid": "text",
        "legal_name": "text",
        "alias": [
          {
            "type": "text",
            "value": "text",
            "name": "text"
          }
        ],
        "place_of_birth": "text",
        "country_of_birth": "text",
        "avatar": {
          "uuid": "text",
          "anchor_uuid": "text",
          "image": [
            {
              "attachment_public_uuid": "text",
              "content_type": "text",
              "height": 1,
              "width": 1
            }
          ],
          "style": "text"
        },
        "version_terms_of_service": "text",
        "notification_filters": [
          {
            "notification_delivery_method": "text",
            "notification_target": "text",
            "category": "text"
          }
        ],
        "relations": [
          {
            "user_id": "text",
            "counter_user_id": "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"
            },
            "counter_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"
            },
            "relationship": "text",
            "status": "text",
            "user_status": "text",
            "counter_user_status": "text"
          }
        ]
      },
      "UserCompany": {
        "name": "text",
        "public_nick_name": "text",
        "address_main": {
          "street": "text",
          "house_number": "text",
          "po_box": "text",
          "postal_code": "text",
          "city": "text",
          "country": "text",
          "extra": "text",
          "mailbox_name": "text",
          "province": "text",
          "is_user_address_updated": true
        },
        "address_postal": {
          "street": "text",
          "house_number": "text",
          "po_box": "text",
          "postal_code": "text",
          "city": "text",
          "country": "text",
          "extra": "text",
          "mailbox_name": "text",
          "province": "text",
          "is_user_address_updated": true
        },
        "language": "text",
        "region": "text",
        "country": "text",
        "ubo": [
          {
            "name": "text",
            "date_of_birth": "text",
            "nationality": "text"
          }
        ],
        "chamber_of_commerce_number": "text",
        "legal_form": "text",
        "status": "text",
        "sub_status": "text",
        "session_timeout": 1,
        "daily_limit_without_confirmation_login": {
          "value": "text",
          "currency": "text"
        },
        "id": 1,
        "created": "text",
        "updated": "text",
        "public_uuid": "text",
        "display_name": "text",
        "alias": [
          {
            "type": "text",
            "value": "text",
            "name": "text"
          }
        ],
        "type_of_business_entity": "text",
        "sector_of_industry": "text",
        "counter_bank_iban": "text",
        "avatar": {
          "uuid": "text",
          "anchor_uuid": "text",
          "image": [
            {
              "attachment_public_uuid": "text",
              "content_type": "text",
              "height": 1,
              "width": 1
            }
          ],
          "style": "text"
        },
        "version_terms_of_service": "text",
        "directors": [
          {
            "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"
          }
        ],
        "notification_filters": [
          {
            "notification_delivery_method": "text",
            "notification_target": "text",
            "category": "text"
          }
        ],
        "customer": {
          "billing_account_id": "text",
          "invoice_notification_preference": "text",
          "id": 1,
          "created": "text",
          "updated": "text"
        },
        "customer_limit": {
          "limit_monetary_account": 1,
          "limit_monetary_account_remaining": 1,
          "limit_card_debit_maestro": 1,
          "limit_card_debit_mastercard": 1,
          "limit_card_debit_wildcard": 1,
          "limit_card_wildcard": 1,
          "limit_card_replacement": 1,
          "limit_amount_monthly": {
            "value": "text",
            "currency": "text"
          },
          "spent_amount_monthly": {
            "value": "text",
            "currency": "text"
          }
        },
        "billing_contract": [
          {
            "subscription_type": "text",
            "id": 1,
            "created": "text",
            "updated": "text",
            "contract_date_start": "text",
            "contract_date_end": "text",
            "contract_version": 1,
            "subscription_type_downgrade": "text",
            "status": "text",
            "sub_status": "text"
          }
        ],
        "deny_reason": "text",
        "relations": [
          {
            "user_id": "text",
            "counter_user_id": "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"
            },
            "counter_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"
            },
            "relationship": "text",
            "status": "text",
            "user_status": "text",
            "counter_user_status": "text"
          }
        ],
        "tax_resident": [
          {
            "country": "text",
            "tax_number": "text",
            "status": "text",
            "id": 1
          }
        ]
      },
      "UserPaymentServiceProvider": {
        "id": 1,
        "created": "text",
        "updated": "text",
        "certificate_distinguished_name": "text",
        "alias": [
          {
            "type": "text",
            "value": "text",
            "name": "text"
          }
        ],
        "avatar": {
          "uuid": "text",
          "anchor_uuid": "text",
          "image": [
            {
              "attachment_public_uuid": "text",
              "content_type": "text",
              "height": 1,
              "width": 1
            }
          ],
          "style": "text"
        },
        "status": "text",
        "sub_status": "text",
        "public_uuid": "text",
        "display_name": "text",
        "public_nick_name": "text",
        "language": "text",
        "region": "text",
        "session_timeout": 1
      }
    }
  },
  "UserPaymentServiceProvider": {
    "id": 1,
    "created": "text",
    "updated": "text",
    "certificate_distinguished_name": "text",
    "alias": [
      {
        "type": "text",
        "value": "text",
        "name": "text"
      }
    ],
    "avatar": {
      "uuid": "text",
      "anchor_uuid": "text",
      "image": [
        {
          "attachment_public_uuid": "text",
          "content_type": "text",
          "height": 1,
          "width": 1
        }
      ],
      "style": "text"
    },
    "status": "text",
    "sub_status": "text",
    "public_uuid": "text",
    "display_name": "text",
    "public_nick_name": "text",
    "language": "text",
    "region": "text",
    "session_timeout": 1
  }
}

✅ You're Ready!

You’ve now successfully authenticated with the bunq Public API as a PSD2-certified provider.

Now you're ready to set up the OAuth with your end user and start using the API in accordance with your certified roles (AISP, PISP, or CBPII).

Please refer to this page on how to set up OAuth:

OAuth

📝 Reminder

All integration steps must be repeated in the production environment with your real eIDAS certificate when you're ready to go live.

Ready to continue? You can check what you can do with bunq's API according to your role in these pages here:

Account Information Service Provider (AISP)

Payment Initiation Service Provider (PISP)

Card-Based Payment Instrument Issuer (CBPII)

PreviousAre you a Third Party Provider (TPP)? Start here!NextChange your avatar

Last updated 7 months ago

Was this helpful?

hashtagPre-Requisite

hashtag🛠️ Step-by-Step Integration

hashtag1. Generate Installation Key Pair

hashtag2. (Sandbox only) Generate a test PSD2 Certificate

hashtag3. Create Installation

hashtag4. Generate the Signature

hashtag6. Create Payment Service Provider Credential

hashtag7. Extract Credential Token and register Your Device

hashtagIP addresses

hashtag9. Sign the Session Request

hashtagTroubleshooting

hashtag11. Create Session

hashtag✅ You're Ready!

hashtag📝 Reminder

Pre-Requisite

🛠️ Step-by-Step Integration

1. Generate Installation Key Pair

2. (Sandbox only) Generate a test PSD2 Certificate

3. Create Installation

4. Generate the Signature

6. Create Payment Service Provider Credential

7. Extract Credential Token and register Your Device

IP addresses

9. Sign the Session Request

Troubleshooting

11. Create Session

✅ You're Ready!

📝 Reminder