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. -
Payment through POS
This examples outlines a method to process a payment through the POS without the POS knowing anything about the item(s) that are being paid for.
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. |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
POST https://www.example.com/webhooks/addSessionLine X-Mplus-Subscription-Id: example_subscription X-Mplus-Signature: ... Content-Type: application/json Accept: application/json { "addSessionLine": { "line": { "articleNumber": 235, "lineId": "c686f63d-46a7-498e-b421-c72e5cb7136b", "priceIncl": 9.50, "quantity": 1, "text": "Tour Ticket (Adult)" } }, (...) } |
| « « « 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. |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 |
{ "dialog": { "required": true, "allowMultipleOptions": false, "dialogTitle": "Select the desired time slot", "dialogOptions": [ { "optionId": 1, "optionName": "10:00-11:00 (3 seats available)" }, { "optionId": 2, "optionName": "11:00-12:00 (15 seats available)" }, { "optionId": 3, "optionName": "12:00-13:00 (9 seats available)" }, { "optionId": 4, "optionName": "13:00-14:00 (22 seats available)" } ] } } |
| » » » 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. |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 |
POST https://www.example.com/webhooks/addSessionLine X-Mplus-Subscription-Id: example_subscription X-Mplus-Signature: ... Content-Type: application/json Accept: application/json { "dialog": { "selectedDialogOptionIds": [1] }, "addSessionLine": { "line": { "articleNumber": 235, "lineId": "c686f63d-46a7-498e-b421-c72e5cb7136b", "priceIncl": 9.50, "quantity": 1, "text": "Tour Ticket (Adult)" } }, (...) } |
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. |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 |
POST https://www.example.com/webhooks/completeSession X-Mplus-Subscription-Id: example_subscription X-Mplus-Signature: uZucqk+xPZii7TmP1IHOKPoS4/K+8ejNwl7EyxnEzs4= Content-Type: application/json Accept: application/json { "event": { "eventBlocking": true, "eventCounter": 1, "eventTimestamp": "2017-08-09T16:07:33.964+02:00" }, "sender": { "branchNumber": 1, "workplaceNumber": 1 }, "session": { "lines": [ { "articleNumber": 235, "lineId": "c686f63d-46a7-498e-b421-c72e5cb7136b", "priceIncl": 9.50, "quantity": 1, "text": "Tour Ticket (adult)" } ], "sessionId": "5eea25d4-4188-43b8-9a66-8086561d590c" }, "payments": [ { "method": "CONTANT", "description": "Contant", "amount": 9.50 } ] } |
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
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. |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
POST https://www.example.com/webhooks/startExternalPayment X-Mplus-Subscription-Id: example_subscription X-Mplus-Signature: ... Content-Type: application/json Accept: application/json { "externalPayment": { "externalPaymentId": "7a4d4fe3-25c8-4159-923a-5fc2fd596b26", "method": "K_CASH_MACHINE", "description": "Cash Machine", "amount": 11.25 }, "session": (...) } |
| « « « 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. |
|
1 2 3 4 5 6 7 8 |
{ "externalPayment": { "externalPaymentId": "7a4d4fe3-25c8-4159-923a-5fc2fd596b26", "started": true, "message": "Payment ready to be started", "customerMessage": "Please insert EUR 11.25" } } |
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. |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
POST https://www.example.com/webhooks/pollExternalPayment X-Mplus-Subscription-Id: example_subscription X-Mplus-Signature: ... Content-Type: application/json Accept: application/json { "externalPayment": { "externalPaymentId": "7a4d4fe3-25c8-4159-923a-5fc2fd596b26", "method": "K_CASH_MACHINE", "description": "Cash Machine", "amount": 11.25 } } |
| « « « Response « « « |
|---|
| In the response, you can send a message to be placed on the POS screen. |
|
1 2 3 4 5 6 7 |
{ "externalPayment": { "externalPaymentId": "7a4d4fe3-25c8-4159-923a-5fc2fd596b26", "message": "EUR 10.00 of 11.25 inputted", "customerMessage": "EUR 1.25 remaining" } } |
| » » » 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). |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
POST https://www.example.com/webhooks/pollExternalPayment X-Mplus-Subscription-Id: example_subscription X-Mplus-Signature: ... Content-Type: application/json Accept: application/json { "externalPayment": { "externalPaymentId": "7a4d4fe3-25c8-4159-923a-5fc2fd596b26", "method": "K_CASH_MACHINE", "description": "Cash Machine", "amount": 11.25 }, "session": (...) } |
| « « « Response « « « |
|---|
| In the response, you can confirm the payment. |
|
1 2 3 4 5 6 |
{ "externalPayment": { "externalPaymentId": "7a4d4fe3-25c8-4159-923a-5fc2fd596b26", "confirmed": true } } |
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. |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
POST https://www.example.com/webhooks/requestCancelExternalPayment X-Mplus-Subscription-Id: example_subscription X-Mplus-Signature: ... Content-Type: application/json Accept: application/json { "externalPayment": { "externalPaymentId": "7a4d4fe3-25c8-4159-923a-5fc2fd596b26", "method": "K_CASH_MACHINE", "description": "Cash Machine", "amount": 11.25 }, "session": (...) } |
| « « « Response « « « |
|---|
| In the response, you should confirm that you cancelled the payment. |
|
1 2 3 4 5 6 |
{ "externalPayment": { "externalPaymentId": "7a4d4fe3-25c8-4159-923a-5fc2fd596b26", "cancelled": true } } |
| Or you should let the POS operator know that cancellation is not possible. |
|
1 2 3 4 5 6 7 |
{ "externalPayment": { "externalPaymentId": "7a4d4fe3-25c8-4159-923a-5fc2fd596b26", "cancelled": false, "message": "Unable to cancel, the payment process is almost completed. Please wait a few seconds." } } |
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. |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
POST https://www.example.com/webhooks/cancelExternalPayment X-Mplus-Subscription-Id: example_subscription X-Mplus-Signature: ... Content-Type: application/json Accept: application/json { "externalPayment": { "externalPaymentId": "7a4d4fe3-25c8-4159-923a-5fc2fd596b26", "method": "K_CASH_MACHINE", "description": "Cash Machine", "amount": 11.25 }, "session": (...) } |
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
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. |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
POST https://www.example.com/webhooks/startExternalPayment X-Mplus-Subscription-Id: example_subscription X-Mplus-Signature: ... Content-Type: application/json Accept: application/json { "externalPayment": { "externalPaymentId": "f0892a08-a286-4738-9263-f5ec22ffc7a1", "method": "K_RESERVATION_SYSTEM", "description": "Reserveringen", "amount": 16.84 }, "session": (...) } |
| « « « Response « « « |
|---|
| In the response, you then return a dialog that lists the available reservations. |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 |
{ "dialog": { "required": true, "allowMultipleOptions": false, "columns": 3, "dialogTitle": "Select the correct reservation", "dialogOptions": [ { "optionId": 1, "optionName": "Mr. J. Smith (Mon-Tue)" }, { "optionId": 2, "optionName": "Mrs. D. Doe (Mon-Wed)" }, { "optionId": 3, "optionName": "Mr. & Mrs. A. Nonymous (Sat-Fri)" }, { "optionId": 4, "optionName": "Big Company Ltd. (Tue)" } ] }, "externalPayment": { "externalPaymentId": "f0892a08-a286-4738-9263-f5ec22ffc7a1" } } |
| » » » 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. |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
POST https://www.example.com/webhooks/startExternalPayment X-Mplus-Subscription-Id: example_subscription X-Mplus-Signature: ... Content-Type: application/json Accept: application/json { "dialog": { "selectedDialogOptionIds": [3] }, "externalPayment": { "externalPaymentId": "f0892a08-a286-4738-9263-f5ec22ffc7a1", "method": "K_RESERVATION_SYSTEM", "description": "Reserveringen", "amount": 16.84 }, "session": (...) } |
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). |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
POST https://www.example.com/webhooks/pollExternalPayment X-Mplus-Subscription-Id: example_subscription X-Mplus-Signature: ... Content-Type: application/json Accept: application/json { "dialog": { "selectedDialogOptionIds": [3] }, "externalPayment": { "externalPaymentId": "f0892a08-a286-4738-9263-f5ec22ffc7a1", "method": "K_RESERVATION_SYSTEM", "description": "Reserveringen", "amount": 16.84 }, "session": (...) } |
| « « « Response « « « |
|---|
| In the response, you can confirm the booking on the reservation. |
|
1 2 3 4 5 6 |
{ "externalPayment": { "externalPaymentId": "f0892a08-a286-4738-9263-f5ec22ffc7a1", "confirmed": true } } |
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. |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
POST https://www.example.com/webhooks/cancelExternalPayment X-Mplus-Subscription-Id: example_subscription X-Mplus-Signature: ... Content-Type: application/json Accept: application/json { "externalPayment": { "externalPaymentId": "f0892a08-a286-4738-9263-f5ec22ffc7a1", "method": "K_RESERVATION_SYSTEM", "description": "Reserveringen", "amount": 16.84 }, "session": (...) } |
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.
Payment through POS
This examples outlines a possible way to have an item or list of items paid through the POS, without the POS knowing anything about the items. We will use the following webhooks for this integration: scanCode and completeSession.
Webhook scanCode
Whenever a barcode or qr code is scanned through the POS, you will receive a notification about this through the scanCode webhook.
This concludes the Payment through POS example. Please contact us at dev@mpluskassa.nl if you have any questions about setting up a system like this.