{
information: {
elements: [ ... ],
recipient: "CUSTOMER" or "MERCHANT"
}
}Generally there are are two ways to process payments on a terminal:
Use the terminal in the standalone mode where the cashier is entering the amount to charge on the terminal or
connect the till to the terminal and allow the till to coordinate the payment on the terminal.
In the standalone mode there is no integration required and as such it can be simply used. The transactions done on the terminal will appear in the transaction list once they are executed.
To connect the till with the terminal consists on the following steps:
Ensure the terminal is connected to the Internet. This might be different depending on the terminal hardware.
Create a transaction with the Transaction Service. Use the create operation to create a new transaction.
Use the till-connection-credentials method of the Transaction Terminal Service to get connection credentials for your transaction and the terminal it should be processed on.
Connect your till to initialize the processing of the payment by using WebSockets. You need to implement some interactive process through the WebSocket.
The creation of the transaction is done in the same way as for any other integration. The details of the WebSocket integration are described in the following sections.
As there are interactions between the cashier and the terminal during the payment process a technique has to be used which supports this. Specifically the interaction requires a two way communication. WebSockets allow this kind of communication.
Within the WebSocket the STOMP protocol is used to exchange messages. See https://stomp.github.io/stomp-specification-1.2.html
The connect will open the connection and as a result the transaction processing on the terminal will start. All the details about the transaction
like amount etc. is taken from the transaction object as created earlier with the Transaction Service over the regular REST API.
When the WebSocket is breaking because of a network issue (e.g. in a mobile network this can happen often) the payment processing will not stop. The WebSocket
can be again opened and the Connect can be sent again. The transaction is tried to be resumed. If the timeout has been reached the transaction will fail and
accordingly the error message will be sent from the server. In this case a new transaction must be started.
The messages to display on the till are passed as plain JavaScript objects and can contain the following elements.
The notification contains information to display to the attendant on the till.
{
information: {
elements: [ ... ],
recipient: "CUSTOMER" or "MERCHANT"
}
}The question contains information to display to the attendant on the till and options he needs to chose from.
{
information: {
elements: [ ... ],
recipient: "CUSTOMER" or "MERCHANT"
},
options: [
{
identifier: "option-1",
text: "First option",
primary: true
},
{
identifier: "option-2",
text: "Second option",
primary: false
}
]
}Errors to WebSocket requests contain the following information.
{
id: "ab-1234567 (2000-01-01T00:00:00.000Z)",
date: "2000-01-01T00:00:00.000",
message: "Translated error message",
defaultMessage: "English error message",
type: "END_USER_ERROR" or "CONFIGURATION_ERROR" or "DEVELOPER_ERROR" or "SERVER_ERROR"
}Paragraph
The paragraph represents a block of text.
Ridiculus metus pulvinar morbi natoque sem etiam dictum, hac ipsum placerat risus orci est ante, fames tellus felis erat elit gravida. Euismod facilisis gravida sollicitudin nisi pellentesque tincidunt enim fusce dictum sit, odio magna feugiat interdum varius himenaeos diam venenatis sociis.
{
text: "Ridiculus metus pulvinar morbi natoque sem etiam dictum, hac ipsum placerat risus orci est ante, fames tellus felis erat elit gravida. Euismod facilisis gravida sollicitudin nisi pellentesque tincidunt enim fusce dictum sit, odio magna feugiat interdum varius himenaeos diam venenatis sociis.",
type: "PARAGRAPH"
}Ordered List
The ordered list represents a numbered list of items:
First
Second
Third
{
items: [
{ text: "First" },
{ text: "Second" },
{ text: "Third" }
],
type: "ORDERED_LIST"
}Unordered List
The unordered list represents a list of items with bullet points.
First
Second
Third
{
items: [
{ text: "First" },
{ text: "Second" },
{ text: "Third" }
],
type: "UNORDERED_LIST"
}Description List
The ordered list represents a list of items with description.
The first element
The second element
The third element
{
items: [
{
description: "First",
text: "The first element"
},
{
description: "Second",
text: "The second element"
},
{
description: "Third",
text: "The third element"
}
],
type: "DESCRIPTION_LIST"
}Table
| Text | Number | Amount |
|---|---|---|
First |
1 |
USD1.00 |
Second |
2 |
CHF2.00 |
Third |
3 |
EUR3.00 |
{
columns: [
{
identifier: "text",
text: "Text",
type: "TEXT"
},
{
identifier: "number",
text: "Number",
type: "NUMBER"
},
{
identifier: "amount",
text: "Amount",
type: "AMOUNT"
}
],
rows: [
{ cells: [
{ column: "text", text: "First" },
{ column: "number", text: "1" },
{ column: "amount", text: "USD1.00" }
] },
{ cells: [
{ column: "text", text: "Second" },
{ column: "number", text: "2" },
{ column: "amount", text: "CHF2.00" }
] },
{ cells: [
{ column: "text", text: "Third" },
{ column: "number", text: "3" },
{ column: "amount", text: "EUR3.00" }
] },
],
type: "TABLE"
}To connect your till via a WebSocket using JavaScript, we recommend using our TerminalTillConnection JavaScript utility.
Include the JavaScript file of the utility.
<script src="https://app-wallee.com/assets/payment/terminal-till-connection.js" type="text/javascript"></script>Create a new instance of TerminalTillConnection passing the WebSocket URL, the connection credentials as options.
var tillConnection = new TerminalTillConnection({
url: "wss://app-wallee.com/terminal-websocket",
token: "[connection-credentials]"
});Subscribe to events to handle messages from the terminal.
tillConnection.subscribe("notification", function(payload){
// Display the information on the till.
});
tillConnection.subscribe("question", function(payload, callback){
// Display the question on the till and allow the attendant to chose one of the options.
// Call the callback method with the chosen option's identifier as argument.
callback(optionIdentifier);
});
tillConnection.subscribe("charged", function(){
// The transaction has been successfully charged.
});
tillConnection.subscribe("canceled", function(){
// The payment was canceled.
});
tillConnection.subscribe("error", function(error){
// An error occurred during the process of a WebSocket request.
});
tillConnection.subscribe("connected", function(){
// The connection has been established.
});
tillConnection.subscribe("disconnected", function(){
// The connection has been disconnected or lost.
});Establish the connection.
tillConnection.connect();Use the cancel method to cancel the payment.
tillConnection.cancel();