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.
Dans un premier temps, vous devez créer une transaction. Pour cela, vous pouvez utiliser le Transaction Service et
l’opération créer.
Ensuite, vous pouvez utiliser l’opération effectuer la transaction pour
déclencher une transaction sur le terminal. L’opération perform transaction ne répond pas à la requête HTTP pendant environ
80 secondes au maximum. Pendant ce temps, le terminal essaie d’effectuer la transaction. Lorsque la transaction réussit ou échoue,
l’opération perform transaction renvoie immédiatement le résultat. Si le terminal a besoin de plus de temps, la méthode répond
avec le statut HTTP 543. Dans ce cas, la méthode doit être invoquée à nouveau avec les mêmes paramètres.
Le pseudo-code suivant montre comment implémenter ce modèle :
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);
}
}
}Il existe deux opérations perform transaction différentes sur le Payment Terminal Till Service :
Vous pouvez effectuer la transaction avec l’ID du terminal ou
Vous pouvez effectuer la transaction avec l’identifiant du terminal.
L’identifiant du terminal est l’ID que vous voyez aussi sur le reçu, etc. Le modèle est 3xxx xxxx. L’identifiant du terminal, quant à lui, est un numéro plus court visible uniquement dans le portail.
Comme il y a des interactions entre le caissier et le terminal pendant le processus de paiement, il faut utiliser une technique qui le permette. Concrètement, l’interaction nécessite une communication bidirectionnelle. Les WebSockets permettent ce type de communication.
Au sein du WebSocket, le protocole STOMP est utilisé pour échanger des messages. Voir https://stomp.github.io/stomp-specification-1.2.html
La connexion ouvre le canal et, par conséquent, le traitement de la transaction démarre sur le terminal. Tous les détails de la transaction,
comme le montant, etc., sont repris de l’objet transaction créé précédemment avec le Transaction Service via l’API REST habituelle.
Lorsque le WebSocket se rompt à cause d’un problème de réseau (cela peut arriver souvent sur un réseau mobile, par exemple), le traitement du paiement ne s’arrête pas. Le WebSocket
peut être rouvert et le Connect peut être renvoyé. Le système essaie de reprendre la transaction. Si le délai d’attente a été atteint, la transaction échoue et
le message error est envoyé en conséquence par le serveur. Dans ce cas, une nouvelle transaction doit être démarrée.
Les messages à afficher sur la caisse sont transmis sous forme d’objets JavaScript simples et peuvent contenir les éléments suivants.
La notification contient des informations à afficher à l’opérateur sur la caisse.
{
information: {
elements: [ ... ],
recipient: "CUSTOMER" or "MERCHANT"
}
}La question contient des informations à afficher à l’opérateur sur la caisse ainsi que des options parmi lesquelles il doit choisir.
{
information: {
elements: [ ... ],
recipient: "CUSTOMER" or "MERCHANT"
},
options: [
{
identifier: "option-1",
text: "First option",
primary: true
},
{
identifier: "option-2",
text: "Second option",
primary: false
}
]
}Les erreurs relatives aux requêtes WebSocket contiennent les informations suivantes.
{
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"
}Paragraphe
Le paragraphe représente un bloc de texte.
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"
}Liste ordonnée
La liste ordonnée représente une liste numérotée d’éléments :
First
Second
Third
{
items: [
{ text: "First" },
{ text: "Second" },
{ text: "Third" }
],
type: "ORDERED_LIST"
}Liste non ordonnée
La liste non ordonnée représente une liste d’éléments avec des puces.
First
Second
Third
{
items: [
{ text: "First" },
{ text: "Second" },
{ text: "Third" }
],
type: "UNORDERED_LIST"
}Liste descriptive
La liste ordonnée représente une liste d’éléments avec 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"
}Tableau
| 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"
}Pour connecter votre caisse via un WebSocket en utilisant JavaScript, nous recommandons d’utiliser notre utilitaire JavaScript TerminalTillConnection.
Incluez le fichier JavaScript de l’utilitaire.
<script src="https://sandbox.app-wallee.com/assets/payment/terminal-till-connection.js" type="text/javascript"></script>Créez une nouvelle instance de TerminalTillConnection en passant l’URL du WebSocket et les identifiants de connexion comme options.
var tillConnection = new TerminalTillConnection({
url: "wss://sandbox.app-wallee.com/terminal-websocket",
token: "[connection-credentials]"
});Abonnez-vous aux événements pour traiter les messages provenant du 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.
});Établissez la connexion.
tillConnection.connect();Utilisez la méthode cancel pour annuler le paiement.
tillConnection.cancel();