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. If you don’t reply within 60 seconds, we immediately resend the same request.

After a reply, we also immediately resend the same request.

This loop continues until (1) you let us know payment succeeded, (2) you let us know payment didn’t succeed or (3) a cancel request ( requestCancelExternalPayment) is sent from the POS.

» » » 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, or (4) 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 return that you did, or if it is no longer possible to cancel, you should communicate this to the POS operator through an understandable message.

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

Or you should let the POS operator know that cancellation is not possible.

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.