Example Flows

This page outlines some examples on how you can use the MplusKASSA Webhooks. Do you have an interesting idea for a way to use our webhooks? Please don’t hesitate to contact us at dev@mpluskassa.nl to discuss the possibilities.


Contents

  • Ticketing with Time Slots
    This examples outlines a possible way to sell tickets where the available time slots can change dynamically based on time and tickets already sold.
  • Cash Machine Payment
    This examples outlines a possible way to send a payable amount to an external payment device (like a cash machine).
  • Book on Reservation
    This examples outlines a possible way to send the list of articles ordered on the POS to an external reservation system, where a complete customer invoice can then later be generated.
  • Loyalty Vouchers
    This examples outlines a method to easily add a way to track loyalty and accept vouchers distributed based on customer loyalty.

Ticketing with Time Slots

This examples outlines a possible way to sell tickets where the available time slots can change dynamically based on time and tickets already sold. We are going to be using two webhooks, addSessionLine and completeSession.

Webhook addSessionLine

This event will be used to signal the external system that a “ticket” article has been added to the session.

» » » Request » » »
In the request, you can see that an article named “Tour Ticket (Adult)” was added. The POS has no knowledge about available time slots, but you can “fake” this knowledge by returning this information in the response.

« « « Response « « «
In the response, “fake” the knowledge by returning the available time slots, together with some additional details like seats left. This will show up in the POS as an interactive dialog.

Ticketing with Time Slots Dialog

» » » Request » » »
The next request will include the selected dialog option, in this case it was option 1, the “10:00-11:00” time slot. Use this request to make a reservation for the selected time slot.

Webhook completeSession

This event will be used to signal to the external system that the ticket has been paid for. At this point in time, the ticket reservation may be confirmed and optionally tickets could be printed.

» » » Request » » »
After payment has been completed, you will receive the full receipt details. Knowing that payment has been completed, you can use this moment to make the ticket reservation permanent and print the tickets.

This concludes the Ticketing with Time Slots example. Please contact us at dev@mpluskassa.nl if you have any questions about setting up a system like this.


Cash Machine Payment

Please note that the startExternalPayment/pollExternalPayment/requestCancelExternalPayment/cancelExternalPayment webhooks have not yet been implemented and the technical details have not yet been finalized. Use this chapter only as an indication of where we are headed, but not as a basis for actual development.

This examples outlines a possible way to send a payable amount to an external payment device (like a cash machine). We have implemented a dedicated “External Payment” flow to handle these kinds of integrations. This example will showcase how the POS starts an external payment, how it waits for a successful payment, and how it can display status messages from the external system in the meantime. We are going to be using four webhooks, startExternalPayment, pollExternalPayment, requestCancelExternalPayment and cancelExternalPayment.

Webhook startExternalPayment

After the POS operator has confirmed the use of the external payment method, this event is triggered once to signal to the external system that the payment process can be started. You will only receive this request if you have configured a payment method to work with your integration.

<<< we will insert an image here to display the correct POS configuration >>>

» » » Request » » »
In the request, you will receive all the relevant details of the payment that was started. Pay special attention to the externalPaymentId. This is what uniquely identifies the current payment “process,” and should be used in all communication regarding this payment.

« « « Response « « «
In the response, you must acknowledge receipt of the request to start the external payment. Make sure you include the correct externalPaymentId. You can optionally return a message to be placed on the POS screen.

Webhook pollExternalPayment

This event is different from all other webhook events in that it is a long-polling request. We expect a response to this request approx. every 10 seconds. If you don’t reply within 30 seconds, we assume your system is unavailable or has timed out and we will stop the external payment process.

After a reply, we immediately resend the same request, which also needs to be replied to within 10 seconds. This continues until (1) you let us know payment succeeded, (2) you let us know payment didn’t succeed or (3) 30 seconds elapse and we assume your system is unavailable.

» » » Request (long-polling) » » »
The request will wait for a response until you (1) let us know payment succeeded, (2) let us know payment didn’t succeed, (3) respond with a text message, (4) a total of 30 seconds elapse or (5) the POS operator sends a cancel request.

« « « Response « « «
In the response, you can send a message to be placed on the POS screen.

» » » Request (long-polling) » » »
The request will wait for a response until you (1) confirm the payment, (2) not confirm the payment, (3) respond with a status message, or (4) the POS operator manually cancels the event (after at least 30 seconds have passed).

« « « Response « « «
In the response, you can confirm the payment.

Webhook requestCancelExternalPayment

This event signals to the external system that the POS operator would like to request a cancellation of the currently running payment process.

» » » Request » » »
When a cancellation is requested, you should cancel the current process ASAP and immediately return that you did, or use a response to the long-polling pollExternalPayment request to return that you did.

« « « Response « « «
In the response, you can confirm that you cancelled the payment.

Webhook cancelExternalPayment

This event signals to the external system that the payment process was forcefully cancelled by the POS operator.

» » » Request » » »
This event occurs when the POS operator decides that they no longer want to wait for the external system to reply. They cannot issue this command until at least 30 seconds have passed. Please pay attention to this event, because it means the POS will no longer be interested in the result of the payment process. This event is a courtesy event, meaning that the payment process on the POS will be cancelled either way, whether the external system acknowledges it or not.

This concludes the Cash Machine Payment example. Please contact us at dev@mpluskassa.nl if you have any questions about setting up a system like this.


Book on Reservation

Please note that the startExternalPayment/pollExternalPayment/requestCancelExternalPayment/cancelExternalPayment webhooks have not yet been implemented and the technical details have not yet been finalized. Use this chapter only as an indication of where we are headed, but not as a basis for actual development.

This examples outlines a possible way to send the list of articles ordered on the POS to an external reservation system, where a complete customer invoice can then later be generated. We will use the “External Payment” flow for this integration.

Webhook startExternalPayment

After the POS operator has confirmed the use of the external payment method, this event is triggered once to signal to the external system that the payment process can be started. You will only receive this request if you have configured a payment method to work with your integration.

<<< we will insert an image here to display the correct POS configuration >>>

» » » Request » » »
In the request, you will receive all the relevant details of the payment that was started. Pay special attention to the externalPaymentId. This is what uniquely identifies the current payment “process,” and should be used in all communication regarding this payment.

« « « Response « « «
In the response, you then return a dialog that lists the available reservations.

» » » Request » » »
In the next request, the selected dialog option (which is the desired reservation) is included. [3] means the reservation for “Mr. & Mrs. A. Nonymous (Sat-Fri)” was selected.

Webhook pollExternalPayment

This event is different from all other webhook events in that it is a long-polling request. That means it will keep waiting for a response until a response is given. From this point on, the external system determines when payment is complete and when the POS is ready to move on. If no response is given within 30 seconds, the POS operator gets the option to manually cancel the request. But this is not what should normally occur.

» » » Request (long-polling) » » »
The request will wait for a response until you (1) confirm the booking, (2) not confirm the booking, (3) respond with a status message, or (4) the POS operator manually cancels the event (after at least 30 seconds have passed).

« « « Response « « «
In the response, you can confirm the booking on the reservation.

Webhook cancelExternalPayment

This event signals to the external system that the payment process was cancelled by the POS operator.

» » » Request » » »
This event occurs when the POS operator decides that they no longer want to wait for the external system to reply. They cannot issue this command until at least 30 seconds have passed. Please pay attention to this event, because it means the POS will no longer be interested in the result of the payment process.

This concludes the Book on Reservation example. Please contact us at dev@mpluskassa.nl if you have any questions about setting up a system like this.