Grundsätzlich gibt es zwei Möglichkeiten, Zahlungen auf einem Terminal zu verarbeiten:
Verwenden Sie das Terminal im Standalone-Modus, in dem die Kassenperson den zu belastenden Betrag auf dem Terminal eingibt, oder
verbinden Sie die Kasse mit dem Terminal und lassen Sie die Kasse die Zahlung auf dem Terminal koordinieren.
Im Standalone-Modus ist keine Integration erforderlich und das Terminal kann somit einfach verwendet werden. Die auf dem Terminal getätigten Transaktionen erscheinen in der Transaktionsliste, sobald sie ausgeführt wurden.
Wenn Sie planen, Ihre Anwendung mit dem Terminal zu integrieren, haben Sie die folgenden Möglichkeiten:
Verbinden Sie sich über einen Socket im lokalen Netzwerk mit dem Terminal. Wenn Sie an dieser Integration interessiert sind, nehmen Sie bitte Kontakt mit uns auf.
Verbinden Sie sich über einen WebSocket mit dem Terminal. Der WebSocket nutzt einen Server auf unserer Seite, um sich mit dem Terminalgerät zu verbinden.
Verbinden Sie sich über eine Long-Polling-HTTP-Anfrage mit dem Terminal.
Der Rest der Dokumentation konzentriert sich auf die beiden letztgenannten Verbindungsmethoden. Die Verbindungsmethoden sind im Allgemeinen sehr ähnlich:
Stellen Sie sicher, dass das Terminal mit dem Internet verbunden ist. Dies kann je nach Terminal-Hardware unterschiedlich sein.
Erstellen Sie eine Transaktion mit dem Transaction Service. Verwenden Sie die create-Operation, um eine neue Transaktion zu erstellen.
Verbinden Sie Ihre Kasse, um die Verarbeitung der Zahlung über WebSockets oder den Long-Polling-Mechanismus zu initialisieren.
Die Erstellung der Transaktion erfolgt auf die gleiche Weise wie bei jeder anderen Integration.
Wenn Sie nicht sicher sind, welche Methode Sie verwenden sollen, haben wir versucht, einige Eigenschaften der verschiedenen Methoden aufzulisten:
Long Polling ist einfacher zu integrieren, da das Long Polling über WebSockets lediglich eine standardmässige Webservice-Operation verwendet.
Long Polling bietet keine Interaktion mit dem Kunden. Solche Interaktionen ermöglichen ein besseres Erlebnis für den Kunden.
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://staging-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://staging-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();