Implémentation du protocol

Notre API peut communiquer avec le terminal (POI) à l'aide de messages JSON ou XML et respecte le protocole Nexo Retailer. Toutes les requêtes et réponses suivent une structure standard de type en-tête-corps (header-body).

1. Structure des messages de l'API

Chaque requête API que vous envoyez est contenue dans un objet SaletoPOIRequest. Dans cet objet, vous devez fournir l'objet MessageHeader et l'objet corps de requête (Request body) correspondant au type de transaction.

Composant	Usage	Exemples
Header (En-tête)	Identifie le type de transaction, le POI utilisé et les identifiants uniques de transaction.	Inclut `ProtocolVersion`, `ServiceID`, `POIID` et `MessageCategory`.
Body (Corps)	Contient l'objet principal de la requête ou de la réponse pour le type de transaction.	Un objet `PaymentRequest` lors d'un paiement, ou un objet `PaymentResponse` lors de la réception d'un résultat.

2. Message de requête (Request)

Requête MessageHeader

Les champs suivants sont obligatoires dans le MessageHeader de chaque requête :

Nom	Requis	Type	Description
ProtocolVersion	✅	String	Version du protocole Nexo ; actuellement 3.1.
MessageClass	✅	Enum	Le contexte de la requête ; presque toujours `Service`, mais peut aussi être `Device` ou `Event`.
MessageCategory	✅	Enum	Le type de transaction (ex: `Payment` ou `Input`) ; spécifié dans la documentation de chaque flux.
MessageType	✅	Enum	Toujours `Request`.
ServiceID	✅	String	Votre identifiant unique pour cette requête (1-10 caractères alphanumériques).
SaleID	✅	String	Votre identifiant unique pour le système de caisse (POS) envoyant la requête.
POIID	✅	String	L'identifiant du POI cible.

Exemple d'en-tête de requête (Header) :

Request Header example

"SaleToPOIRequest": {
    "MessageHeader": {
        "ProtocolVersion": "3.1",
        "MessageClass": "Service",
        "MessageCategory": "Payment",
        "MessageType": "Request",
        "SaleID": "POSSystemID12345",
        "ServiceID": "0207111104",
        "POIID": "V400m-324688179"
    },
    "PaymentRequest": {...}
}

Review the full schema on the API specification page for required fields.

Corps de la requête (Request body)

Les champs requis dans le corps de la requête varient selon l'opération effectuée. Vous trouverez des exemples spécifiques et des informations de référence détaillant les besoins de chaque opération dans notre documentation "Local API" en ligne.

{
  "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"
      }
    }
  }
}

Review the full schema on the API specification page for required fields.

3. Message de réponse (Response)

Les réponses sont contenues dans un objet unique (similaire à SaleToPOIResponse) et incluent le MessageHeader ainsi que l'objet corps de réponse correspondant.

En-tête de réponse (Response header) : Il reprend les valeurs que vous avez fournies dans la requête. La seule exception est le MessageType, qui est toujours Response.
Corps de réponse (Response body) : Il inclut un identifiant de transaction et les données nécessaires pour générer les reçus.

Dans une intégration HTTP, pour les messages asynchrones, vous recevez uniquement une réponse ok de l'API. Le MessageHeader et le corps de la réponse sont envoyés en réponse à une requête GET.

Réponse MessageHeader

L'exemple suivant montre l'en-tête que vous recevriez en réponse à l'exemple de requête de paiement fourni ci-dessus :

Request Header & Body example

  "MessageHeader": {
    "MessageCategory": "Payment",
    "MessageClass": "Service",
    "MessageType": "Response",
    "POIID": "Terminal_01",
    "ProtocolVersion": "3.1",
    "SaleID": "POS001",
    "ServiceID": "102"
  },

Review the full schema on the API specification page for required fields.

Corps de la réponse (Response body)

Le corps de la réponse inclut souvent un identifiant de transaction et des données utilisables pour générer vos reçus.

Request Header & Body example

{
  "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
      }
    ],
    }
  }
}

Review the full schema on the API specification page for required fields.

Identifiant de transaction

Dans chaque réponse, le POI renvoie un identifiant de transaction : POIData.POITransactionID.TransactionID. Vous devez stocker chaque TransactionID car il s'agit d'une donnée clé pour effectuer des opérations supplémentaires telles que :

Annuler une transaction (Void / Cancel),
Vérifier le statut d'une transaction,
Paiement avec acquisition de carte,
Pré-autorisation.

Données du reçu (Receipt data)

L'objet PaymentReceipt contient les informations à imprimer ou afficher. Le champ RequiredSignatureFlag indique si le reçu nécessite une signature physique du client.

Dans l'objet PaymentReceipt, le champ RequiredSignatureFlag indique si le reçu de paiement du client nécessite une signature physique.

Identifier le POI

Le Diagnostic permet à l'application du système de caisse (POS) de récupérer le numéro de série unique du matériel. L'intérêt principal de la validation par numéro de série réside dans la prévention de la fraude et la garantie de l'intégrité du système.

Le POS peut effectuer une vérification rapide lors de l'authentification pour récupérer le numéro de série unique du terminal (POI). En comparant ce numéro à un enregistrement stocké, votre système peut immédiatement détecter si un terminal non autorisé ou inconnu a été substitué dans l'installation. Cela crée un couplage simple, sécurisé et vérifiable entre le logiciel de caisse et l'appareil physique.

Proposition de mise en œuvre :

Première installation : Récupérez et stockez le numéro de série du POI via une requête de Diagnostic. Cette première installation est considérée comme "de confiance" selon votre processus de déploiement.
Connexions suivantes : Le POS exécute une nouvelle requête de Diagnostic. Si le numéro de série renvoyé ne correspond pas à la valeur stockée, le POS doit alerter l'utilisateur pour confirmer si le terminal a été légitimement remplacé ou non.

Note : Vous pouvez également comparer le numéro de série avec celui répertorié dans votre base de données centrale. Cette démarche est facilitée pour les clients conformes à la norme P2PE, qui sont tenus de suivre l'intégralité du cycle de vie de leurs terminaux de paiement.