In general there are three APIs how you can interact with the terminal via API:
Cloud Till Interface: By using the cloud interface you are using a public reachable API to interact with the terminal device. The benefit is you do not need to know where the device is located and it works from any network. However there is a higher delay compared to other integration methods because the communication happens via a central server. The Cloud Till Interface documentation can be found below.
Local Till Interface: By using the local till interface you connect directly with a socket to the terminal device. The benefit is that you have a fast connection as both your application and the terminal device are in the same local network. The drawback is that you need to know the terminal's IP address. The Local Till Interface documentation changes depending on the application version installed on the terminal device.
Android Till Interface: By using the Android till interface you can directly talk to the terminal software. The benefit is that you can use an Android SDK to interact with the terminal but you can do that only for applications that will run on the terminal. If the application is not running on the terminal the Android till interface does not work. For the Android Till Interface you will need to add the SDK to your Android app as a dependency.
For testing and publication of your Android app please get in contact with us.
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.
If you plan to integrate your application with the terminal you have the following options:
Connect to the terminal through a socket in the local network. If you are looking for this integration please get in contact with us.
Connect to the terminal through a websocket. The WebSocket will use a server from our side to connect to the terminal device.
Connect to the terminal through a long polling HTTP request.
The rest of the documentation focus on the two later connection methods. The connection methods are in general very similar:
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.
Connect your till to initialize the processing of the payment by using WebSockets or the long polling mechanism.
The creation of the transaction is done in the same way as for any other integration.
When you are not sure which method to use we have tried to list some properties of the different methods:
Long polling is simpler to integrate as the WebSockets long polling uses just a standard web service operation.
Long polling does not offer any interaction with the attendee. Those interactions allow a better experience for the attendee.
Als ersten Schritt müssen Sie eine Transaktion erstellen. Dafür können Sie den Transaction Service und
die Operation Erstellen verwenden.
Anschliessend können Sie die Operation Transaktion durchführen verwenden, um
auf dem Terminal eine Transaktion auszulösen. Die Operation perform transaction beantwortet die HTTP-Anfrage für rund
maximal 80 Sekunden nicht. Während dieser Zeit versucht das Terminal, die Transaktion durchzuführen. Wenn die Transaktion erfolgreich ist oder fehlschlägt, gibt die
Operation perform transaction das Ergebnis sofort zurück. Falls das Terminal mehr Zeit benötigt, antwortet die Methode
mit dem HTTP-Status 543. In diesem Fall muss die Methode erneut mit denselben Parametern aufgerufen werden.
Der folgende Pseudocode zeigt, wie das Muster implementiert werden kann:
function carryOutTransaction(spaceId, terminalId, transactionId) {
for (i = 0; i < 10; i++) {
try {
paymentTerminalTillService.performTransaction(spaceId, transactionId, terminalId);
}
catch(Exception e) {
// We log the exception but do not stop the processing. Generally
// it is better not just to repeat with the status code 543 rather also
// with any other error that can be caused by a connection issue.
log(e);
}
}
}Es gibt zwei verschiedene perform transaction-Operationen auf dem Payment Terminal Till Service:
Sie können die Transaktion mit der Terminal-ID durchführen oder
Sie können die Transaktion mit dem Terminal-Identifier durchführen.
Der Terminal-Identifier ist die ID, die Sie auch auf dem Beleg usw. sehen. Das Muster ist 3xxx xxxx. Der Terminal-Identifier hingegen ist eine kürzere Nummer, die nur innerhalb des Portals sichtbar ist.
Da es während des Zahlungsprozesses Interaktionen zwischen dem Kassierer und dem Terminal gibt, muss eine Technik verwendet werden, die dies unterstützt. Konkret erfordert die Interaktion eine bidirektionale Kommunikation. WebSockets ermöglichen diese Art der Kommunikation.
Innerhalb des WebSockets wird das STOMP-Protokoll verwendet, um Nachrichten auszutauschen. Siehe https://stomp.github.io/stomp-specification-1.2.html
Der Connect öffnet die Verbindung, und als Ergebnis startet die Transaktionsverarbeitung auf dem Terminal. Alle Details zur Transaktion
wie Betrag usw. werden dem Transaktionsobjekt entnommen, das zuvor mit dem Transaction Service über die reguläre REST-API erstellt wurde.
Wenn der WebSocket wegen eines Netzwerkproblems abbricht (z.B. in einem Mobilfunknetz kann dies häufig vorkommen), stoppt die Zahlungsverarbeitung nicht. Der WebSocket
kann erneut geöffnet und der Connect erneut gesendet werden. Es wird versucht, die Transaktion fortzusetzen. Wenn das Timeout erreicht wurde, schlägt die Transaktion fehl und
entsprechend wird die error-Nachricht vom Server gesendet. In diesem Fall muss eine neue Transaktion gestartet werden.
Die auf der Kasse anzuzeigenden Nachrichten werden als einfache JavaScript-Objekte übergeben und können die folgenden Elemente enthalten.
Die Benachrichtigung enthält Informationen, die dem Bediener an der Kasse angezeigt werden.
{
information: {
elements: [ ... ],
recipient: "CUSTOMER" or "MERCHANT"
}
}Die Frage enthält Informationen, die dem Bediener an der Kasse angezeigt werden, sowie Optionen, aus denen er wählen muss.
{
information: {
elements: [ ... ],
recipient: "CUSTOMER" or "MERCHANT"
},
options: [
{
identifier: "option-1",
text: "First option",
primary: true
},
{
identifier: "option-2",
text: "Second option",
primary: false
}
]
}Fehler zu WebSocket-Anfragen enthalten die folgenden Informationen.
{
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"
}Absatz
Der Absatz stellt einen Textblock dar.
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"
}Geordnete Liste
Die geordnete Liste stellt eine nummerierte Liste von Einträgen dar:
First
Second
Third
{
items: [
{ text: "First" },
{ text: "Second" },
{ text: "Third" }
],
type: "ORDERED_LIST"
}Ungeordnete Liste
Die ungeordnete Liste stellt eine Liste von Einträgen mit Aufzählungspunkten dar.
First
Second
Third
{
items: [
{ text: "First" },
{ text: "Second" },
{ text: "Third" }
],
type: "UNORDERED_LIST"
}Beschreibungsliste
Die geordnete Liste stellt eine Liste von Einträgen mit Beschreibung dar.
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"
}Tabelle
| 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"
}Um Ihre Kasse über einen WebSocket mit JavaScript zu verbinden, empfehlen wir die Verwendung unseres JavaScript-Utilities TerminalTillConnection.
Binden Sie die JavaScript-Datei des Utilities ein.
<script src="https://app-wallee.com/assets/payment/terminal-till-connection.js" type="text/javascript"></script>Erstellen Sie eine neue Instanz von TerminalTillConnection und übergeben Sie die WebSocket-URL und die Verbindungs-Zugangsdaten als Optionen.
var tillConnection = new TerminalTillConnection({
url: "wss://app-wallee.com/terminal-websocket",
token: "[connection-credentials]"
});Abonnieren Sie die Ereignisse, um Nachrichten vom Terminal zu verarbeiten.
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.
});Stellen Sie die Verbindung her.
tillConnection.connect();Verwenden Sie die Methode cancel, um die Zahlung abzubrechen.
tillConnection.cancel();