La nostra API può comunicare con il POI utilizzando messaggi JSON o XML e aderisce al Protocollo Nexo Retailer. Tutte le richieste e risposte seguono una struttura standard header-body del messaggio
1. Struttura dei messaggi API
Ogni richiesta API che invii è contenuta all'interno di un oggetto SaletoPOIRequest. In questo, devi fornire l'oggetto MessageHeader e il corretto oggetto body della richiesta corrispondente al tipo di transazione.
| Componente | Scopo | Esempi |
|---|---|---|
| Header | Identifica il tipo di transazione, il POI utilizzato e identificativi unici della transazione. |
Include |
| Body | Contiene l'oggetto principale di richiesta o risposta per il tipo di transazione. |
Un oggetto |
2. Messaggio di richiesta
MessageHeader Request
I seguenti campi sono obbligatori in ogni MessageHeader della richiesta:
| Nome | Obbligatorio | Tipo | Descrizione |
|---|---|---|---|
| ProtocolVersion | ✅ |
Stringa |
Versione del protocollo Nexo; attualmente 3.1 |
| MessageClass | ✅ |
Enum |
Il contesto della richiesta; quasi sempre |
| MessageCategory | ✅ |
Enum |
Il tipo di transazione (ad es. |
| MessageType | ✅ |
Enum |
Sempre |
| ServiceID | ✅ |
Stringa |
Il tuo ID univoco per questa richiesta (1-10 caratteri alfanumerici). |
| SaleID | ✅ |
Stringa |
Il tuo ID univoco per il sistema POS che invia la richiesta |
| POIID | ✅ |
Stringa |
L'ID del POI di destinazione |
Esempio di Header della richiesta
"SaleToPOIRequest": {
"MessageHeader": {
"ProtocolVersion": "3.1",
"MessageClass": "Service",
"MessageCategory": "Payment",
"MessageType": "Request",
"SaleID": "POSSystemID12345",
"ServiceID": "0207111104",
"POIID": "V400m-324688179"
},
"PaymentRequest": {...}
}
Consulta lo schema completo nella pagina delle specifiche API per i campi obbligatori.
Corpo della richiesta
I campi obbligatori nel corpo della richiesta variano in base all'operazione eseguita. Puoi trovare esempi specifici e informazioni di riferimento che dettagliano le esigenze per ogni operazione nella nostra documentazione online della Local API.
| Nome | Obbligatorio | Tipo | Descrizione |
|---|---|---|---|
| ProtocolVersion | ✅ |
Stringa |
Versione del protocollo Nexo; attualmente 3.1 |
| MessageClass | ✅ |
Enum |
Il contesto della richiesta; quasi sempre |
| MessageCategory | ✅ |
Enum |
Il tipo di transazione (ad es. |
| MessageType | ✅ |
Enum |
Sempre |
| ServiceID | ✅ |
Stringa |
Il tuo ID univoco per questa richiesta (1-10 caratteri alfanumerici). |
| SaleID | ✅ |
Stringa |
Il tuo ID univoco per il sistema POS che invia la richiesta |
| POIID | ✅ |
Stringa |
L'ID del POI di destinazione |
Esempio di Header e Body della richiesta
{
"MessageHeader": {
"MessageCategory": "Payment",
"MessageClass": "Service",
"MessageType": "Request",
"POIID": "Terminal_01",
"ProtocolVersion": "3.1",
"SaleID": "POS001",
"ServiceID": "86"
},
"PaymentRequest": {
"PaymentData": {
"PaymentType": "Normal"
},
"PaymentTransaction": {
"AmountsReq": {
"Currency": "EUR",
"RequestedAmount": 12.34
}
},
"SaleData": {
"SaleTransactionID": {
"TimeStamp": "2025-11-29T22:05:55.029",
"TransactionID": "12345"
}
}
}
}
Consulta lo schema completo nella pagina delle specifiche API per i campi obbligatori.
3. Messaggio di risposta
Le risposte sono contenute all'interno di un singolo oggetto (simile a SaleToPOIResponse) e includono il MessageHeader e il corrispondente oggetto body della risposta.
Header della risposta: esso riporta i valori forniti nella richiesta. L'unica eccezione è MessageType, che è sempre
Response.Body della risposta: includerà un identificativo della transazione e i dati necessari per generare le ricevute.
In un'integrazione HTTP, per i messaggi asincroni, ricevi solo una risposta
okdall'API. IlMessageHeadere il body della risposta vengono inviati in risposta a una GET.
MessageHeader Response
Il MessageHeader che ricevi nella risposta riporta i valori forniti nella richiesta. L'unica eccezione è MessageType, che è Response.
L'esempio seguente mostra l'header che riceveresti in risposta all'esempio di richiesta di pagamento fornito sopra.
Esempio di Header e Body della richiesta
"MessageHeader": {
"MessageCategory": "Payment",
"MessageClass": "Service",
"MessageType": "Response",
"POIID": "Terminal_01",
"ProtocolVersion": "3.1",
"SaleID": "POS001",
"ServiceID": "102"
},
Consulta lo schema completo nella pagina delle specifiche API per i campi obbligatori.
Body della risposta
I valori che ricevi nel body della risposta dipendono dal tipo di richiesta di transazione effettuata. Forniamo esempi e informazioni di riferimento per ogni tipo di transazione nella nostra documentazione per il punto vendita.
Il body della risposta includerà spesso un identificativo della transazione e dati che puoi utilizzare per generare le tue ricevute.
Esempio di una risposta:
Esempio di Header e Body della richiesta
{
"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"
},
"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"
},
"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
}
],
}
}
}
Consulta lo schema completo nella pagina delle specifiche API per i campi obbligatori.
Identificativo della transazione
In ogni risposta, il POI restituisce un identificativo della transazione: POIData.POITransactionID.TransactionID. Devi memorizzare ogni TransactionID poiché è un dato chiave per eseguire alcune operazioni aggiuntive come:
- Annullare una transazione (Cancel),
- Verifica dello stato della transazione,
- Pagamento tramite acquisizione carta,
- Preautorizzazione
Dati della ricevuta
Nelle risposte alle transazioni, il risultato può contenere un oggetto PaymentReceipt. Puoi aggiungere le coppie chiave-valore di questo oggetto alla ricevuta che stampi, visualizzi o invii via email al tuo cliente.
Nell'oggetto PaymentReceipt è presente RequiredSignatureFlag che indica che la ricevuta di pagamento del titolare della carta richiede una firma fisica da parte del Cliente.
4. Identificare il POI
La Diagnosi consente all'applicazione Point of Sale (POS) di recuperare il Numero di Serie univoco dell'hardware. L'interesse principale nell'utilizzo della validazione del Numero di Serie è la prevenzione delle frodi e l'integrità del sistema.
Il POS può eseguire un rapido controllo durante il login per recuperare il numero di serie univoco del POI. Confrontando questo numero con un record archiviato, il tuo sistema può rilevare immediatamente se un terminale non autorizzato o sconosciuto è stato sostituito nell'impianto. Ciò crea un collegamento semplice, sicuro e verificabile tra il software POS e il dispositivo POI fisico.
Di seguito trovi una semplice proposta di implementazione:
Prima installazione: recupera e memorizza il Numero di Serie del POI tramite una richiesta Diagnosi . La prima installazione dovrebbe essere considerata sicura secondo il processo di installazione.
Login successivi: il POS esegue una nuova richiesta Diagnosi. Se il Numero di Serie restituito non corrisponde al valore memorizzato, il POS deve avvisare l'utente per confermare se il POI è stato legittimamente cambiato oppure no.
Puoi anche confrontare il Numero di Serie con quello noto presente nel tuo Database. Questo può essere facilitato per i clienti conformi P2PE che devono seguire l'intero ciclo di vita dei terminali di pagamento.