Comment on page

Tab payment

This tutorial will help you create a tab that can be paid once by a single user (a so-called TagUsageSingle). It explains two ways to make the Tab visible to your customers:
  • QR code from the CashRegister
  • QR code from the Tab.

Before you start

  • Open a session
  • Pass the session Token in the X-Bunq-Client-Authentication header in every following request of this session.

Call Sequence

1. POST /attachment-public

Start by creating an attachment that will be used for the avatar for the cash register.
  • Make sure you set the Content-Type header to match the MIME type of the image.
  • Pass a description of the image via the X-Bunq-Attachment-Description header.


The payload of this request is the binary representation of the image file. Do not use any JSON formatting.


  • Save the uuid of the posted attachment. You'll need it to create the avatar in the next step.

2. POST /avatar

  • Make an avatar using the public attachment you've just created.


The payload of this request is the uuid of the attachment public.


  • Receive the UUID of the avatar created using the Attachment object.
  • Save the UUID. You will use it as the avatar for the cash register you're about to create.

3. GET /monetary-account

  • List all your monetary accounts.
  • Choose the one you want your cash register to be connected to and save its id . Each paid tab for the cash register will transfer the money to this account.

4a. POST /cash-register

  • Create a cash register using the id of the monetary account you want to connect the cash register to in the URL of the request.


  • Provide the uuid of the avatar you created for this cash register.
  • Make sure to provide a unique name for your cash register.
  • Change the status of the cash register to PENDING_APPROVAL.


The response contains the id of the cash register you created. Save this id. You will need it to create subsequent tabs and tab items.

4b. Wait for approval

  • Production: a bunq admin will review and approve your cash register.
  • Sandbox: your cash register will be automatically approved.

5. POST /tab-usage-single

  • Create a new tab that is connected to your cash register using the id of the cash register in the request URL request.


  • Give the tab a name in merchant_reference.
  • Create the tab with the OPEN status and give the tab a starting amount. You can update this amount later.


The response contains the uuid of the tab you created.

6. POST /tab-item (optional)

You can add items to a tab. This will display the products or services the customer is going to pay for. Adding items to a tab is does not change the total amount of the tab itself.
Make sure the sum of the item prices equals the total_amount of the tab when you change its status to WAITING_FOR_PAYMENT.

7. PUT /tab-usage-single

Once the tab is ready for a customer to pay for the order, update the status of the tab to WAITING_FOR_PAYMENT. This will make the tab visible to your customers.


To decide how you are going to make your tab visible, pass a visibility object in the payload.
Set cash_register_qr_code true to connect the tab to the QR code from the cash register. If this cash register does not have a QR code yet, it is created automatically.
Only one Tab can be connected to the QR code of the cash register at a time.
Set tab_qr_code true to create a QR code specifically for the tab. The QR code can not be linked to anything else.