Protocolimplementatie

Onze API kan communiceren met de POI via JSON- of XML-berichten en voldoet aan het Nexo Retailer Protocol. Alle verzoeken en antwoorden volgen een standaard bericht header-body structuur

1. API-berichtstructuur

Elk API-verzoek dat u verstuurt, is vervat in een SaletoPOIRequest object. Hierin moet u het MessageHeader object en het juiste Request body object voorzien dat overeenkomt met het transactietype.

Component	Doel	Voorbeelden
Header	Identificeert het transactietype, de gebruikte POI en unieke transactie-identificaties.	Bevat `ProtocolVersion`, `ServiceID`, `POIID` en `MessageCategory`.
Body	Bevat het kernverzoek of responsobject voor het transactietype.	Een `PaymentRequest` object bij het uitvoeren van een betaling, of een `PaymentResponse` object bij het ontvangen van een resultaat.

2. Verzoekbericht

MessageHeader-verzoek

De volgende velden zijn verplicht in elke MessageHeader van een verzoek:

Naam	Verplicht	Type	Beschrijving
ProtocolVersion	✅	String	Versie van het Nexo-protocol; momenteel 3.1
MessageClass	✅	Enum	De context van het verzoek; bijna altijd `Service` maar kan ook Device of Event zijn
MessageCategory	✅	Enum	Het type transactie (bv. `Payment` of `Input`); gespecificeerd in de documentatie voor elke flow
MessageType	✅	Enum	Altijd `Request`
ServiceID	✅	String	Uw unieke ID voor dit verzoek (1-10 alfanumerieke tekens).
SaleID	✅	String	Uw unieke ID voor het POS-systeem dat het verzoek verstuurt
POIID	✅	String	De ID van de doel-POI

Voorbeeld van request header

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

Bekijk het volledige schema op de API-specificatiepagina voor verplichte velden.

Request body

De vereiste velden in de request body variëren volgens de operatie die wordt uitgevoerd. U vindt specifieke voorbeelden en referentie-informatie met details voor elke operatie in onze online Local API-documentatie.

Naam	Verplicht	Type	Beschrijving
ProtocolVersion	✅	String	Versie van het Nexo-protocol; momenteel 3.1
MessageClass	✅	Enum	De context van het verzoek; bijna altijd `Service` maar kan ook Device of Event zijn
MessageCategory	✅	Enum	Het type transactie (bv. `Payment` of `Input`); gespecificeerd in de documentatie voor elke flow
MessageType	✅	Enum	Altijd `Request`
ServiceID	✅	String	Uw unieke ID voor dit verzoek (1-10 alfanumerieke tekens).
SaleID	✅	String	Uw unieke ID voor het POS-systeem dat het verzoek verstuurt
POIID	✅	String	De ID van de doel-POI

Voorbeeld van request header & body

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

Bekijk het volledige schema op de API-specificatiepagina voor verplichte velden.

3. Antwoordbericht

Antwoorden zijn vervat in één enkel object (vergelijkbaar met SaleToPOIResponse) en bevatten de MessageHeader en het bijbehorende Response body object.

Response header: deze echoot de waarden die u in het verzoek heeft opgegeven. De enige uitzondering is de MessageType, die altijd Response is.
Response body: deze bevat een transactie-identificatie en gegevens die nodig zijn om bonnen te genereren.

In een HTTP-integratie, voor asynchrone berichten, ontvangt u enkel een ok antwoord van de API. De MessageHeader en response body worden verstuurd als antwoord op een GET.

MessageHeader Response

De MessageHeader die u ontvangt in het antwoord, echoot de waarden die u in het verzoek heeft opgegeven. De enige uitzondering is de MessageType, die Response is.

Het volgende voorbeeld toont de header die u zou ontvangen als antwoord op het bovenstaand voorbeeld van een betalingsverzoek.

Voorbeeld van request header & body

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

Bekijk het volledige schema op de API-specificatiepagina voor verplichte velden.

Response body

De waarden die u ontvangt in de response body zijn afhankelijk van het type transactie dat u heeft aangevraagd. We voorzien voorbeelden en referentie-informatie voor elk transactietype in onze kassadocumentatie.

De response body bevat vaak een transactie-identificatie en gegevens die u kunt gebruiken om uw bonnen te genereren.

Voorbeeld van een antwoord:

Voorbeeld van request header & body

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

Bekijk het volledige schema op de API-specificatiepagina voor verplichte velden.

Transactie-identificatie

In elk antwoord retourneert de POI een transactie-identificatie: POIData.POITransactionID.TransactionID. U moet elke TransactionID bewaren, omdat dit een sleutelgegeven is om extra handelingen uit te voeren zoals:

Een transactie annuleren (Void),
Statuscontrole van de transactie,
Kaartacquisitiebetaling,
Preautorisatie

Bongegevens

In transactieresponsen kan het resultaat een PaymentReceipt object bevatten. U kunt de key-value pairs uit dit object toevoegen aan het ticket dat u print, toont of e-mailt aan uw klant.

In het PaymentReceipt-object is er een RequiredSignatureFlag die aangeeft dat het betalingsbewijs van de kaarthouder een fysieke handtekening van de klant vereist.

4. Identificeer de POI

De Diagnose laat de Point of Sale (POS)-applicatie toe het unieke serienummer van de hardware op te halen. Het primaire doel van het gebruiken van de validatie van het serienummer is fraudepreventie en systeemintegriteit.

Het POS-systeem kan tijdens het inloggen snel controleren om het unieke serienummer van de POI op te halen. Door dit nummer te vergelijken met een opgeslagen record, kan uw systeem onmiddellijk detecteren of een ongeautoriseerde of onbekende terminal in de configuratie is geplaatst. Dit creëert een eenvoudige, veilige, verifieerbare koppeling tussen de POS-software en het fysieke POI-apparaat.

Hieronder vindt u een eenvoudig voorstel voor implementatie:

Eerste installatie: haal het serienummer van de POI op en sla het op via een Diagnose verzoek. De eerste installatie moet worden vertrouwd volgens het installatieproces.
Volgende login: POS voert een nieuw Diagnose-verzoek uit. Als het geretourneerde serienummer niet overeenkomt met de opgeslagen waarde, moet het POS-systeem de gebruiker waarschuwen om te bevestigen of de POI legitiem is gewijzigd of niet.

U kunt ook het serienummer vergelijken met het bekende serienummer uit uw database. Dit kan eenvoudiger zijn voor P2PE-conforme klanten die de volledige levenscyclus van betaalterminals moeten volgen.