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.
Come primo passo dovete creare una transazione. A tale scopo potete utilizzare il Transaction Service e
l’operazione creare.
Successivamente potete utilizzare l’operazione eseguire la transazione per
avviare una transazione sul terminale. L’operazione perform transaction non risponde alla richiesta HTTP per circa
80 secondi al massimo. Durante questo tempo il terminale tenta di eseguire la transazione. Quando la transazione riesce o fallisce,
l’operazione perform transaction restituisce immediatamente il risultato. Nel caso in cui il terminale abbia bisogno di più tempo, il metodo risponde
con lo stato HTTP 543. In questo caso il metodo deve essere invocato nuovamente con gli stessi parametri.
Il seguente pseudocodice mostra come implementare questo schema:
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);
}
}
}Esistono due diverse operazioni perform transaction sul Payment Terminal Till Service:
Potete eseguire la transazione con l’ID del terminale oppure
Potete eseguire la transazione con l’identificativo del terminale.
L’identificativo del terminale è l’ID che vedete anche sulla ricevuta ecc. Lo schema è 3xxx xxxx. L’identificativo del terminale, invece, è un numero più corto visibile solo all’interno del portale.
Poiché durante il processo di pagamento ci sono interazioni tra il cassiere e il terminale, è necessario utilizzare una tecnica che le supporti. In concreto, l’interazione richiede una comunicazione bidirezionale. I WebSocket consentono questo tipo di comunicazione.
All’interno del WebSocket viene utilizzato il protocollo STOMP per scambiare messaggi. Vedere https://stomp.github.io/stomp-specification-1.2.html
La connessione apre il canale e, di conseguenza, l’elaborazione della transazione sul terminale viene avviata. Tutti i dettagli della transazione,
come l’importo ecc., vengono ripresi dall’oggetto transazione creato in precedenza con il Transaction Service tramite la consueta API REST.
Quando il WebSocket si interrompe a causa di un problema di rete (ad esempio in una rete mobile questo può accadere spesso), l’elaborazione del pagamento non si ferma. Il WebSocket
può essere riaperto e il Connect può essere inviato di nuovo. Il sistema tenta di riprendere la transazione. Se il timeout è stato raggiunto, la transazione fallisce e
di conseguenza il messaggio error viene inviato dal server. In questo caso deve essere avviata una nuova transazione.
I messaggi da visualizzare sulla cassa vengono trasmessi come semplici oggetti JavaScript e possono contenere i seguenti elementi.
La notifica contiene informazioni da visualizzare all’operatore sulla cassa.
{
information: {
elements: [ ... ],
recipient: "CUSTOMER" or "MERCHANT"
}
}La domanda contiene informazioni da visualizzare all’operatore sulla cassa e opzioni tra cui deve scegliere.
{
information: {
elements: [ ... ],
recipient: "CUSTOMER" or "MERCHANT"
},
options: [
{
identifier: "option-1",
text: "First option",
primary: true
},
{
identifier: "option-2",
text: "Second option",
primary: false
}
]
}Gli errori relativi alle richieste WebSocket contengono le seguenti informazioni.
{
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"
}Paragrafo
Il paragrafo rappresenta un blocco di testo.
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"
}Lista ordinata
La lista ordinata rappresenta un elenco numerato di voci:
First
Second
Third
{
items: [
{ text: "First" },
{ text: "Second" },
{ text: "Third" }
],
type: "ORDERED_LIST"
}Lista non ordinata
La lista non ordinata rappresenta un elenco di voci con punti elenco.
First
Second
Third
{
items: [
{ text: "First" },
{ text: "Second" },
{ text: "Third" }
],
type: "UNORDERED_LIST"
}Lista descrittiva
La lista ordinata rappresenta un elenco di voci con descrizione.
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"
}Tabella
| 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"
}Per collegare la vostra cassa tramite un WebSocket utilizzando JavaScript, consigliamo di utilizzare la nostra utility JavaScript TerminalTillConnection.
Includete il file JavaScript dell’utility.
<script src="https://sandbox.app-wallee.com/assets/payment/terminal-till-connection.js" type="text/javascript"></script>Create una nuova istanza di TerminalTillConnection passando come opzioni l’URL del WebSocket e le credenziali di connessione.
var tillConnection = new TerminalTillConnection({
url: "wss://sandbox.app-wallee.com/terminal-websocket",
token: "[connection-credentials]"
});Sottoscrivete gli eventi per gestire i messaggi provenienti dal terminale.
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.
});Stabilite la connessione.
tillConnection.connect();Utilizzate il metodo cancel per annullare il pagamento.
tillConnection.cancel();