Data Transport Layer

Per abilitare l'integrazione tra il tuo POS e il POI, supportiamo quattro diversi Data Transport Layer, progettati per coprire un'ampia gamma di architetture tecniche, esigenze di sicurezza e ambienti di distribuzione. Ogni protocollo offre diverse capacità in termini di prestazioni, modelli di connettività e complessità di implementazione, consentendo ai fornitori di POS di scegliere il metodo che meglio si adatta al loro ecosistema.

• HTTP — Un protocollo di richiesta/risposta semplice e leggero, ideale per integrazioni locali dove non è richiesta la crittografia.

• HTTPS — Una versione sicura di HTTP che utilizza TLS, raccomandata per tutti gli ambienti in cui riservatezza, integrità e autenticazione sono essenziali.

• TCP/IP — Un canale persistente, bidirezionale, basato su socket che consente la messaggistica in tempo reale, bassa latenza e connessioni continue.

• IPC (Android App-to-App) — Un meccanismo di comunicazione inter-processo ad alte prestazioni che consente alle applicazioni POS Android di interagire direttamente con l'applicazione di pagamento in esecuzione sul terminale.

Questi protocolli forniscono opzioni flessibili per integrare le funzionalità di pagamento, sia che il POS e il POI comunichino tramite una rete locale, canali sicuri o all'interno dello stesso dispositivo Android.

1. Protocollo HTTP

Gestione Sincrona e Asincrona

La Market Pay Local API utilizza un modello di comunicazione misto basato sui requisiti dell'endpoint:

• Modalità Sincrona (SYNC): Utilizzata per azioni semplici e dirette in cui il POS attende un risultato immediato. Segue un ciclo standard di richiesta/risposta singola (es., POST /status restituisce RC 200 OK con il corpo della risposta).

• Modalità Asincrona (ASYNC): Utilizzata per transazioni complesse che richiedono l'interazione dell'utente o tempi di elaborazione. Questo comporta il ciclo di HTTP Polling dettagliato di seguito.

Gestione Asincrona

L'applicazione POS gestisce il ciclo di polling in base ai codici di risposta e ai tipi di messaggio.

Il meccanismo asincrono viene utilizzato per tutte le operazioni POST in ASYNC: /payment, /acquisition, /reversal, /balanceinquiry, e /giftcard e /update.

Meccanismo di polling loop

Il Polling Loop è il meccanismo utilizzato per le transazioni Asincrone (ASYNC), dove il Punto Vendita (POS) monitora attivamente il Terminale di Pagamento (POI) per un risultato finale dopo aver avviato una richiesta. Questo loop sostituisce una connessione persistente ed è fondamentale per la gestione dello stato della transazione e la stabilità della comunicazione.

• Inizio: Il POS invia una richiesta POST (es., /payment) e riceve RC 202 Accepted, segnalando che la transazione è in coda e il loop deve iniziare.

• Continuazione: Il POS invia ripetute richieste GET (polling). Il loop continua finché il POI restituisce uno stato intermedio (RC 206 Partial Content, RC 201 Created, o RC 204 No Content).

• Terminazione (Successo/Fallimento): Il loop si interrompe immediatamente (break) quando il POI restituisce un codice di stato finale (RC 200 OK per il risultato o RC 423 Locked/RC 403 Forbidden per un errore fatale).

• Eccezione: Un errore interno non recuperabile (come un rifiuto di parsing) viene fornito tramite una risposta RC 200 OK contenente un EventNotification, che richiede anche al POS di interrompere immediatamente il polling.

Diagramma di sequenza del polling loop

Questo diagramma di sequenza si concentra esclusivamente sul ciclo di comunicazione continua avviato dopo la risposta iniziale RC 202 Accepted. Il ciclo continua fino a quando un risultato finale della transazione o un errore forza una terminazione (break).

Codici di stato della transazione

Riferimento al flusso

Questa tabella definisce il significato e le azioni richieste per ogni codice di risposta HTTP riscontrato durante una transazione sincrona o il polling loop asincrono.

Esempio di risposta:

{
  "MessageHeader": {
    "MessageCategory": "Payment",
    "MessageClass": "Service",
    "MessageType": "Response",
    "POIID": "Terminal_01",
    "ProtocolVersion": "3.1",
    "SaleID": "POS001",
    "ServiceID": "102"
  },
  "PaymentResponse": {
    "MarketpayPaymentExtensions": {
      "ApplicationID": "A0000000041010",
      "BankID": "519303",
      "PANSequenceNumber": "00",
      "TVR": "0000040001"
    },
    "PaymentReceipt": [
      {
        "DocumentQualifier": "CashierReceipt",
        "OutputContent": {
          "OutputFormat": "Text",
          "OutputText": [
            {
              "EndOfLineFlag": true,
              "Text": "POTWIERDZENIE DLA"
            },
            {
              "EndOfLineFlag": true,
              "Text": "SPRZEDAWCY"
            },
            {
              "EndOfLineFlag": true,
              "Text": "BRAK PARAGONU DO"
            },
            {
              "EndOfLineFlag": true,
              "Text": "ZAKUPU"
            },
            {
              "EndOfLineFlag": true,
              "Text": "MARKET PAY PRECERT"
            },
            {
              "EndOfLineFlag": true,
              "Text": "120 RUE REAUMUR"
            },
            {
              "EndOfLineFlag": true,
              "Text": "75002 PARIS"
            },
            {
              "EndOfLineFlag": true,
              "Text": "Mastercard"
            },
            {
              "EndOfLineFlag": true,
              "Text": "BEZSTYKOWY"
            },
            {
              "EndOfLineFlag": true,
              "Text": "XXXXXXXXXXXX1676 00"
            },
            {
              "EndOfLineFlag": true,
              "Text": "AID: A0000000041010"
            },
            {
              "EndOfLineFlag": true,
              "Text": "TVR: 0000040001"
            },
            {
              "EndOfLineFlag": true,
              "Text": "29-11-2025 22:17"
            },
            {
              "EndOfLineFlag": true,
              "Text": "NUMER REFERENCYJNY: 13"
            },
            {
              "EndOfLineFlag": true,
              "Text": "KWOTA:EUR 123,00"
            },
            {
              "EndOfLineFlag": true,
              "Text": "Zaakceptowana"
            }
          ]
        },
        "RequiredSignatureFlag": false
      },
      {
        "DocumentQualifier": "CustomerReceipt",
        "OutputContent": {
          "OutputFormat": "Text",
          "OutputText": [
            {
              "EndOfLineFlag": true,
              "Text": "RECU PORTEUR"
            },
            {
              "EndOfLineFlag": true,
              "Text": "PAS DE REÇU POUR"
            },
            {
              "EndOfLineFlag": true,
              "Text": "L'ACHAT"
            },
            {
              "EndOfLineFlag": true,
              "Text": "MARKET PAY PRECERT"
            },
            {
              "EndOfLineFlag": true,
              "Text": "120 RUE REAUMUR"
            },
            {
              "EndOfLineFlag": true,
              "Text": "75002 PARIS"
            },
            {
              "EndOfLineFlag": true,
              "Text": "Mastercard"
            },
            {
              "EndOfLineFlag": true,
              "Text": "SANS CONTACT"
            },
            {
              "EndOfLineFlag": true,
              "Text": "XXXXXXXXXXXX1676 00"
            },
            {
              "EndOfLineFlag": true,
              "Text": "AID: A0000000041010"
            },
            {
              "EndOfLineFlag": true,
              "Text": "29-11-2025 22:17"
            },
            {
              "EndOfLineFlag": true,
              "Text": "NUMÉRO DE RÉFÉRENCE: 13"
            },
            {
              "EndOfLineFlag": true,
              "Text": "MONTANT:EUR 123,00"
            },
            {
              "EndOfLineFlag": true,
              "Text": "Approuvé"
            }
          ]
        },
        "RequiredSignatureFlag": false
      }
    ],
    "PaymentResult": {
      "AmountsResp": {
        "AuthorizedAmount": "123",
        "Currency": "EUR"
      },
      "MerchantOverrideFlag": false,
      "OnlineFlag": true,
      "PaymentAcquirerData": {
        "AcquirerID": "40105611508",
        "AcquirerPOIID": "00000001",
        "ApprovalCode": "511725",
        "MerchantID": "198703093982001"
      },
      "PaymentInstrumentData": {
        "CardData": {
          "EntryMode": "Contactless",
          "MaskedPAN": "XXXXXXXXXXXX1676",
          "PaymentBrand": "MASTERCARD"
        },
        "PaymentInstrumentType": "Card"
      },
      "PaymentType": "Normal"
    },
    "POIData": {
      "POITransactionID": {
        "TimeStamp": "2025-11-29T22:17:23.359",
        "TransactionID": "13"
      }
    },
    "Response": {
      "AdditionalResponse": "000",
      "Result": "Success"
    },
    "SaleData": {
      "OperatorID": "App2AppOperator",
      "SaleTransactionID": {
        "TimeStamp": "2025-11-29T22:16:58.354",
        "TransactionID": "12345"
      },
      "SponsoredMerchant": {
        "Address": "120 RUE REAUMUR\n75002 PARIS",
        "CommonName": "MARKET PAY PRECERT",
        "CountryCode": "FR",
        "MerchantCategoryCode": "4411",
        "RegisteredIdentifier": "198703093982001"
      }
    }
  }
}

Esempio di EventNotification:

Il messaggio contiene i metadati principali della transazione in MessageHeader e le istruzioni di visualizzazione nel corpo EventNotification: TimeStamp e EventToNotify

{
  "MessageHeader": {
    "MessageCategory": "EventNotification",
    "MessageClass": "Service",
    "MessageType": "Response",
    "POIID": "POI_123",
    "ProtocolVersion": "3.1",
    "SaleID": "POS001",
    "ServiceID": "823"
  },
  "EventNotification": {
    "TimeStamp": "2025-04-02T15:48:47.596+02:00",
    "EventToNotify": "Reject"
  }
}

Codici intermedi di polling ASYNC

Questi codici vengono restituiti esclusivamente a una richiesta di polling GET e richiedono all'applicazione POS di continuare il ciclo di monitoraggio fino al raggiungimento di uno stato finale (RC 200/423).

In ASYNC, il POS riceverà Display Request inviate dal POI tramite il ciclo di polling. La sua funzione principale è istruire il POS su quali informazioni visualizzare o quale stato operativo è stato raggiunto durante una transazione.

Struttura del Display Request

Il messaggio contiene i metadati principali della transazione in MessageHeader e le istruzioni di visualizzazione nel corpo DisplayRequest.DisplayOutput:

Esempio di DisplayRequest:

{
    "MessageHeader":{
        "MessageCategory":"Display",
        "MessageClass":"Service",
        "MessageType":"Request",
        "POIID":"PayOnSite",
        "ProtocolVersion":"3.1",
        "SaleID":"POS_01",
        "ServiceID":"102"
    }
    "DisplayRequest":{
        "DisplayOutput":[
            {
                "Device":"CashierDisplay",
                "InfoQualify":"Status",
                "OutputContent":{
                    "OutputFormat":"Text",
                    "OutputText":[
                        {
                            "Text":"WaitingForCard"
                        }
                    ]
                },
                "ResponseRequiredFlag":false
            }
        ]
    },
}

Regole Tecniche e Funzionali

2. HTTPS

HTTPS (Hypertext Transfer Protocol Secure) è HTTP sovrapposto alla crittografia SSL/TLS. Questo è lo standard richiesto per tutte le comunicazioni su Internet pubblica, garantendo integrità e riservatezza dei dati. La comunicazione avviene tra POS/terminale e un gateway centrale di pagamento (la Cloud API), non direttamente tra POS e terminale. 

Troverai informazioni aggiuntive sulla nostra pagina Cloud API e sulla nostra documentazione online. La nostra Cloud API non segue ancora la struttura Nexo Retailer.

Come funziona?

1. Richiesta: Il POS invia una richiesta HTTPS sincrona alla Cloud API (il gateway).

2. Instradamento: La Cloud API instrada in modo sicuro la richiesta al terminale specifico.

3. Risultato (Asincrono via Webhook): Il POS spesso non attende il risultato finale. Invece, la Cloud API invia immediatamente una risposta iniziale che conferma la ricezione della richiesta. Quando la transazione si conclude sul terminale, la Cloud API invia un messaggio HTTPS POST automatico (un Webhook) a un URL predefinito sul server POS per consegnare lo stato finale.

Dettagli di implementazione

• Sicurezza: Richiede certificati SSL/TLS validi e la validazione obbligatoria della firma per i webhook in ingresso.

• Webhooks (opzionali): Il server POS deve esporre un endpoint HTTPS pubblico e dedicato per ricevere le notifiche webhook. Deve gestire l'acknowledgment (HTTP 200 OK) prontamente.

• Gestione degli errori: Il POS deve gestire i webhook duplicati e gestire separatamente lo stato della transazione (lo stato è definito dal webhook, non dalla richiesta iniziale).

• Addressing: Il terminale necessita solo di connettività Internet generale; il suo indirizzo IP è solitamente dinamico e irrilevante per la richiesta POS.

3. Protocollo TCP/IP

Cos'è

Il protocollo TCP/IP fornisce una base di comunicazione a basso livello stabilendo una connessione affidabile e persistente (Socket) tra due programmi che operano sulla rete locale. Questo protocollo è tipicamente scelto per applicazioni che richiedono consegna dati garantita, ordinata e massimo controllo sullo stato della connessione. 

Come funziona

1. Connessione: L'applicazione POS (client) avvia una connessione al POI (server) utilizzando l'indirizzo IP e il numero di porta del POI. Questa connessione rimane aperta e attiva per tutta la sessione di transazione. 
2. Flusso dati: Tutti i messaggi Nexo JSON o XML vengono inviati come flusso continuo di dati attraverso questo socket. 
3. Nessun Polling: A differenza di HTTP, il POS non deve inviare richieste GET ripetute; il POI può inviare direttamente al POS tramite il socket aperto sia gli stati intermedi sia il risultato finale.

Dettagli di implementazione:

Message Framing

Poiché TCP tratta i dati come un flusso di byte continuo (senza delimitatori di messaggio predefiniti), lo sviluppatore deve implementare un meccanismo di framing per analizzare correttamente i singoli messaggi Nexo:  

• Requisito: Il POS deve leggere il flusso per identificare correttamente l'inizio e la fine di ogni messaggio JSON/XML. Se il POS invia due messaggi JSON immediatamente, il POI li riceve come un unico lungo flusso (es., {"Msg1":...}{"Msg2":...}).
• Meccanismo: Questo viene ottenuto utilizzando un Length-Prefix (4 byte) nell'header del messaggio, con un campo di lunghezza fissa che indica la dimensione totale in byte del corpo del messaggio seguente. Il POS legge il campo di lunghezza, poi esattamente quel numero di byte per il messaggio completo. 

Gestione della connessione e dello stato:

Il POS è responsabile del mantenimento della stabilità e persistenza della connessione socket:

• Persistenza della connessione: La connessione socket dovrebbe essere mantenuta aperta e attiva per tutta la sessione di transazione per consentire al POI di inviare notifiche e il risultato finale direttamente al POS (nessun polling richiesto).

• Keep-Alive: Implementare un meccanismo keep-alive (es., invio regolare di messaggi ping non transazionali) per evitare che dispositivi di rete (come firewall o load balancer) chiudano la connessione socket inattiva.

• Riconnessione: L'applicazione POS deve includere una logica robusta per rilevare automaticamente una connessione interrotta e tentare di ristabilire il socket rapidamente per evitare interruzioni della transazione.

Gestione degli errori

Gli sviluppatori devono distinguere tra un fallimento di transazione e un fallimento di comunicazione:

• Errore di comunicazione: Se il POS perde la connessione socket prima di ricevere una risposta finale, il POS non deve automaticamente assumere che la transazione sia fallita. Deve tentare di riconnettersi e inviare una richiesta /diagnosis per determinare l'esito.

• Errore di transazione: Se il POI risponde con una risposta Nexo che indica un errore di business, la connessione socket rimane attiva, ma il POS deve finalizzare il flusso della transazione.

Configurazione

• Addressing: Richiede che il POS utilizzi un indirizzo IP statico o una prenotazione DHCP per il POI per garantire un endpoint di connessione noto.
• Gestione degli errori: Il POS deve implementare una logica per rilevare connessioni interrotte, gestire i keep-alive del socket e tentare la riconnessione in modo corretto.

4. Inter-Process Communication (IPC)

IPC (Inter-Process Communication) è un insieme di meccanismi che consente a due o più applicazioni o processi isolati in esecuzione sullo stesso dispositivo Android di comunicare. Per la nostra applicazione App-to-App, il meccanismo utilizzato è AIDL (Android Interface Definition Language), che permette all' applicazione POS di chiamare in modo sicuro metodi direttamente su un servizio in esecuzione all'interno dell' Applicazione di Pagamento (POI).

Troverai maggiori dettagli nella pagina dedicata: Integrazione App-to-App. La nostra integrazione App-to-App non segue ancora il protocollo nexo retailer.

Come funziona

Invece di avviare semplicemente l'App di Pagamento tramite un Intent e attendere un risultato, questo processo stabilisce una connessione diretta e sicura:

1. Service Binding: L'App POS (client) avvia esplicitamente un bind a un servizio esposto dall'App di Pagamento (server). Questa connessione viene stabilita utilizzando il framework del sistema operativo Android.

2. Interfaccia AIDL: Le due app condividono le stesse definizioni di interfaccia AIDL. L'App POS utilizza le classi stub generate per invocare i metodi definiti nell'interfaccia (es., makePayment(amount, reference)).

3. Chiamata Sincrona/Asincrona: L'App di Pagamento elabora la richiesta (es., attiva il lettore di carte) e utilizza un meccanismo di Callback definito nell'interfaccia AIDL per restituire l'esito della transazione (successo o fallimento) all'App POS.

Dettagli di implementazione

• Dipendenza: Richiede l'integrazione di un SDK/Libreria fornita dal vendor (es., un file AAR) e dei relativi file di interfaccia AIDL nel tuo progetto POS Android.

• Sicurezza: La comunicazione è protetta localmente dal sistema operativo Android e spesso validata dalla verifica del certificato di firma del chiamante (nelle integrazioni professionali) per garantire che solo app autorizzate possano comunicare.

• Addressing: Non è richiesta alcuna configurazione di rete (IP/Porta), in quanto la comunicazione è gestita dal kernel del dispositivo locale.