Ce contenu a été traduit par une intelligence artificielle. Si vous repérez une erreur, merci de nous le signaler pour nous aider à améliorer notre support. En cas de doute, la version originale en anglais fait foi.
Pour permettre l'intégration entre votre logiciel de caisse (POS) et le terminal (POI), nous supportons quatre couches de transport de données différentes. Elles sont conçues pour couvrir un large éventail d'architectures techniques, de besoins de sécurité et d'environnements de déploiement. Chaque protocole offre des capacités distinctes en termes de performance, de modèles de connectivité et de complexité d'implémentation, permettant aux fournisseurs de POS de choisir la méthode la plus adaptée à leur écosystème.
HTTP — Un protocole requête/réponse simple et léger, idéal pour les intégrations locales où le chiffrement n'est pas requis.
HTTPS — Une version sécurisée de HTTP utilisant TLS, recommandée pour tous les environnements où la confidentialité, l'intégrité et l'authentification sont essentielles.
TCP/IP — Un canal basé sur des sockets persistants et bidirectionnels permettant une messagerie en temps réel, une faible latence et des connexions continues.
IPC (Android App-to-App) — Un mécanisme de communication inter-processus haute performance permettant aux applications POS Android d'interagir directement avec l'application de paiement s'exécutant sur le terminal.
1. Protocole HTTP
Gestion synchrone et asynchrone
L'API locale Market Pay utilise un modèle de communication mixte basé sur les exigences du point de terminaison (endpoint) :
Mode Synchrone (SYNC) : Utilisé pour des actions simples et directes où le POS attend un résultat immédiat. Cela suit un cycle standard de requête/réponse unique (ex:
POST /statusrenvoieRC 200 OKavec le corps de la réponse).Mode Asynchrone (ASYNC) : Utilisé pour les transactions complexes nécessitant une interaction de l'utilisateur ou un temps de traitement. Cela implique le cycle de Polling HTTP détaillé ci-dessous.
Gestion de l'asynchronisme
L'application POS gère le cycle de scrutation (polling) en fonction des codes de réponse et des types de messages. Le mécanisme asynchrone est utilisé pour toutes les opérations POST en ASYNC : /payment, /acquisition, /reversal, /balanceinquiry, /giftcard et /update.
Mécanisme de la boucle de Polling
La boucle de Polling est le mécanisme utilisé pour les transactions asynchrones, où le POS surveille activement le terminal de paiement (POI) pour obtenir un résultat final après avoir initié une requête. Cette boucle remplace une connexion persistante et est critique pour la gestion de l'état de la transaction.
Initialisation : Le POS envoie une requête POST (ex:
/payment) et reçoit unRC 202 Accepted, signalant que la transaction est en file d'attente et que la boucle doit commencer.Continuation : Le POS envoie des requêtes GET répétées (polling). La boucle continue tant que le POI renvoie un statut intermédiaire (
RC 206 Partial Content,RC 201 Created, ouRC 204 No Content).Terminaison (Succès/Échec) : La boucle s'arrête immédiatement (break) lorsque le POI renvoie un code de statut final (
RC 200 OKpour le résultat ouRC 423 Locked / RC 403 Forbiddenpour une erreur fatale).Exception : Une erreur interne irrécupérable est transmise via une réponse
RC 200 OKcontenant uneEventNotification, ce qui oblige également le POS à arrêter immédiatement le polling.
Codes de statut de transaction
Ce tableau définit la signification et les actions requises pour chaque code de réponse HTTP rencontré.
| RC | Statut & Type | Contenu livré | Résultat du flux / Action POS requise |
|---|---|---|---|
| 200 | OK (Final) | Corps complet (PaymentResponse) ou Échec (EventNotification). | Transaction finalisée. Le résultat final a été reçu. Le POS doit ARRÊTER le polling. |
| 202 | Accepted (Début) | Aucun (Corps vide) | Transaction démarrée. La requête est acceptée. Le POS doit immédiatement COMMENCER le polling (boucle GET). |
| 423 | Locked (Erreur fatale) | Aucun (Corps vide) | Terminal bloqué. Le terminal est occupé ou verrouillé. Le POS doit ARRÊTER et traiter comme un échec. |
| 403 | Forbidden (Erreur critique) | Aucun (Corps vide) | Rejeté. Requête non autorisée. Le POS doit ARRÊTER la transaction immédiatement. |
2. HTTPS
Le HTTPS est du HTTP superposé à un chiffrement SSL/TLS. C'est la norme requise pour toute communication via l'internet public. Ici, la communication se fait entre le POS et une passerelle de paiement centrale (Cloud API), et non directement entre le POS et le terminal.
Fonctionnement :
Requête : Le POS envoie une requête HTTPS synchrone à la Cloud API.
Routage : La Cloud API achemine la requête de manière sécurisée vers le terminal spécifique.
Résultat (Asynchrone via Webhook) : Le terminal renvoie le résultat à la Cloud API, qui envoie ensuite un message HTTPS POST automatique (un Webhook) vers une URL prédéfinie sur le serveur du POS pour livrer le statut final.
3. Protocole TCP/IP
Présentation
Le protocole TCP/IP établit une connexion fiable et persistante (Socket) entre deux programmes sur le réseau local. Ce protocole est choisi pour les applications nécessitant une livraison de données ordonnée et un contrôle maximal de l'état de la connexion.
Fonctionnement
Connexion : Le POS (client) initie une connexion vers l'adresse IP et le port du POI (serveur). La connexion reste ouverte pendant toute la session.
Pas de Polling : Contrairement au HTTP, le POI peut "pousser" (push) les statuts intermédiaires et le résultat final directement vers le POS via la socket ouverte.
Détails d'implémentation : Encapsulation des messages (Framing)
TCP traitant les données comme un flux continu d'octets, vous devez implémenter un mécanisme de préfixe de longueur (Length-Prefix) :
Le POS doit lire un champ de longueur fixe dans l'en-tête indiquant la taille totale du message à suivre pour identifier correctement le début et la fin de chaque message JSON/XML.
4. Communication Inter-Processus (IPC)
L'IPC permet à deux applications isolées s'exécutant sur le même appareil Android de communiquer. Pour notre intégration "App-to-App", nous utilisons l'AIDL (Android Interface Definition Language).
Fonctionnement :
Liaison de service (Service Binding) : L'application POS initie une liaison vers un service exposé par l'application de paiement.
Interface AIDL : Le POS utilise des méthodes définies (ex:
makePayment) pour interagir avec le POI.Callback : L'application de paiement utilise un mécanisme de rappel (callback) pour renvoyer le résultat de la transaction au POS.