JSON Definitions

Every webhook request contains the following three objects in the payload:

  • event Contains metadata about the event.
  • sender Contains the details of the workplace that is sending the event.

Most webhooks, with the exception of backgroundPoll, also contain the following object:

  • session Contains the details of the current session.

Then there are some objects that only occur within specific event requests:

  • scanCode Contains the scanned code’s details.
  • addSessionLine Contains the added line’s details.
  • removeSessionLine Contains the removed line’s details.
  • mergeSession Contains the ID of the session that the current session is merging with.
  • completeSession Contains the payment details of the session.
  • printBill Contains the details of previous payments to the bill.
  • customAction Contains the details of the custom action.
  • cafeteriaOrder Contains the details of the underlying cafeteria order.
  • tableOrder Contains the details of the underlying table order.
  • order Contains the details of the underlying order.
  • table Contains the details of the underlying table.
  • course Contains the details of the underlying course.

When replying to a webhook, you can choose to reply with an empty body, or with one or more of the following objects:

  • error
    Signify an error in the request that was sent.
  • lineChanges
    Request changes to the session’s lines.
  • lineAdditions
    Request additions to the session’s lines.
  • lineDeletions
    Request deletions from the session’s lines.
  • lockSession
    Lock the session from further changes.
  • lockSessionForAdditions
    Lock the session from further additions (deletions/decreases is allowed).
  • receiptFooter (only works with completeSession)
    Request some extra data to be printed on the footer of the receipt.
  • billFooter (only works with printBill)
    Request some extra data to be printed on the footer of the bill.
  • dialog
    Request a dialog to show up on screen.
  • message
    Request messages to show up on the user screen and/or the customer screen.
  • requestScanCode
    Request a code to be scanned in the POS.
  • customActionChange
    Change the caption of a customAction button.
  • vatMethodChange
    Change the VAT method of the current session.
  • externalCardScan
    Notify the POS that an external card was scanned, that the POS should know about.
  • prepayTable
    Register payment on a table.
  • requestCustomAction
    Request the POS to execute a specific custom action.

When you reply with a dialog, the user will be able to select some dialog options. Afterwards, the same event will be sent to you again, but this time including the selected dialog options.

  • dialog Contains selected dialog options.

When you receive a polling webhook (you can recognize this by the property event.eventPolling), you must reply with at least a polling object in the response. Otherwise, MplusKASSA will continue querying your endpoint until the webhook is manually cancelled.

  • polling Tell MplusKASSA to continue polling or not, and optionally display some messages.

There is also always the possibility that your reply triggers an error, this will cause the following request to be sent:

  • error Signify an error in the response that was sent.

event

Property Type Explanation
event.eventBlocking boolean Is the event blocking? When this is true, MplusKASSA is waiting for your response.
event.eventPolling boolean Is the event polling? When this is true, MplusKASSA will continue to query your endpoint until you respond that polling is finished (see polling response).
event.eventCounter int An increasing counter that helps you check if you already processed an event. Please note that the counter may occasionally reset.
event.eventTimestamp datetime The date and time that the event occurred.

sender

Property Type Explanation
sender.branchNumber int The branch the event was sent from.
sender.workplaceNumber int The workplace the event was sent from.
sender.instanceId uuid Every time the POS is restarted, this UUID is regenerated.
sender.paymentStarted boolean When the POS is in the payment screen, this variable will be true. To detect changes to and from the payment screen, you can listen to the startPayment and cancelPayment events.

session

Property Type Explanation
session.sessionId uuid The session’s unique ID.
session.table.number bigint (optional) The table number that the session is attached to.
session.table.subNumber bigint (optional) The table sub number that the session is placed upon.
session.lines array The session’s lines.
session.lines[].lineId uuid The line’s unique ID.
session.lines[].articleNumber bigint (optional) The line’s article number.
session.lines[].priceIncl number (optional) The line’s price including VAT.
session.lines[].quantity number (optional) The line’s quantity.
session.lines[].text string The line’s textual description.
session.lines[].discountPercentage number (optional) The line’s percentual discount, this stacks with the discount amount.
session.lines[].discountAmount number (optional) The line’s discount amount, this stacks with the discount percentage.
session.lines[].supplierArticleNumber string (optional) Article number from the supplier, if available.
session.lines[].pluNumber string (optional) PLU number, if available.
session.lines[].extArticleId string (optional) External article ID, if available.
Note that you would normally not be able to have a line with a discount from MplusKASSA and an external discount. It can only be one or the other.
session.lines[].externalDiscount.discountId uuid (optional) This is a UUID you generate and store to remember that you applied this discount.
session.lines[].externalDiscount.discountDescription string (optional) A textual description for the external discount.
session.lines[].externalDiscount.discountPercentage number (optional) The line’s external percentual discount, this stacks with the external discount amount.
session.lines[].externalDiscount.discountAmount number (optional) The line’s external discount amount, this stacks with the external discount percentage.
Note that you would normally not be able to have a line with a discount from MplusKASSA and an external discount. It can only be one or the other.

scanCode

Property Type Explanation
scanCode.scannedCode string A textual representation of the code that was scanned.
scanCode.codeType string barcode, rfid, qrcode

addSessionLine

Property Type Explanation
addSessionLine.line.lineId string The added line’s unique ID.<
addSessionLine.line.articleNumber bigint (optional) The added line’s article number.
addSessionLine.line.priceIncl number (optional) The added line’s price including VAT.
addSessionLine.line.quantity number (optional) The added line’s quantity.
addSessionLine.line.text string The added line’s textual description.
On top of this the added line can also contain all the additional properties a session.lines[] object can contain.

removeSessionLine

Property Type Explanation
removeSessionLine.line.lineId string The removed line’s unique ID.
removeSessionLine.line.articleNumber bigint (optional) The removed line’s article number.
removeSessionLine.line.priceIncl number (optional) The removed line’s price including VAT.
removeSessionLine.line.quantity number (optional) The removed line’s quantity.
removeSessionLine.line.text string The removed line’s textual description.
On top of this the added line can also contain all the additional properties a session.lines[] object can contain.

mergeSession

Property Type Explanation
mergeSession.mergeWithSessionId string The session that the current session is merged with.
session.sessionId string The session that is merged.

completeSession

Property Type Explanation
completeSession.payments[].amount number The amount that was paid with this specific payment method.
completeSession.payments[].description string The description label of this payment method.
completeSession.payments[].method string The reference id of this payment method.

customAction

Property Type Explanation
customAction.customActionId text The manually configured ID of the customAction button that was clicked.
customAction.buttonCaption text The manually configured caption of the customAction button that was clicked, can be changed through a webhook response.
customAction.onStartup boolean Whether or not the webhook was called during POS startup. You may use this to set initial state.
customAction.numpadValue number (optional) The current value of the POS numpad input.

cafeteriaOrder

Property Type Explanation
customAction.customActionId text The manually configured ID of the customAction button that was clicked.
customAction.numpadValue number (optional) The current value of the POS numpad input.

tableOrder

Property Type Explanation
customAction.customActionId text The manually configured ID of the customAction button that was clicked.
customAction.numpadValue number (optional) The current value of the POS numpad input.

order

Property Type Explanation
customAction.customActionId text The manually configured ID of the customAction button that was clicked.
customAction.numpadValue number (optional) The current value of the POS numpad input.

table

Property Type Explanation
customAction.customActionId text The manually configured ID of the customAction button that was clicked.
customAction.numpadValue number (optional) The current value of the POS numpad input.

course

Property Type Explanation
customAction.customActionId text The manually configured ID of the customAction button that was clicked.
customAction.numpadValue number (optional) The current value of the POS numpad input.

error

Property Type Explanation
error.code string One of the Error Codes.
error.message string Additional descriptive explanation of the cause of the error.

lineChanges

Property Type Explanation
lineChanges[].lineId uuid The UUID of the session line that you want to change.
lineChanges[].externalDiscount externalDiscount (optional) The details of an external discount are explained below.
externalDiscount.discountId uuid This is a UUID you
generate and store to remember that you applied this discount.
externalDiscount.discountPercentage number (optional) The discount percentage that you want to apply to the line.
externalDiscount.applyToQuantity number (optional) The quantity of this line that you want to apply the discount too. For example, if the quantity of the line is 2, but you want to apply the discount to 1 of these 2.
externalDiscount.discountAmount number (optional) The exact amount
of discount percentage that you want to apply to the line.
externalDiscount.discountDescription string (optional) A descriptive label for the discount.

lineAdditions

Property Type Explanation
lineAdditions[].lineId uuid (optional) The UUID of the session line that you want to add. You are allowed to generate this. If you ommit this an UUID will be generated automatically, but it will be more difficult for you to know which line you added.
lineAdditions[].articleNumber bigint This number should be present in the MplusKASSA administration.
lineAdditions[].barcode string This barcode should be present in the MplusKASSA administration.
lineAdditions[].pluNumber string This PLU number should be present in the MplusKASSA administration.
lineAdditions[].supplierArticleNumber string This supplier article number should be present in the MplusKASSA administration.
lineAdditions[].extArticleId string This external article ID should be present in the MplusKASSA administration.
You can add an article through articleNumber, barcode, pluNumber, supplierArticleNumber, extArticleId, or a combination thereof.
lineAdditions[].priceIncl number (optional)
The line’s price including VAT. If you ommit this, the default price will be used.
lineAdditions[].quantity number (optional) The line’s price including VAT. If you ommit this, a default quantity of 1 will be used.
lineAdditions[].text string (optional) The line’s price including VAT. If you ommit this, the default article text will be used.
lineAdditions[].externalDiscount externalDiscount (optional) See the explanation at session for more details.

lineDeletions

Property Type Explanation
lineDeletions[].lineId uuid The UUID of the session line that you want to delete.
It is possible that your request for deletion will be denied. For example, you can only delete lines that you yourself added. You will receive an error message if this is the case.

lockSession

Added in MplusKASSA v11.1.0

Property Type Explanation
lockSession boolean Locks or unlocks the session from further changes.

lockSessionForAdditions

Added in MplusKASSA v16.2.0

Property Type Explanation
lockSessionForAdditions boolean Locks or unlocks the session from further additions (deletions/decreases are allowed).

receiptFooter

Attention: receiptFooter only works with the completeSession event.

Or for multiple footers, use an array:

Property Type Explanation
receiptFooter.text string (optional) The additional text that you want to print on the receipt footer. New lines ( \n) are supported.
receiptFooter.barcode.codeType string (optional) The type of barcode you want to print on the receipt footer. Available types are: code128 (default) or qrcode.
receiptFooter.barcode.code string (optional) The code that you want to be printed as a barcode on the receipt footer.
receiptFooter.printSeparate boolean (optional) Set to true if the footer should be printed separately from the receipt. (The receipt printer will make a cut between the receipt and this footer.)
It is possible that your request for extra data on the footer will be denied. You will receive an error message if this is the case, and the receipt will be printed without
your additional data.

If you do not see the receipt footer text and/or code appear on the printed receipt, it is possible that the receipt layout is not properly configured. Please contact our support at dev@mpluskassa.nl so we can help you resolve this issue.

billFooter

Added in MplusKASSA v16.2.0

Attention: billFooter only works with the printBill event.

The JSON details of billFooter are identical to receiptFooter.

dialog

Property Type Explanation
dialog.required boolean Is a choice required?
dialog.allowMultipleOptions boolean Is more than one choice allowed?
dialog.dialogTitle string Which title should the dialog show?
dialog.dialogOptions[].optionId int The option’s ID.
dialog.dialogOptions[].optionName string The option’s textual description.
dialog.dialogOptions[].optionColor string The option’s color in hexadecimal format.

message

Please note that the message property is an array that allows for multiple messages to be returned in a single reply.
Property Type Explanation
message[].message text (optional) Show a message on the POS user’s display..
message[].customerMessage text (optional) Show a message on the POS customer display.
message[].displayTime int (optional) This will ensure the message and customerMessage are shown for at least this amount of seconds.
message[].messageDisplayTime int (optional) This will ensure the message is shown for at least this amount of seconds.
message[].customerMessageDisplayTime int (optional) This will ensure the customerMessage is shown for at most this amount of seconds.
message[].hideTimestamp boolean (optional) When set to true, this will hide the timestamps that are usually shown in front of the messages.
message[].clearScreen boolean (optional) When set to true, this will clear all previous messages.
message[].clearCustomerScreen boolean (optional) When set to true, this will clear the current customer message.
message[].monospacedFont boolean (optional) When set to true, this will display the messages in a monospaced font so you can better align multiple lines.

requestScanCode

Added in MplusKASSA v13.1.0

Property Type Explanation
requestScanCode.required boolean Is a scan required?
requestScanCode.requestTitle boolean What would you like the POS screen to display to the user?

dialog

Property Type Explanation
dialog.selectedDialogOptionIds int[] The ID’s of the selected dialog option. Can be zero, one or more.
On top of this, you also receive all the original data from the event.

polling

Added in MplusKASSA v11.3.0

Property Type Explanation
polling.finished boolean Tell MplusKASSA whether the polling process is finished or not. When you return false, MplusKASSA will immediately resend the request to your endpoint.
polling.message text (optional) Show a message on the POS user’s display. Use this to update the user on progress made in the polling process.
polling.customerMessage text (optional) Show a message on the POS customer display. Use this to update the customer on progress made in the polling process.
polling.displayTime int (optional) This will ensure the message and customerMessage are shown for at least this amount of seconds.
polling.messageDisplayTime int (optional) This will ensure the message is shown for at least this amount of seconds.
polling.customerMessageDisplayTime int (optional) This will ensure the customerMessage is shown for at most this amount of seconds.
polling.hideTimestamp boolean (optional) When set to true, this will hide the timestamps that are usually shown in front of the messages.
polling.clearScreen boolean (optional) When set to true, this will clear all previous messages.
polling.clearCustomerScreen boolean (optional) When set to true, this will clear the current customer message.
polling.monospacedFont boolean (optional) When set to true, this will display the messages in a monospaced font so you can better align multiple lines.

customActionChange

Added in MplusKASSA v15.1.0

Property Type Explanation
customActionChange.customActionId text The ID of the customAction button that should be changed.
customActionChange.buttonCaption text The desired new caption for the customAction button.

vatMethodChange

Added in MplusKASSA v15.1.0

Property Type Explanation
vatMethodChange text inclusive, exclusive, shifted

externalCardScan

Added in MplusKASSA v16.2.0

Property Type Explanation
externalCardScan.cardIdentifier text (optional) Use any kind of string that you use as identifier for this card within your system. Does not need to be present within the POS.
externalCardScan.cardDescription text (optional) Enter the name of the card owner, or a description of the card itself.
externalCardScan.cardBalance number (optional) The card’s current balance.
externalCardScan.cardExpiration datetime (optional) The date and time when the card expires and is no longer usable. Please note that we do not actually do anything with this date, it is only used for informational purposes in the POS.
Even though all properties are optional, nothing will be displayed on the POS if you omit them all.

prepayTable

Added in MplusKASSA v16.2.0

Property Type Explanation
prepayTable.table.number table Designate the table’s number that the payments are meant for.
prepayTable.table.subNumber table (optional) Designate the table’s subnumber that the payments are meant for.
prepayTable.payments[].paymentId uuid Provide a unique ID, the POS will use to make sure this payment is not registered more than once.
prepayTable.payments[].amount number The amount that was paid.
prepayTable.payments[].method text (optional) The method that you want to register this payment to. If omitted, the POS uses the generic WEBHOOK payment method.

requestCustomAction

Added in MplusKASSA v17.0.0

Property Type Explanation
requestCustomAction.customActionId text The manually configured ID of the customAction button that you would like to trigger.
It is important to realize that this is a request to trigger the custom action, not a guarantee that it will. Reasons why the custom action may not trigger are: (1) the POS is not running, (2) the POS is currently in an interrupted state (like processing an electronic payment), (3) the POS currently has no logged in user or (4) the POS is currently in a blocked state (like displaying a dialog).

dialog

Property Type Explanation
dialog.selectedDialogOptionIds int[] The ID’s of the selected dialog option. Can be zero, one or more.
On top of this, you also receive all the original data from the event.

error

Property Type Explanation
error.code string One of the Error Codes.
error.message string Additional descriptive explanation of the cause of the error.
original object All of the details of the original event.