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.
  • session Contains the details of the current session.

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

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.
  • receiptFooter (only works with completeSession)
    Request some extra data to be printed on the footer of the receipt.
  • dialog
    Request a dialog to show up on screen.

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.

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.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.

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

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

receiptFooter

Attention: receiptFooter only works with the completeSession event.

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.
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 us at dev@mpluskassa.nl so we can help you resolve this issue.

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

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.