Standard POS integration

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.

Voici la traduction en français de votre description du flux de paiement :

Le flux de paiement de base détaille les messages nécessaires que votre logiciel de caisse (POS) doit gérer pour fonctionner efficacement :

Login (Connexion) : démarre une session opérationnelle avec le terminal, permettant de traiter des transactions depuis la caisse.
Payment (Paiement) : transaction de vente, utilisant une carte ou un autre instrument pour finaliser un achat au point de vente.
Abort (Abandon) : arrête et annule immédiatement une transaction en cours avant que la phase d'autorisation ne soit lancée.
TransactionStatus (Statut de la transaction) : vérifie le résultat final ou le dernier état de traitement connu d'une transaction précédente ; généralement déclenché après une perte de communication entre la caisse (POS) et le terminal (POI).
Reversal (Extourne / Annulation) : annule une transaction récemment approuvée en recréditant les fonds sur le compte ou la carte du client avant que la transaction ne soit compensée financièrement (settlement).
Refund (Remboursement) : restitue les fonds à un client suite à une vente qui a déjà été compensée, généralement lors d'un retour produit.
Logout (Déconnexion) : cette requête ferme la session opérationnelle active sur le terminal, concluant le service du caissier ou la période d'utilisation.

Avec ces 7 messages, votre logiciel de caisse couvrira le périmètre d'intégration standard. Vous trouverez les détails de ces messages ci-dessous. Nous proposons également des fonctionnalités complémentaires qui pourraient vous intéresser pour apporter plus de valeur ou de sécurité à vos clients.

1. Login

Le LoginRequest est la première étape obligatoire pour initier la communication avec le terminal de paiement (POI) et établir une session opérationnelle.

Cette opération doit être déclenchée au démarrage de l'application ou chaque fois que le caissier se connecte au système de caisse (POS). Son objectif principal est de transmettre l'identité du système (détails du logiciel de caisse) et le contexte opérationnel (ID de l'opérateur, Date/Heure) au POI, garantissant ainsi que toutes les transactions suivantes sont correctement enregistrées et autorisées..

Click to View: Login Request/Response Sequence Diagram

This diagram illustrates the mandatory synchronous exchange used to establish the session:

A. Login Request

Header

L'objet standard SaleToPOIRequest.MessageHeader, avec le champ MessageClass défini sur Service et le champ MessageCategory sur Login.

Body

Ce tableau détaille les champs requis au sein de l'objet LoginRequest, qui permet d'identifier le logiciel de caisse (POS) et l'opérateur pour la nouvelle session.

Field Name	Type	Required	Description
`DateTime`	String	Yes	The current date and time of the POS system at the moment the session is opened, in UTC following ISO 8601.
`OperatorID`	String	No	Identification of the specific cashier or operator (e.g., `"Cashier001"`).
`OperatorLanguage`	String	Yes	Defines the language preference of the cashier/operator (e.g., `EN`, `PL`), in ISO 639-1 codes, using two alpha characters.
`SaleSoftware.ApplicationName`	String	Yes	The name of the POS application sending the request (e.g., `"POS Simulator"`).
`SaleSoftware.ProviderIdentification`	String	Yes	Identification of the software provider (e.g., `"POS Provider ID"`).
`SaleSoftware.SoftwareVersion`	String	Yes	The version number of the POS application (e.g., `"22.1.1.0"`).

Login request example JSON

This section contains the detailed JSON payload needed for the login request:

{
  "MessageHeader": {
    "ProtocolVersion": "3.1",
    "MessageClass": "Service",
    "MessageCategory": "Login",
    "MessageType": "Request",
    "ServiceID": "823",
    "SaleID": "POS_123",
    "POIID": "POI_123"
  },
  "LoginRequest": {
    "DateTime": "2024-12-16T15:24:50.0+01:00",
    "OperatorID": "Cashier001",
    "OperatorLanguage": "EN",
    "SaleSoftware": [
      {
        "ApplicationName": "POS Simulator",
        "ProviderIdentification": "POS Provider ID",
        "SoftwareVersion": "22.1.1.0"
      }
    ],
  }
}

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

Login request example XML

This section contains the detailed XML payload needed for the login request:

<?xml version="1.0" encoding="UTF-8"?>
<SaleToPOIRequest xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
	<MessageHeader ProtocolVersion="3.1" MessageClass="Service" MessageCategory="Login" MessageType="Request" ServiceID="9343" SaleID="ECR001" POIID="456"></MessageHeader>
	<LoginRequest OperatorLanguage="EN" OperatorID="Cashier001">
		<DateTime>2025-03-03T10:39:46Z</DateTime>
		<SaleSoftware ProviderIdentification="CashRegisterCompany" ApplicationName="ECR Simulator" SoftwareVersion="0.0.5"></SaleSoftware>
		<SaleTerminalData>
			<SaleCapabilities/>
		</SaleTerminalData>
	</LoginRequest>
</SaleToPOIRequest>

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

B. Login Response

La réponse de connexion (Login Response) confirme que la session opérationnelle a été établie avec succès, fournissant au système de caisse (POS) des informations essentielles sur le statut et le logiciel du terminal de paiement (POI).

Deux résultats différents peuvent être attendus :

Succès : Une réponse avec Response.Result : « Success ».
Échec : Si une erreur d'analyse (parsing) survient, une EventNotification avec EventToNotify : « Reject » est renvoyée.

Le MessageHeader que vous recevez dans la réponse reprend les valeurs que vous avez fournies dans la requête. La seule exception est le MessageType, qui est « Response ».

Body

Ce tableau détaille les champs requis au sein de l'objet LoginResponse, qui identifie le logiciel de caisse (POS) et l'opérateur pour la nouvelle session. Vous trouverez un exemple de requête après le tableau.

JSON Path	Type	Description
`Response.Result`	Enum	Status of the login request. Must be `Success` to proceed with transactions.
`POISystemData.POIStatus.GlobalStatus`	Enum	The current overall health status of the terminal and its systems.
`POISystemData.DateTime`	String	The current date and time maintained by the POI (often used for synchronization).
`POISystemData.POISoftware`	String	Information related to the software of the POI.

Login response example JSON

This section contains the detailed JSON payload needed for the payment flow:

{
  "MessageHeader": {
    "MessageCategory": "Login",
    "MessageClass": "Service",
    "MessageType": "Response",
    "POIID": "POI_123",
    "ProtocolVersion": "3.1",
    "SaleID": "POS_123",
    "ServiceID": "823"
  },
  "LoginResponse": {
    "POISystemData": {
      "DateTime": "2025-11-28T14:12:59.6+01:00",
      "POISoftware": {
        "ApplicationName": "Pay On Site",
        "CertificationCode": "",
        "ProviderIdentification": "Market Pay",
        "SoftwareVersion": "4.1.0-71ce1a2b9-dev"
      },
      "POIStatus": {
        "GlobalStatus": "OK"
      }
    },
    "Response": {
      "Result": "Success"
    }
  }
}

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

Login response example XML

Each XML message payload has to be preceded by 4 bytes containing the number of bytes of the following XML message. The encoding is binary, big endian. This allows the application layer to always be able to determine if a complete XML message has been received before parsing it, regardless of the underlying protocol.

<SaleToPOIResponse>
   <LoginResponse>
      <POISystemData>
         <DateTime>2025-03-03T11:39:46.3+01:00</DateTime>
         <POISoftware ApplicationName="Pay On Site" CertificationCode="" ProviderIdentification="Market Pay" SoftwareVersion="2.0.6.1-3e0963690-qa"/>
         <POIStatus GlobalStatus="OK"/>
      </POISystemData>
      <Response Result="Success"/>
   </LoginResponse>
   <MessageHeader MessageCategory="Login" MessageClass="Service" MessageType="Response" POIID="456" ProtocolVersion="3.1" SaleID="ECR001" ServiceID="9343"/>
</SaleToPOIResponse>

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

EventNotification

Lorsqu'une requête de connexion (Login Request) échoue, le terminal de paiement (POI) répond avec un message EventNotification spécifique, signalant que le message a été rejeté ou n'a pas pu être traité. C'est généralement la méthode utilisée par le terminal pour signaler immédiatement au système de caisse (POS) une erreur de structure ou d'analyse (parsing) irrécupérable.

Le MessageHeader que vous recevez pour une EventNotification reprend les valeurs que vous avez fournies dans la requête. Les deux seules exceptions sont le MessageCategory, qui devient EventNotification, et le MessageType, qui devient Response.

Field Name	Type	Description
`EventNotification.EventToNotify`	String	The specific event that caused the rejection; here, `Reject`, indicating the Login message could not be parsed or validated by the POI.
`EventNotification.TimeStamp`	String	Date and time the POI detected the error and generated this notification.

Event notification example

If parsing error will happen during POI application handles incoming message, EventNotification will be returned:

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

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

Ces erreurs surviennent lorsque le POI est injoignable ou que les paramètres de session sont incorrects :

Format de message invalide : Des champs obligatoires (ex : DateTime, SaleSoftware) sont manquants dans la requête LoginRequest, ou la structure est corrompue.
POI injoignable : Le terminal est éteint, déconnecté du réseau, ou son adresse IP est inconnue ou incorrecte.
Conflit de session : Le terminal est déjà connecté avec un autre SaleID (ID de caisse), ou l'application du POI est occupée.

Au démarrage du POI, un certain temps peut s'écouler avant qu'il ne soit pleinement opérationnel et prêt à recevoir un message. Si vous rencontrez ce cas de figure, nous vous conseillons d'ajouter un délai et un mécanisme de rétentative pour la requête de connexion.

2. Payment

La requête de paiement (Payment Request) est le message de transaction principal utilisé pour initier un large éventail d'opérations financières sur le terminal de paiement (POI). Elle permet au logiciel de caisse (POS) de lancer des opérations telles qu'un paiement standard, une finalisation d'acquisition de carte, un remboursement, une pré-autorisation ou une finalisation de pré-autorisation.

Dans cette section, nous nous concentrerons sur le paiement standard. Les autres types sont détaillés dans des chapitres dédiés.

A. Payment Request

Header

L'objet standard SaleToPOIRequest.MessageHeader, avec MessageClass défini sur Service et MessageCategory sur Payment.

Body

Pour initier un paiement avec succès, le corps de la requête (PaymentRequest) doit contenir des données définissant le contexte de la vente ainsi que les détails financiers, plus précisément le montant de la transaction et l'identifiant unique de la transaction.

Ce tableau détaille les champs requis au sein de l'objet PaymentRequest.

Field Name	Required	Type	Description
`PaymentTransaction.AmountsReq.RequestedAmount`	Yes	Number	Total monetary value of the transaction requested for payment.
`PaymentTransaction.AmountsReq.Currency`	Yes	String	Currency of the requested amount (e.g., EUR, NOK...) in ISO 4217.
`SaleData.SaleTransactionID.TimeStamp`	Yes	String	Date and time of the request in UTC format.
`SaleData.SaleTransactionID.TransactionID`	Yes	String	The unique transaction reference ID from the POS. Currently limited to 35 characters as per ISO 20022 standard.
`PaymentData.PaymentType`	No	Enum	Defines the nature of the transaction. Default is `Normal`. Can also be `Refund`, `FirstReservation`...)

Payment Request example JSON

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

Payment Request example XML

<?xml version="1.0" encoding="UTF-8"?>
<SaleToPOIRequest xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
	<MessageHeader MessageClass="Service" MessageCategory="Payment" MessageType="Request" ServiceID="9345" SaleID="ECR001" POIID="456"></MessageHeader>
	<PaymentRequest>
		<SaleData OperatorID="666">
			<SaleTransactionID TransactionID="Transaction123" TimeStamp="2025-03-03T10:39:59Z"></SaleTransactionID>
		</SaleData>
		<PaymentTransaction>
			<AmountsReq Currency="EUR" RequestedAmount="12.34"></AmountsReq>
		</PaymentTransaction>
		<PaymentData></PaymentData>
		<MarketpayPaymentExtensions></MarketpayPaymentExtensions>
	</PaymentRequest>
</SaleToPOIRequest>

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

B. Intermediate Status

Lorsqu'une transaction de paiement s'exécute de manière asynchrone, le terminal de paiement (POI) utilise des messages de type Display Request pour informer le système de caisse (POS) de l'interaction requise de la part du client ou de l'état actuel du terminal. Le POS peut interpréter ces informations pour mettre à jour l'affichage client ou l'interface du caissier, puis continuer à attendre le résultat final.

Header

Le MessageHeader que vous recevez dans la réponse reprend les valeurs que vous avez fournies dans la requête. Les exceptions sont le MessageCategory, qui est Display, et le MessageType, qui est Request.

Body

Field Name	Type	Description
`DisplayOutput.Device`	Enum	The logical device where the information should be presented (e.g., `CashierDisplay`, `CustomerDisplay`...)
`DisplayOutput.InfoQualify`	Enum	Qualification of the information being sent (e.g., `Status`, `Input`...).
`DisplayOutput.ResponseRequiredFlag`	Boolean	Indicates if the POS is expected to send a reply message after processing the display.
`DisplayOutput.OutputContent.OutputFormat`	Enum	The format of the content being sent (e.g., text, reference ID, or menu).
`DisplayOutput.OutputContent.OutputText`	String	The actual text message or instruction to be displayed, can be: `WaitingForCard`, `PINRequired BankAuthorization`, `ApplicationSelection`

Event notification example JSON

{
  "MessageHeader": {
    "MessageCategory": "Display",
    "MessageClass": "Service",
    "MessageType": "Request",
    "POIID": "POI_01",
    "ProtocolVersion": "3.1",
    "SaleID": "POS_01",
    "ServiceID": "823"
  },
  "DisplayRequest": {
    "DisplayOutput": {
      "Device": "CashierDisplay",
      "InfoQualify": "Status",
      "ResponseRequiredFlag": "false",
      "OutputContent": {
        "OutputFormat": "MessageRef",
        "OutputText": "WaitingForCard",
        "PredefinedContent": {
          "ReferenceID": "1"
        }
      }
    }
  }
}

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

Event notification example XML

<SaleToPOIRequest>
   <DisplayRequest>
      <DisplayOutput Device="CashierDisplay" InfoQualify="Status" ResponseRequiredFlag="false">
         <OutputContent OutputFormat="MessageRef">
            <OutputText>WaitingForCard</OutputText>
            <PredefinedContent ReferenceID="1"/>
         </OutputContent>
      </DisplayOutput>
   </DisplayRequest>
   <MessageHeader MessageCategory="Display" MessageClass="Service" MessageType="Request" POIID="456" ProtocolVersion="3.1" SaleID="ECR001" ServiceID="9351"/>
</SaleToPOIRequest>

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

C. Payment Response

La réponse de paiement (Payment Response) est le message final et définitif envoyé par le terminal (POI) à la caisse (POS), confirmant l'issue d'une demande financière initiée par cette dernière. Elle marque la fin du flux de paiement et fournit toutes les données nécessaires au POS pour conclure la vente.

Les résultats attendus sont communiqués via le champ principal Response.Result :

Success (Succès) : Les fonds ont été capturés, réservés ou remboursés avec succès. La réponse contient tous les détails de la transaction et les reçus.
Failure (Échec) : L'opération n'a pas pu être menée à bien (ex : carte refusée, délai d'attente de la transaction dépassé). La réponse inclut des informations de diagnostic via les champs AdditionalResponse et ErrorCondition (si présents).

Le MessageHeader que vous recevez dans la réponse reprend les valeurs que vous avez fournies dans la requête. La seule exception est le MessageType, qui est « Response ».

Body

Le corps de la PaymentResponse fournit un enregistrement complet de la transaction. Le POS doit interpréter cette réponse pour identifier le résultat de l'opération et imprimer les reçus. Le tableau ci-dessous détaille les champs attendus au sein de l'objet PaymentResponse.

Field Name	Type	Key Information & POS Action
`Response.Result`	Enum	Transaction Outcome: Confirms the final status of the operation (`Success`, `Failure` or `Partial`). Must be checked first.
`PaymentResult.OnlineFlag`	Boolean	Exact amount authorized (key information for `Partial` results)
`PaymentResult.PaymentAcquirerData.ApprovalCode`	String	Authorization code assigned during payment processing
`PaymentResult.PaymentAcquirerData.ApprovalCode`	String	Authorization code assigned during payment processing
`POIData.POITransactionID.TransactionID`	String	Transaction ID assigned by the terminal, must be stored by POS. It is required for all follow-up operations (Reversal, Preauthorization completion...).
`PaymentResult.PaymentInstrumentData.PaymentInstrumentType`	String	Type of payment instrument: `Card`, `Mobile`, `StoredValue` ...
`PaymentResult.PaymentInstrumentData.CardData.EntryMode`	Enum	Entry mode of the payment instrument information: `ICC`, `Contactless`, `Scanned` ...
`PaymentResult.PaymentInstrumentData.CardData.PaymentBrand`	String	Card Type: Identifies the payment brand (e.g., VISA, MASTERCARD). Used for routing and receipt display.
`PaymentReceipt`	Array	Contains the text lines for the `CashierReceipt` and `CustomerReceipt`.
`PaymentReceipt.RequiredSignatureFlag`	Boolean	indicates whether the transaction requires customer's signature on the printed receipt.
`MarketpayPaymentExtensions.BankID`	String	Contains information on customer's card: `ApplicationID`, `BankID` and `PANSequenceNumber`

Payment Response example JSON

{
  "SaleToPOIResponse": {
    "MessageHeader": {
      "MessageCategory": "Payment",
      "MessageClass": "Service",
      "MessageType": "Response",
      "POIID": "456",
      "ProtocolVersion": "3.1",
      "SaleID": "ECR001",
      "ServiceID": "9345"
    },
    "PaymentResponse": {
      "MarketpayPaymentExtensions": {
        "ApplicationID": "A0000000041010",
        "BankID": "513640",
        "PANSequenceNumber": "01"
      },
      "PaymentReceipt": [
        {
          "DocumentQualifier": "CashierReceipt",
          "RequiredSignatureFlag": false,
          "OutputContent": {
            "OutputFormat": "Text",
            "OutputText": [
              {
                "EndOfLineFlag": true,
                "Text": "MERCHANT RECEIPT"
              },
              {
                "EndOfLineFlag": true,
                "Text": "--------------------------------"
              },
              {
                "EndOfLineFlag": true,
                "Text": "Candy Shop"
              },
              {
                "EndOfLineFlag": true,
                "Text": "75002 Paris"
              },
              {
                "EndOfLineFlag": true,
                "Text": "REFERENCE: 1"
              },
              {
                "EndOfLineFlag": true,
                "Text": "TID: 30010909"
              },
              {
                "EndOfLineFlag": true,
                "Text": "DEVICE NAME: 2290348732"
              },
              {
                "EndOfLineFlag": true,
                "Text": "MERCHANT: 000000001231344"
              },
              {
                "EndOfLineFlag": true,
                "Text": "PAN: XXXXXXXXXXXX7462 01"
              },
              {
                "EndOfLineFlag": true,
                "Text": "AID: A0000000041010"
              },
              {
                "EndOfLineFlag": true,
                "Text": "CARD TYPE: MASTERCARD"
              },
              {
                "EndOfLineFlag": true,
                "Text": "PAYMENT"
              },
              {
                "EndOfLineFlag": true,
                "Text": "CONTACTLESS"
              },
              {
                "EndOfLineFlag": true,
                "Text": "AMOUNT:€ 12,34"
              },
              {
                "EndOfLineFlag": true,
                "Text": "Approved"
              },
              {
                "EndOfLineFlag": true,
                "Text": "213462"
              },
              {
                "EndOfLineFlag": true,
                "Text": "TIME: 11:40:06"
              },
              {
                "EndOfLineFlag": true,
                "Text": "DATE: 03.03.2025"
              },
              {
                "EndOfLineFlag": true,
                "Text": "AUTHENTICATION METHOD: NO"
              },
              {
                "EndOfLineFlag": true,
                "Text": "CARDHOLDER VERIFICATION"
              },
              {
                "EndOfLineFlag": true,
                "Text": "PLEASE RETAIN FOR YOUR RECORDS"
              }
            ]
          }
        },
        {
          "DocumentQualifier": "CustomerReceipt",
          "RequiredSignatureFlag": false,
          "OutputContent": {
            "OutputFormat": "Text",
            "OutputText": [
              {
                "EndOfLineFlag": true,
                "Text": "RECU PORTEUR"
              },
              {
                "EndOfLineFlag": true,
                "Text": "--------------------------------"
              },
              {
                "EndOfLineFlag": true,
                "Text": "Candy Shop"
              },
              {
                "EndOfLineFlag": true,
                "Text": "75002 Paris"
              },
              {
                "EndOfLineFlag": true,
                "Text": "RÉFÉRENCE: 1"
              },
              {
                "EndOfLineFlag": true,
                "Text": "TID: 30010909"
              },
              {
                "EndOfLineFlag": true,
                "Text": "NOM DE L'APPAREIL: 2290348732"
              },
              {
                "EndOfLineFlag": true,
                "Text": "MARCHAND: 000000001231344"
              },
              {
                "EndOfLineFlag": true,
                "Text": "PAN: XXXXXXXXXXXX7462 01"
              },
              {
                "EndOfLineFlag": true,
                "Text": "AID: A0000000041010"
              },
              {
                "EndOfLineFlag": true,
                "Text": "TYPE DE CARTE: MASTERCARD"
              },
              {
                "EndOfLineFlag": true,
                "Text": "PAIEMENT"
              },
              {
                "EndOfLineFlag": true,
                "Text": "SANS CONTACT"
              },
              {
                "EndOfLineFlag": true,
                "Text": "MONTANT:€ 12,34"
              },
              {
                "EndOfLineFlag": true,
                "Text": "Approuvé"
              },
              {
                "EndOfLineFlag": true,
                "Text": "213462"
              },
              {
                "EndOfLineFlag": true,
                "Text": "TIME: 11:40:06"
              },
              {
                "EndOfLineFlag": true,
                "Text": "DATE: 03.03.2025"
              },
              {
                "EndOfLineFlag": true,
                "Text": "METHODE"
              },
              {
                "EndOfLineFlag": true,
                "Text": "D'AUTHENTIFICATION: AUCUNE"
              },
              {
                "EndOfLineFlag": true,
                "Text": "VÉRIFICATION DU TITULAIRE DE LA"
              },
              {
                "EndOfLineFlag": true,
                "Text": "CARTE"
              },
              {
                "EndOfLineFlag": true,
                "Text": "VEUILLEZ CONSERVER POUR VOS"
              },
              {
                "EndOfLineFlag": true,
                "Text": "DOSSIERS"
              }
            ]
          }
        }
      ],
      "PaymentResult": {
        "MerchantOverrideFlag": false,
        "OnlineFlag": true,
        "AmountsResp": {
          "AuthorizedAmount": "12.34",
          "Currency": "EUR"
        },
        "PaymentAcquirerData": {
          "AcquirerID": "40105611508",
          "AcquirerPOIID": "30010909",
          "MerchantID": "000000001231344",
          "ApprovalCode": "213462"
        },
        "PaymentInstrumentData": {
          "PaymentInstrumentType": "Card",
          "CardData": {
            "EntryMode": "Contactless",
            "MaskedPAN": "XXXXXXXXXXXX7462",
            "PaymentBrand": "MASTERCARD"
          }
        }
      },
      "POIData": {
        "POITransactionID": {
          "TimeStamp": "2025-03-03T11:40:06.500",
          "TransactionID": "1"
        }
      },
      "Response": {
        "Result": "Success",
        "AdditionalResponse": "000"
      },
      "SaleData": {
        "OperatorID": "666",
        "SaleTransactionID": {
          "TimeStamp": "2025-03-03T10:39:59Z",
          "TransactionID": "Transaction123"
        }
      }
    }
  }
}

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

Payment Response example XML

<SaleToPOIResponse>
   <MessageHeader MessageCategory="Payment" MessageClass="Service" MessageType="Response" POIID="456" ProtocolVersion="3.1" SaleID="ECR001" ServiceID="9345"/>
   <PaymentResponse>
      <MarketpayPaymentExtensions ApplicationID="A0000000041010" BankID="513640" PANSequenceNumber="01"/>
      <PaymentReceipt DocumentQualifier="CashierReceipt" RequiredSignatureFlag="false">
         <OutputContent OutputFormat="Text">
            <OutputText EndOfLineFlag="true">MERCHANT RECEIPT</OutputText>
            <OutputText EndOfLineFlag="true">--------------------------------</OutputText>
            <OutputText EndOfLineFlag="true">Candy Shop</OutputText>
            <OutputText EndOfLineFlag="true">75002 Paris</OutputText>
            <OutputText EndOfLineFlag="true">REFERENCE: 1</OutputText>
            <OutputText EndOfLineFlag="true">TID: 30010909</OutputText>
            <OutputText EndOfLineFlag="true">DEVICE NAME: 2290348732</OutputText>
            <OutputText EndOfLineFlag="true">MERCHANT: 000000001231344</OutputText>
            <OutputText EndOfLineFlag="true">PAN: XXXXXXXXXXXX7462 01</OutputText>
            <OutputText EndOfLineFlag="true">AID: A0000000041010</OutputText>
            <OutputText EndOfLineFlag="true">CARD TYPE: MASTERCARD</OutputText>
            <OutputText EndOfLineFlag="true">PAYMENT</OutputText>
            <OutputText EndOfLineFlag="true">CONTACTLESS</OutputText>
            <OutputText EndOfLineFlag="true">AMOUNT:€ 12,34</OutputText>
            <OutputText EndOfLineFlag="true">Approved</OutputText>
            <OutputText EndOfLineFlag="true">213462</OutputText>
            <OutputText EndOfLineFlag="true">TIME: 11:40:06</OutputText>
            <OutputText EndOfLineFlag="true">DATE: 03.03.2025</OutputText>
            <OutputText EndOfLineFlag="true">AUTHENTICATION METHOD: NO</OutputText>
            <OutputText EndOfLineFlag="true">CARDHOLDER VERIFICATION</OutputText>
            <OutputText EndOfLineFlag="true">PLEASE RETAIN FOR YOUR RECORDS</OutputText>
         </OutputContent>
      </PaymentReceipt>
      <PaymentReceipt DocumentQualifier="CustomerReceipt" RequiredSignatureFlag="false">
         <OutputContent OutputFormat="Text">
            <OutputText EndOfLineFlag="true">RECU PORTEUR</OutputText>
            <OutputText EndOfLineFlag="true">--------------------------------</OutputText>
            <OutputText EndOfLineFlag="true">Candy Shop</OutputText>
            <OutputText EndOfLineFlag="true">75002 Paris</OutputText>
            <OutputText EndOfLineFlag="true">RÉFÉRENCE: 1</OutputText>
            <OutputText EndOfLineFlag="true">TID: 30010909</OutputText>
            <OutputText EndOfLineFlag="true">NOM DE L&apos;APPAREIL: 2290348732</OutputText>
            <OutputText EndOfLineFlag="true">MARCHAND: 000000001231344</OutputText>
            <OutputText EndOfLineFlag="true">PAN: XXXXXXXXXXXX7462 01</OutputText>
            <OutputText EndOfLineFlag="true">AID: A0000000041010</OutputText>
            <OutputText EndOfLineFlag="true">TYPE DE CARTE: MASTERCARD</OutputText>
            <OutputText EndOfLineFlag="true">PAIEMENT</OutputText>
            <OutputText EndOfLineFlag="true">SANS CONTACT</OutputText>
            <OutputText EndOfLineFlag="true">MONTANT:€ 12,34</OutputText>
            <OutputText EndOfLineFlag="true">Approuvé</OutputText>
            <OutputText EndOfLineFlag="true">213462</OutputText>
            <OutputText EndOfLineFlag="true">TIME: 11:40:06</OutputText>
            <OutputText EndOfLineFlag="true">DATE: 03.03.2025</OutputText>
            <OutputText EndOfLineFlag="true">METHODE</OutputText>
            <OutputText EndOfLineFlag="true">D&apos;AUTHENTIFICATION: AUCUNE</OutputText>
            <OutputText EndOfLineFlag="true">VÉRIFICATION DU TITULAIRE DE LA</OutputText>
            <OutputText EndOfLineFlag="true">CARTE</OutputText>
            <OutputText EndOfLineFlag="true">VEUILLEZ CONSERVER POUR VOS</OutputText>
            <OutputText EndOfLineFlag="true">DOSSIERS</OutputText>
         </OutputContent>
      </PaymentReceipt>
      <PaymentResult MerchantOverrideFlag="false" OnlineFlag="true">
         <AmountsResp AuthorizedAmount="12.34" Currency="EUR"/>
         <PaymentAcquirerData AcquirerID="40105611508" AcquirerPOIID="30010909" MerchantID="000000001231344">
            <ApprovalCode>213462</ApprovalCode>
         </PaymentAcquirerData>
         <PaymentInstrumentData PaymentInstrumentType="Card">
            <CardData EntryMode="Contactless" MaskedPAN="XXXXXXXXXXXX7462" PaymentBrand="MASTERCARD"/>
         </PaymentInstrumentData>
      </PaymentResult>
      <POIData>
         <POITransactionID TimeStamp="2025-03-03T11:40:06.500" TransactionID="1"/>
      </POIData>
      <Response Result="Success">
         <AdditionalResponse>000</AdditionalResponse>
      </Response>
      <SaleData OperatorID="666">
         <SaleTransactionID TimeStamp="2025-03-03T10:39:59Z" TransactionID="Transaction123"/>
      </SaleData>
   </PaymentResponse>
</SaleToPOIResponse>

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

D. Error handling

Voici la traduction en français de votre documentation technique :

Lorsqu'une opération de paiement échoue, le système de caisse (POS) doit catégoriser l'erreur afin de déterminer l'action de récupération appropriée et éviter tout écart financier.

Erreur de conflit de communication

Cette défaillance survient avant même que le terminal de paiement (POI) ne puisse commencer à traiter la logique de la transaction. Le terminal est alors occupé par une autre opération.

Transaction refusée (Decline)

Le POI délivre un message de réponse final contenant le champ de résultat définitif défini sur Result: "Failure".

Cause : La carte a été refusée par l'émetteur, un serveur de paiement était injoignable, ou une erreur spécifique à l'hôte a empêché l'autorisation.
Diagnostic : Le corps de la réponse contient des champs de diagnostic tels que AdditionalResponse et, potentiellement, ErrorCondition expliquant la raison du refus.

Notification d'événement (Event Notification)

Cela signale que le POI n'a pas pu comprendre la structure du message envoyé par le POS. Le POI envoie un message EventNotification avec le champ EventToNotify défini sur Reject.

Cause : Le message de demande de paiement était syntaxiquement incorrect, il manquait un champ obligatoire, ou les données ont été corrompues pendant la transmission.

Action requise : Le POS doit inspecter la charge utile (payload) envoyée au POI, corriger l'erreur structurelle (formatage, champs obligatoires, etc.), puis tenter à nouveau la transaction.

Event notification example JSON

{
  "MessageHeader": {
    "MessageCategory": "EventNotification",
    "MessageClass": "Service",
    "MessageType": "Response",
    "POIID": "POI01",
    "ProtocolVersion": "3.0",
    "SaleID": "POS001",
    "ServiceID": "823"
  },
  "EventNotification": {
    "TimeStamp": "2025-11-28T14:12:59.6+01:00",
    "EventToNotify": "Reject"
  }
}

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

3. Abort

Vous pouvez ensuite envoyer une requête d'abandon (Abort Request) pour interrompre une transaction en cours. Lorsque cette requête est reçue avant que la transaction ne soit envoyée en autorisation, le paiement est annulé. Si le client a inséré sa carte mais n'a pas encore validé son code PIN, l'opération peut toujours être abandonnée.

Pour les transactions complexes commençant par une acquisition de carte (Card Acquisition, un paiement en deux étapes), la requête d'abandon standard est ignorée. Reportez-vous à la documentation sur l'acquisition de carte pour plus d'informations.

A. Abort Request

Header

The standard SaleToPOIRequest.MessageHeader object, with MessageClass set to Service and MessageCategory set to Abort.

Body

This table details the fields required within the AbortRequest object.

Field Name	Type	Required	Description for POS (How to use it)
`MessageReference.MessageCategory`	Enum	Yes	Must match the category of the transaction being stopped (e.g., `"Payment"`, `"Reversal"`).
`MessageReference.ServiceID`	String	Yes	The unique `ServiceID` of the original transaction.
`MessageReference.SaleID`	String	Yes	Identification of the Sale Terminal that initiated the operation.
`AbortRequest.AbortReason`	String	Yes	A free-text field or code explaining why the transaction is being aborted (e.g., "MerchantAbort").

The example shows how to cancel an in-progress payment with a ServiceID of 830.

AbortRequest for Payment example JSON

{
  "MessageHeader": {
    "MessageClass": "Service",
    "MessageCategory": "Abort",
    "MessageType": "Request",
    "ServiceID": "831",
    "SaleID": "POS_01",
    "POIID": "Terminal_01"
  },
  "AbortRequest": {
    "MessageReference": {
      "MessageCategory": "Payment",
      "ServiceID": "830",
      "SaleID": "POS_01",
    },
    "AbortReason": "MerchantAbort"
  }
}

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

AbortRequest for Payment example XML

<?xml version="3.1" encoding="UTF-8"?>
<SaleToPOIRequest xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
	<MessageHeader MessageClass="Service" MessageCategory="Abort" MessageType="Request" ServiceID="3909" SaleID="ECR001" POIID="456"></MessageHeader>
	<AbortRequest>
		<MessageReference MessageCategory="Payment" ServiceID="830" SaleID="ECR_01" POIID="456"></MessageReference>
		<AbortReason>MerchantAbort</AbortReason>
	</AbortRequest>
</SaleToPOIRequest>

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

B. Abort Reponse

Check the responses:

A successful abort request returns a response with a 200 OK HTTP status code and no body.
The payment request returns a response containing:
- Result: Failure
- ErrorCondition: Aborted

Abort Response example JSON

{
  "SaleToPOIResponse": {
    "MessageHeader": {
      "MessageCategory": "Payment",
      "MessageClass": "Service",
      "MessageType": "Response",
      "POIID": "456",
      "ProtocolVersion": "3.1",
      "SaleID": "ECR_01",
      "ServiceID": "3908"
    },
    "PaymentResponse": {
      "MarketpayPaymentExtensions": {},
      "PaymentResult": {
        "OnlineFlag": false,
        "PaymentType": "Normal"
      },
      "POIData": {
        "POITransactionID": {
          "TimeStamp": "2025-03-29T13:40:12.118",
          "TransactionID": "1"
        }
      },
      "Response": {
        "ErrorCondition": "Aborted",
        "Result": "Failure"
      },
      "SaleData": {
        "OperatorID": "Cashier_01",
        "SaleTransactionID": {
          "TimeStamp": "2025-03-29T12:40:09Z",
          "TransactionID": "123"
        }
      }
    }
  }
}

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

Abort Response example XML

<SaleToPOIResponse>
   <MessageHeader MessageCategory="Payment" MessageClass="Service" MessageType="Response" POIID="456" ProtocolVersion="3.1" SaleID="ECR001" ServiceID="3908"/>
   <PaymentResponse>
      <MarketpayPaymentExtensions/>
      <PaymentResult OnlineFlag="false" PaymentType="Normal"/>
      <POIData>
         <POITransactionID TimeStamp="2025-03-29T13:40:12.118" TransactionID="1"/>
      </POIData>
      <Response ErrorCondition="Aborted" Result="Failure"/>
      <SaleData OperatorID="666">
         <SaleTransactionID TimeStamp="2025-03-29T12:40:09Z" TransactionID="123"/>
      </SaleData>
   </PaymentResponse>
</SaleToPOIResponse>

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

To double-check the payment was indeed cancelled, make a transaction status request. The TransactionStatusRequest.MessageReference object should contain:

ServiceID: The ServiceID of the payment you tried to cancel.
MessageCategory: Set to Payment

C. Error handling

Cancel from the terminal

To cancel an in-progress payment on a terminal:

with keypad: on the keypad, select the Cancel key (red button)
touchscreen only: on the transaction screen: click on Cancel transaction button

If this is successful:

The terminal shows a Cancelled message on the display.
The payment request returns a response containing:
- Result: Failure
- ErrorCondition: Cancel

Handling failed cancel requests

If your cancel request failed (and the payment was approved), you will need to refund the payment.

4. Transaction Status

The Status Request is a critical operation used by your Point of Sale (POS) to ask about the final result or status of a previously initiated transaction when that result was not received. This function can be used to recover from different scenario:

Timeout
Connection loss or failure
System failure or program crash

Status Request asks the Payment Terminal (POI) to provide the transaction's current state: whether the transaction was processed (Success or Failure), is still in progress, or was not found on the terminal. If the transaction was processed, the POS receives the original transaction response (e.g., the complete PaymentResponse or ReversalResponse body) detailing the final outcome. POS should automatically checks the status of a transaction any time it fails to receive a transaction response

Transaction status request might be used to extract previous transaction response from terminal. In current POI implementation only last message will be returned

A. Transaction Status Request

Header

The standard SaleToPOIRequest.MessageHeader object, with MessageClass set to Service and MessageCategory set to TransactionStatus.

Body

The body of the Transaction Status Request is sent as an empty object ({}) because the request to retrieve the last transaction's status relies solely on the contextual identifiers already provided in the MessageHeader (such as POIID and SaleID).

Status request example JSON

{
  "MessageHeader": {
    "ProtocolVersion": "3.1",
    "MessageClass": "Service",
    "MessageCategory": "TransactionStatus",
    "MessageType": "Request",
    "ServiceID": "838",
    "SaleID": "POS_01",
    "POIID": "POI_01"
  },
  "TransactionStatusRequest": {}
}

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

Status request example XML

<?xml version="1.0" encoding="UTF-8"?>
<SaleToPOIRequest xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
	<MessageHeader MessageClass="Service" MessageCategory="TransactionStatus" MessageType="Request" ServiceID="3911" SaleID="ECR001" POIID="456"></MessageHeader>
	<TransactionStatusRequest></TransactionStatusRequest>
</SaleToPOIRequest>

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

B. Transaction Status Responses

The POI returns an immediate response with the message that was missed by the POS: a TransactionStatusResponse or an EventNotification

A TransactionStatusResponse.Response with a Result of Success indicates that the transaction reached an end state: approved, cancelled, or declined.

The TransactionStatusResponse contains the original transaction's final message in the RepeatedMessageResponse object. To determine the result of the transaction, use the original transaction response, provided in the RepeatedResponseMessageBody. For example:

PaymentResponse.Response has Result Success: the payment succeeded.
PaymentResponse.Response has Result Failure, read ErrorCondition to determine the reason failure (cancel by customer, ...).

Positive Payment - TransactionStatus Response example

{
  "MessageHeader": {
    "MessageCategory": "TransactionStatus",
    "MessageClass": "Service",
    "MessageType": "Response",
    "POIID": "POI01",
    "ProtocolVersion": "3.0",
    "SaleID": "POS001",
    "ServiceID": "823"
  },
  "TransactionStatusResponse": {
    "RepeatedMessageResponse": {
      "MessageHeader": {
        "MessageCategory": "Payment",
        "MessageClass": "Service",
        "MessageType": "Response",
        "POIID": "POI01",
        "ProtocolVersion": "3.0",
        "SaleID": "POS001",
        "ServiceID": "823"
      },
      "PaymentResponse": {
        "MarketpayPaymentExtensions": {
          "ApplicationID": "A0000000031010",
          "BankID": "476173",
          "PANSequenceNumber": "01",
          "TVR": "AAAAAAA=",
          "CardAcquisitionReference": {
            "TimeStamp": "2025-11-28T13:51:59Z",
            "TransactionID": "83"
          }
        },
        "PaymentReceipt": [
          {
            "DocumentQualifier": "CashierReceipt",
            "RequiredSignatureFlag": "false",
            "OutputContent": {
              "OutputFormat": "Text",
              "OutputText": [
                {
                  "EndOfLineFlag": "true",
                  "Value": "RECEIPT ITEM"
                }
              ]
            }
          },
          {
            "DocumentQualifier": "CustomerReceipt",
            "RequiredSignatureFlag": "false",
            "OutputContent": {
              "OutputFormat": "Text",
              "OutputText": [
                {
                  "EndOfLineFlag": "true",
                  "Value": "RECEIPT ITEM"
                }
              ]
            }
          }
        ],
        "PaymentResult": {
          "MerchantOverrideFlag": "false",
          "OnlineFlag": "true",
          "AmountsResp": {
            "AuthorizedAmount": "11.99",
            "Currency": "EUR"
          },
          "PaymentAcquirerData": {
            "AcquirerID": "40105611508",
            "AcquirerPOIID": "HELP911",
            "MerchantID": "000000000000001",
            "ApprovalCode": "213462"
          },
          "PaymentInstrumentData": {
            "PaymentInstrumentType": "Card",
            "CardData": {
              "EntryMode": "Contactless",
              "MaskedPAN": "XXXXXXXXXXXX0027",
              "PaymentBrand": "VISA"
            }
          }
        },
        "POIData": {
          "POITransactionID": {
            "TimeStamp": "2025-11-28T14:12:59.6+01:00",
            "TransactionID": "9991"
          }
        },
        "Response": {
          "Result": "Success",
          "AdditionalResponse": "000"
        },
        "SaleData": {
          "OperatorID": "456",
          "SaleTransactionID": {
            "TimeStamp": "2025-11-28T14:12:59.6+01:00",
            "TransactionID": "9991"
          },
          "SponsoredMerchant": {
            "Address": "9 RUE DU 4 SEPTEMBRE\n75002 PARIS",
            "CommonName": "MARKET PAY PRECERT",
            "CountryCode": "NO",
            "MerchantCategoryCode": "4411",
            "RegisteredIdentifier": "198703093982001"
          }
        }
      }
    },
    "Response": {
      "Result": "Success"
    }
  }
}

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

Positive Reversal - TransactionStatus Response example

{
  "MessageHeader": {
    "MessageCategory": "TransactionStatus",
    "MessageClass": "Service",
    "MessageType": "Response",
    "POIID": "POI01",
    "ProtocolVersion": "3.0",
    "SaleID": "POS001",
    "ServiceID": "823"
  },
  "TransactionStatusResponse": {
    "RepeatedMessageResponse": {
      "MessageHeader": {
        "MessageCategory": "Reversal",
        "MessageClass": "Service",
        "MessageType": "Response",
        "POIID": "POI01",
        "ProtocolVersion": "3.0",
        "SaleID": "POS001",
        "ServiceID": "823"
      },
      "ReversalResponse": {
        "ReversedAmount": "11.99",
        "CustomerOrder": {
          "ForecastedAmount": "11.99",
          "StartDate": "2025-11-28T14:12:59.6+01:00"
        },
        "MarketpayPaymentExtensions": {
          "AcquirerId": "40105611508",
          "ApplicationID": "A0000000031010",
          "Currency": "EUR",
          "OriginalTransactionType": "Credit",
          "PaymentInstrumentData": {
            "PaymentInstrumentType": "Card",
            "CardData": {
              "PaymentBrand": "VISA",
              "SensitiveCardData": {
                "PAN": "XXXXXXXXXXXX0027",
                "CardSeqNumb": "01",
                "ExpiryDate": "2412"
              }
            }
          }
        },
        "OriginalPOITransaction": {
          "POITransactionID": {
            "TimeStamp": "2025-11-28T14:12:59.6+01:00",
            "TransactionID": "9991"
          }
        },
        "PaymentReceipt": [
          {
            "DocumentQualifier": "CashierReceipt",
            "RequiredSignatureFlag": "false",
            "OutputContent": {
              "OutputFormat": "Text",
              "OutputText": [
                {
                  "EndOfLineFlag": "true",
                  "Value": "RECEIPT ITEM"
                }
              ]
            }
          },
          {
            "DocumentQualifier": "CustomerReceipt",
            "RequiredSignatureFlag": "false",
            "OutputContent": {
              "OutputFormat": "Text",
              "OutputText": [
                {
                  "EndOfLineFlag": "true",
                  "Value": "RECEIPT ITEM"
                }
              ]
            }
          }
        ],
        "POIData": {
          "POITransactionID": {
            "TimeStamp": "2025-11-28T14:12:59.6+01:00",
            "TransactionID": "9991"
          }
        },
        "Response": {
          "Result": "Success"
        },
        "SaleData": {
          "OperatorID": "456",
          "SaleTransactionID": {
            "TimeStamp": "2025-11-28T14:12:59.6+01:00",
            "TransactionID": "9991"
          },
          "SponsoredMerchant": {
            "Address": "9 RUE DU 4 SEPTEMBRE\n75002 PARIS",
            "CommonName": "MARKET PAY PRECERT",
            "CountryCode": "NO",
            "MerchantCategoryCode": "4411",
            "RegisteredIdentifier": "198703093982001"
          }
        }
      }
    },
    "Response": {
      "Result": "Success"
    }
  }
}

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

Positive card acquisition transaction status response

{
  "MessageHeader": {
    "MessageCategory": "TransactionStatus",
    "MessageClass": "Service",
    "MessageType": "Response",
    "POIID": "POI01",
    "ProtocolVersion": "3.0",
    "SaleID": "POS001",
    "ServiceID": "823"
  },
  "TransactionStatusResponse": {
    "RepeatedMessageResponse": {
      "MessageHeader": {
        "MessageCategory": "CardAcquisition",
        "MessageClass": "Service",
        "MessageType": "Response",
        "POIID": "POI01",
        "ProtocolVersion": "3.0",
        "SaleID": "POS001",
        "ServiceID": "823"
      },
      "CardAcquisitionResponse": {
        "MarketpayPaymentExtensions": {
          "ApplicationID": "A0000000031010",
          "BankID": "476173",
          "PANSequenceNumber": "01",
          "CardAcquisitionReference": {
            "TimeStamp": "2025-11-28T14:12:59.6+01:00",
            "TransactionID": "9990"
          }
        },
        "PaymentInstrumentData": {
          "PaymentInstrumentType": "Card",
          "CardData": {
            "EntryMode": "Contactless",
            "MaskedPAN": "XXXXXXXXXXXX0027"
          }
        },
        "POIData": {
          "POITransactionID": {
            "TimeStamp": "2025-11-28T14:12:59.6+01:00",
            "TransactionID": "9991"
          }
        },
        "Response": {
          "Result": "Success",
          "AdditionalResponse": "PFJlc3BvbnNlPgogICA8RGVzY3JpcHRpb24+VG9rZW4gcmVzcG9uc2UgY29ycnVwdGVkLiBGYWlsZWRUb2tlbkdlbmVyYXRpb25SZXNwb25zZShlcnJvcklEPSwgcmV0dXJuQ29kZT0sIHJldHVybk1lc3NhZ2U9MSBleGNlcHRpb25zIG9jY3VycmVkLiAsIHN0YXJ0VGltZT0sIGVuZFRpbWU9KTwvRGVzY3JpcHRpb24+CiAgIDxMb3lhbHR5RXJyb3JGbGFnPnRydWU8L0xveWFsdHlFcnJvckZsYWc+CjwvUmVzcG9uc2U+"
        },
        "SaleData": {
          "OperatorID": "456",
          "SaleTransactionID": {
            "TimeStamp": "2025-11-28T14:12:59.6+01:00",
            "TransactionID": "9991"
          }
        }
      }
    },
    "Response": {
      "Result": "Success"
    }
  }
}

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

Transaction not found

A TransactionStatusResponse.Response with an ErrorCondition of NotFound indicates that we were not able to find the transaction with the SaleID and ServiceID you specified.

When the transaction is not found, this means that either:

The POIID, SaleID or ServiceID you specified in the transaction status request are incorrect. Check that you provided the POIID, SaleID, and ServiceID from the original transaction in the TransactionStatusRequest.MessageReference.
POI did not receive the original transaction request. The cause can be a dropped internet connection or an unexpected power loss. You can retry the original transaction.

The example response below indicates that this transaction was not found.

Transaction not found - TransactionStatus Example

{
  "MessageHeader": {
    "MessageCategory": "TransactionStatus",
    "MessageClass": "Service",
    "MessageType": "Response",
    "POIID": "POI_01",
    "ProtocolVersion": "3.1",
    "SaleID": "POS_01",
    "ServiceID": "838"
  },
  "TransactionStatusResponse": {
    "Response": {
      "Result": "Failure",
      "ErrorCondition": "NotFound"
    }
  }
}

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

Error handling

If the POI application detects a parsing error while handling an incoming message, an EventNotification will be returned, as shown in the example below.

Event notification example

If parsing error will happen during POI application handles incoming message, EventNotification will be returned:

{
  "MessageHeader": {
    "MessageCategory": "EventNotification",
    "MessageClass": "Service",
    "MessageType": "Response",
    "POIID": "POS_01",
    "ProtocolVersion": "3.1",
    "SaleID": "123",
    "ServiceID": "838"
  },
  "EventNotification": {
    "timeStamp": "2025-04-02T15:48:47.596+02:00",
    "eventToNotify": "Reject"
  }
}

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

5. Reversal

A Reversal can be used to cancels a previous Payment, Loyalty or Stored Value transaction. It used to undo a transaction that was processed and successfully approved by the system.

It is primarily used to correct errors, process customer returns, or undo a transaction immediately after it was committed. Unlike an Abort Request (which terminates an in-progress transaction), a Reversal is only applicable to a transaction that has reached a final success state.

Payment transaction can be voided by a reversal as long as reconciliation has not been done. After the clearing of the transaction by the Acquirer, the payment transaction can only be voided by a refund transaction, which requires a new payment transaction.

A. Reversal Request

Header

The standard SaleToPOIRequest.MessageHeader object, with MessageClass set to Service and MessageCategory set to Reversal.

Body

This table details the fields required within the LoginRequest object, which identifies the POS software and the operator for the new session.

Field Name	Type	Required	Description for POS (Purpose)
`OriginalPOITransaction.POITransactionID.TransactionID`	String	Yes	The unique Transaction ID the POI assigned to the original transaction (e.g., "9990").
`OriginalPOITransaction.POITransactionID.TimeStamp`	String	Yes	The Date and Time the POI recorded the original transaction.
`ReversalReason`	Enum	Yes	Explains why the transaction is being cancelled (e.g., merchant error, customer cancellation, unable to complete).
`ReversedAmount`	Number	No	The specific amount to reverse. If omitted, the entire original Authorized Amount is assumed.
`Currency`	String	No	The currency of the original transaction.
`SaleData.SaleTransactionID.TransactionID`	String	Yes	The ID assigned by the POS for this Reversal Request itself (for tracking the reversal attempt), e.g., "9991"

Reversal Request example JSON

{
  "MessageHeader": {
    "MessageCategory": "Reversal",
    "MessageClass": "Service",
    "MessageType": "Request",
    "POIID": "POI_01",
    "ProtocolVersion": "3.1",
    "SaleID": "POS_01",
    "ServiceID": "823"
  },
  "ReversalRequest": {
    "Currency": "EUR",
    "ReversedAmount": 11.99
    "OriginalPOITransaction": {
      "POITransactionID": {
        "TimeStamp": "2025-11-28T14:12:59.6+01:00",
        "TransactionID": "9990"
      },
      "SaleID": "POS_01"
    },
    "ReversalReason": "Unable2Compl",
    "SaleData": {
      "OperatorID": "Cashier_01",
      "SaleReferenceID": "19",
      "SaleTransactionID": {
        "TimeStamp": "2025-11-28T14:12:59.6+01:00",
        "TransactionID": "9991"
      }
    }
  }
}

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

Reversal Request example XML

<?xml version="1.0" encoding="UTF-8"?>
<SaleToPOIRequest xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
	<MessageHeader MessageClass="Service" MessageCategory="Reversal" MessageType="Request" ServiceID="3913" SaleID="ECR001" POIID="456"></MessageHeader>
	<ReversalRequest ReversalReason="MerchantCancel" ReversedAmount="10.02">
		<SaleData OperatorID="666">
			<SaleTransactionID TransactionID="123" TimeStamp="1970-01-01T00:00:00Z"></SaleTransactionID>
		</SaleData>
		<OriginalPOITransaction LastTransactionFlag="false">
			<POITransactionID TransactionID="2" TimeStamp="1970-01-01T00:00:00Z"></POITransactionID>
		</OriginalPOITransaction>
		<CustomerOrder StartDate="2025-03-29T12:41:46Z" ForecastedAmount="10.02" Currency="EUR"></CustomerOrder>
		<MarketpayPaymentExtensions></MarketpayPaymentExtensions>
	</ReversalRequest>
</SaleToPOIRequest>

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

Reversal when you do not know the POI TransactionID

In case of a communication or technical issue, the payment or card acquisition request can remain in-progress. When this happens, the terminal cannot be used until the request times out on its own, usually after 120 seconds. Because you haven't received the response yet, you do not have the TransactionID required to reverse the transaction.

You can get the TransactionID of the original request by sending a transaction status request. You can then follow up with request to reverse the operation.

B. Reversal Response

The Reversal Response is the final message confirming the outcome of a reversal request, indicating whether the attempt to cancel the original transaction was successful or failed.

Header

The MessageHeader you receive in the response echoes the values you provided in the request. The exceptions is the MessageType, which is Response.

Body

Field Name	Type	Description
`Response.Result`	Enum	Transaction Outcome, confirms the final status of the reversal operation. Must be `Success` to confirm cancellation.
`ReversedAmount`	Number	Amount Reversed: precise amount that was successfully credited back to the customer's account/card.
`OriginalPOITransaction.POITransactionID.TransactionID`	String	Transaction ID, from POI, of the original payment that was cancelled. Used for financial linking.
`POIData.POITransactionID.TransactionID`	String	Transaction ID of the Reversal operation itself provided by POI.
`PaymentReceipt`	Array	Receipt Content: Contains the text necessary for printing both the Cashier and Customer reversal receipts.

Reversal Response example JSON

{
  "MessageHeader": {
    "MessageCategory": "Reversal",
    "MessageClass": "Service",
    "MessageType": "Response",
    "POIID": "POS01",
    "ProtocolVersion": "3.0",
    "SaleID": "POS001",
    "ServiceID": "823"
  },
  "ReversalResponse": {
    "CustomerOrder": {},
    "MarketpayPaymentExtensions": {
      "AcquirerId": "40105611508",
      "ApplicationID": "A0000000041010",
      "Currency": "EUR",
      "OriginalTransactionType": "Debit",
      "PaymentInstrumentData": {
        "CardData": {
          "PaymentBrand": "2",
          "SensitiveCardData": {
            "PAN": "XXXXXXXXXXXX1034",
            "CardSeqNumb": "01",
            "ExpiryDate": "2512"
          }
        },
        "PaymentInstrumentType": "Card"
      }
    },
    "OriginalPOITransaction": {
      "POITransactionID": {
        "TimeStamp": "2025-11-28T14:12:59.6+01:00",
        "TransactionID": "9990"
      },
      "SaleID": "POS001"
    },
    "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": "9 RUE DU 4 SEPTEMBRE"
            },
            {
              "EndOfLineFlag": true,
              "Text": "75002 PARIS"
            },
            {
              "EndOfLineFlag": true,
              "Text": "MASTERCARD"
            },
            {
              "EndOfLineFlag": true,
              "Text": "BEZSTYKOWY"
            },
            {
              "EndOfLineFlag": true,
              "Text": "XXXXXXXXXXXX1034"
            },
            {
              "EndOfLineFlag": true,
              "Text": "AID: A0000000041010"
            },
            {
              "EndOfLineFlag": true,
              "Text": "29-11-2025 00:56"
            },
            {
              "EndOfLineFlag": true,
              "Text": "NUMER REFERENCYJNY: 9"
            },
            {
              "EndOfLineFlag": true,
              "Text": "TRANSACTION"
            },
            {
              "EndOfLineFlag": true,
              "Text": "TYPE: ANULOWANIE"
            },
            {
              "EndOfLineFlag": true,
              "Text": "KWOTA:NOK 103,30"
            },
            {
              "EndOfLineFlag": true,
              "Text": "Zaakceptowana"
            }
          ]
        },
        "RequiredSignatureFlag": false
      },
      {
        "DocumentQualifier": "CustomerReceipt",
        "OutputContent": {
          "OutputFormat": "Text",
          "OutputText": [
            {
              "EndOfLineFlag": true,
              "Text": "POTWIERDZENIE DLA"
            },
            {
              "EndOfLineFlag": true,
              "Text": "UŻYTKOWNIKA KARTY"
            },
            {
              "EndOfLineFlag": true,
              "Text": "BRAK PARAGONU DO"
            },
            {
              "EndOfLineFlag": true,
              "Text": "ZAKUPU"
            },
            {
              "EndOfLineFlag": true,
              "Text": "MARKET PAY PRECERT"
            },
            {
              "EndOfLineFlag": true,
              "Text": "9 RUE DU 4 SEPTEMBRE"
            },
            {
              "EndOfLineFlag": true,
              "Text": "75002 PARIS"
            },
            {
              "EndOfLineFlag": true,
              "Text": "MASTERCARD"
            },
            {
              "EndOfLineFlag": true,
              "Text": "BEZSTYKOWY"
            },
            {
              "EndOfLineFlag": true,
              "Text": "XXXXXXXXXXXX1034"
            },
            {
              "EndOfLineFlag": true,
              "Text": "AID: A0000000041010"
            },
            {
              "EndOfLineFlag": true,
              "Text": "29-11-2025 00:56"
            },
            {
              "EndOfLineFlag": true,
              "Text": "NUMER REFERENCYJNY: 9"
            },
            {
              "EndOfLineFlag": true,
              "Text": "TRANSACTION"
            },
            {
              "EndOfLineFlag": true,
              "Text": "TYPE: ANULOWANIE"
            },
            {
              "EndOfLineFlag": true,
              "Text": "KWOTA:NOK 103,30"
            },
            {
              "EndOfLineFlag": true,
              "Text": "Zaakceptowana"
            }
          ]
        },
        "RequiredSignatureFlag": false
      }
    ],
    "POIData": {
      "POITransactionID": {
        "TimeStamp": "2025-11-28T14:12:59.6+01:00",
        "TransactionID": "9991"
      }
    },
    "Response": {
      "Result": "Success"
    },
    "ReversedAmount": "11.99",
    "SaleData": {
      "OperatorID": "456",
      "SaleReferenceID": "19",
      "SaleTransactionID": {
        "TimeStamp": "2025-11-28T14:12:59.6+01:00",
        "TransactionID": "9991"
      },
      "SponsoredMerchant": {
        "Address": "9 RUE DU 4 SEPTEMBRE\n75002 PARIS",
        "CommonName": "MARKET PAY PRECERT",
        "CountryCode": "NO",
        "MerchantCategoryCode": "4411",
        "RegisteredIdentifier": "198703093982001"
      }
    }
  }
}

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

Reversal Response example XML

<SaleToPOIResponse>
   <MessageHeader MessageCategory="Reversal" MessageClass="Service" MessageType="Response" POIID="456" ProtocolVersion="3.1" SaleID="ECR001" ServiceID="3913"/>
   <ReversalResponse>
      <PaymentReceipt DocumentQualifier="CashierReceipt" RequiredSignatureFlag="false">
         <OutputContent OutputFormat="Text">
            <OutputText EndOfLineFlag="true">MERCHANT RECEIPT</OutputText>
            <OutputText EndOfLineFlag="true">--------------------------------</OutputText>
            <OutputText EndOfLineFlag="true">Candy Shop</OutputText>
            <OutputText EndOfLineFlag="true">75002 Paris</OutputText>
            <OutputText EndOfLineFlag="true">REFERENCE: 2</OutputText>
            <OutputText EndOfLineFlag="true">TID: 30010910</OutputText>
            <OutputText EndOfLineFlag="true">DEVICE NAME: 1760317010</OutputText>
            <OutputText EndOfLineFlag="true">MERCHANT: 000000001231344</OutputText>
            <OutputText EndOfLineFlag="true">PAN: XXXXXXXXXXXX7462</OutputText>
            <OutputText EndOfLineFlag="true">AID: A0000000041010</OutputText>
            <OutputText EndOfLineFlag="true">CARD TYPE: MASTERCARD</OutputText>
            <OutputText EndOfLineFlag="true">CANCELLATION</OutputText>
            <OutputText EndOfLineFlag="true">CONTACTLESS</OutputText>
            <OutputText EndOfLineFlag="true">AMOUNT:€ 10,02</OutputText>
            <OutputText EndOfLineFlag="true">Approved</OutputText>
            <OutputText EndOfLineFlag="true">213462</OutputText>
            <OutputText EndOfLineFlag="true">PLEASE RETAIN FOR YOUR RECORDS</OutputText>
         </OutputContent>
      </PaymentReceipt>
      <PaymentReceipt DocumentQualifier="CustomerReceipt" RequiredSignatureFlag="false">
         <OutputContent OutputFormat="Text">
            <OutputText EndOfLineFlag="true">CARDHOLDER RECEIPT</OutputText>
            <OutputText EndOfLineFlag="true">--------------------------------</OutputText>
            <OutputText EndOfLineFlag="true">Candy Shop</OutputText>
            <OutputText EndOfLineFlag="true">75002 Paris</OutputText>
            <OutputText EndOfLineFlag="true">REFERENCE: 2</OutputText>
            <OutputText EndOfLineFlag="true">TID: 30010910</OutputText>
            <OutputText EndOfLineFlag="true">DEVICE NAME: 1760317010</OutputText>
            <OutputText EndOfLineFlag="true">MERCHANT: 000000001231344</OutputText>
            <OutputText EndOfLineFlag="true">PAN: XXXXXXXXXXXX7462</OutputText>
            <OutputText EndOfLineFlag="true">AID: A0000000041010</OutputText>
            <OutputText EndOfLineFlag="true">CARD TYPE: MASTERCARD</OutputText>
            <OutputText EndOfLineFlag="true">CANCELLATION</OutputText>
            <OutputText EndOfLineFlag="true">CONTACTLESS</OutputText>
            <OutputText EndOfLineFlag="true">AMOUNT:€ 10,02</OutputText>
            <OutputText EndOfLineFlag="true">Approved</OutputText>
            <OutputText EndOfLineFlag="true">213462</OutputText>
            <OutputText EndOfLineFlag="true">PLEASE RETAIN FOR YOUR RECORDS</OutputText>
         </OutputContent>
      </PaymentReceipt>
      <POIData>
         <POITransactionID TimeStamp="2025-03-29T13:40:44.374" TransactionID="2"/>
      </POIData>
      <Response Result="Success"/>
   </ReversalResponse>
</SaleToPOIResponse>

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

Reversal not found

A ReversalResponse.Response with an ErrorCondition of NotAllowed indicates that we were not able to find the transaction with the SaleID and ServiceID you specified.

When the transaction is not found, this means that either:

The POIID, SaleID or ServiceID you specified in the transaction status request are incorrect. Check that you provided the POIID, SaleID, and ServiceID from the original transaction in the TransactionStatusRequest.MessageReference.
POI did not receive the original transaction request. The cause can be a dropped internet connection or an unexpected power loss. You can retry the original transaction.

The example response below indicates that this transaction was not found.

Reversal not found - Example

{
  "MessageHeader": {
    "MessageCategory": "Reversal",
    "MessageClass": "Service",
    "MessageType": "Response",
    "POIID": "POS01",
    "ProtocolVersion": "3.1",
    "SaleID": "POS_01",
    "ServiceID": "823"
  },
  "ReversalResponse": {
    "PaymentReceipt": [],
    "Response": {
      "AdditionalResponse": "Transaction not found in database",
      "ErrorCondition": "NotAllowed",
      "Result": "Failure"
    },
    "SaleData": {
      "OperatorID": "456",
      "SaleReferenceID": "19",
      "SaleTransactionID": {
        "TimeStamp": "2025-11-28T14:12:59.6+01:00",
        "TransactionID": "9991"
      }
    }
  }
}

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

Error handling

If the POI application detects a parsing error while handling an incoming message, an EventNotification will be returned, as shown in the example below.

Event notification example

If parsing error will happen during POI application handles incoming message, EventNotification will be returned:

{
  "MessageHeader": {
    "MessageCategory": "EventNotification",
    "MessageClass": "Service",
    "MessageType": "Response",
    "POIID": "POI01",
    "ProtocolVersion": "3.0",
    "SaleID": "POS001",
    "ServiceID": "823"
  },
  "EventNotification": {
    "TimeStamp": "2025-11-28T14:12:59.6+01:00",
    "EventToNotify": "Reject"
  }
}

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

6. Refund

A Refund Request is handled by sending a standard Payment Request, but with the specific transaction type set to "Refund". You will find below a limited information below, refer to the previous Payment Request section for more details.

A. Refund Request

Header

The standard SaleToPOIRequest.MessageHeader object, with MessageClass set to Service and MessageCategory set to Payment.

Body

To successfully initiate a payment, the PaymentRequest body must contain data defining the sale context and the PaymentType set as Refund.

This table details the fields required within the PaymentRequest object.

Field Name	Required	Type	Description
`PaymentTransaction.AmountsReq.RequestedAmount`	Yes	Number	Total monetary value of the transaction requested.
`PaymentTransaction.AmountsReq.Currency`	Yes	String	Currency of the requested amount (e.g., EUR, NOK...) in ISO 4217.
`SaleData.SaleTransactionID.TimeStamp`	Yes	String	Date and time of the request in UTC format.
`SaleData.SaleTransactionID.TransactionID`	Yes	String	The unique transaction reference ID from the POS. Currently limited to 35 characters as per ISO 20022 standard.
`PaymentData.PaymentType`	No	Enum	`Refund`

Payment Request example JSON

{
  "MessageHeader": {
    "MessageCategory": "Payment",
    "MessageClass": "Service",
    "MessageType": "Request",
    "POIID": "POI_01",
    "ProtocolVersion": "3.1",
    "SaleID": "POS_01",
    "ServiceID": "823"
  },
  "PaymentRequest": {
    "PaymentData": {
      "PaymentType": "Refund"
    },
    "PaymentTransaction": {
      "AmountsReq": {
        "Currency": "EUR",
        "RequestedAmount": "11.99"
      }
    },
    "SaleData": {
      "OperatorID": "Cashier_01",
      "OperatorLanguage": "EN",
      "SaleTransactionID": {
        "TimeStamp": "2025-11-28T14:12:59.6+01:00",
        "TransactionID": "9991"
      }
    }
  }
}

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

Payment Request example XML

<SaleToPOIResponse>
   <MessageHeader MessageCategory="Payment" MessageClass="Service" MessageType="Response" POIID="456" ProtocolVersion="3.1" SaleID="ECR001" ServiceID="3930"/>
   <PaymentResponse>
      <MarketpayPaymentExtensions ApplicationID="A0000000041010" BankID="513640" PANSequenceNumber="01"/>
      <PaymentReceipt DocumentQualifier="CashierReceipt" RequiredSignatureFlag="false">
         <OutputContent OutputFormat="Text">
            <OutputText EndOfLineFlag="true">MERCHANT RECEIPT</OutputText>
            <OutputText EndOfLineFlag="true">--------------------------------</OutputText>
            <OutputText EndOfLineFlag="true">MARKET PAY PRECERT</OutputText>
            <OutputText EndOfLineFlag="true">9 RUE DU 4 SEPTEMBRE</OutputText>
            <OutputText EndOfLineFlag="true">75002 PARIS</OutputText>
            <OutputText EndOfLineFlag="true">REFERENCE: 19</OutputText>
            <OutputText EndOfLineFlag="true">TID: 00022302</OutputText>
            <OutputText EndOfLineFlag="true">DEVICE NAME: 1760317010</OutputText>
            <OutputText EndOfLineFlag="true">MERCHANT: 000000001999065</OutputText>
            <OutputText EndOfLineFlag="true">PAN: XXXXXXXXXXXX7462 01</OutputText>
            <OutputText EndOfLineFlag="true">CARD TYPE: MASTERCARD</OutputText>
            <OutputText EndOfLineFlag="true">REFUND</OutputText>
            <OutputText EndOfLineFlag="true">CONTACTLESS</OutputText>
            <OutputText EndOfLineFlag="true">AMOUNT:€ 10,00</OutputText>
            <OutputText EndOfLineFlag="true">Approved</OutputText>
            <OutputText EndOfLineFlag="true">213462</OutputText>
            <OutputText EndOfLineFlag="true">TIME: 29-03-2025 14:00</OutputText>
            <OutputText EndOfLineFlag="true">PLEASE SIGN BELOW</OutputText>
            <OutputText EndOfLineFlag="true"> </OutputText>
            <OutputText EndOfLineFlag="true"> </OutputText>
            <OutputText EndOfLineFlag="true"> </OutputText>
            <OutputText EndOfLineFlag="true">--------------------------------</OutputText>
            <OutputText EndOfLineFlag="true">SIGNATURE REQUIRED</OutputText>
            <OutputText EndOfLineFlag="true">PLEASE RETAIN FOR YOUR RECORDS</OutputText>
         </OutputContent>
      </PaymentReceipt>
      <PaymentReceipt DocumentQualifier="CustomerReceipt" RequiredSignatureFlag="false">
         <OutputContent OutputFormat="Text">
            <OutputText EndOfLineFlag="true">RECU PORTEUR</OutputText>
            <OutputText EndOfLineFlag="true">--------------------------------</OutputText>
            <OutputText EndOfLineFlag="true">MARKET PAY PRECERT</OutputText>
            <OutputText EndOfLineFlag="true">9 RUE DU 4 SEPTEMBRE</OutputText>
            <OutputText EndOfLineFlag="true">75002 PARIS</OutputText>
            <OutputText EndOfLineFlag="true">RÉFÉRENCE: 19</OutputText>
            <OutputText EndOfLineFlag="true">TID: 00022302</OutputText>
            <OutputText EndOfLineFlag="true">NOM DE L&apos;APPAREIL: 1760317010</OutputText>
            <OutputText EndOfLineFlag="true">MARCHAND: 000000001999065</OutputText>
            <OutputText EndOfLineFlag="true">PAN: XXXXXXXXXXXX7462 01</OutputText>
            <OutputText EndOfLineFlag="true">TYPE DE CARTE: MASTERCARD</OutputText>
            <OutputText EndOfLineFlag="true">REMBOURSEMENT</OutputText>
            <OutputText EndOfLineFlag="true">SANS CONTACT</OutputText>
            <OutputText EndOfLineFlag="true">MONTANT:€ 10,00</OutputText>
            <OutputText EndOfLineFlag="true">Approuvé</OutputText>
            <OutputText EndOfLineFlag="true">213462</OutputText>
            <OutputText EndOfLineFlag="true">TIME: 29-03-2025 14:00</OutputText>
            <OutputText EndOfLineFlag="true">VEUILLEZ CONSERVER POUR VOS</OutputText>
            <OutputText EndOfLineFlag="true">DOSSIERS</OutputText>
         </OutputContent>
      </PaymentReceipt>
      <PaymentResult MerchantOverrideFlag="false" OnlineFlag="true" PaymentType="Refund">
         <AmountsResp AuthorizedAmount="10.00" Currency="EUR"/>
         <PaymentAcquirerData AcquirerID="40105611508" AcquirerPOIID="00022302" MerchantID="000000001999065">
            <ApprovalCode>213462</ApprovalCode>
         </PaymentAcquirerData>
         <PaymentInstrumentData PaymentInstrumentType="Card">
            <CardData EntryMode="Contactless" MaskedPAN="XXXXXXXXXXXX7462" PaymentBrand="MASTERCARD"/>
         </PaymentInstrumentData>
      </PaymentResult>
      <POIData>
         <POITransactionID TimeStamp="2025-03-29T14:00:46.391" TransactionID="19"/>
      </POIData>
      <Response Result="Success">
         <AdditionalResponse>000</AdditionalResponse>
      </Response>
      <SaleData OperatorID="666">
         <SaleTransactionID TimeStamp="2025-03-29T13:00:47Z" TransactionID="123"/>
      </SaleData>
   </PaymentResponse>
</SaleToPOIResponse>

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

7. Logout

You should trigger a Logout Request when a terminal session is complete and before the POS system closes, switches users, or initiates a long period of inactivity. During a session, you can do multiple operations (payments, loyalty check...). A session is usually opened for a full day, or for a cashier' shift.

The primary function of the Logout Request endpoint is session termination, which is mandatory to maintain system security and stability.

A. Logout request

Header

The standard SaleToPOIRequest.MessageHeader object, with MessageClass set to Service and MessageCategory set to Logout.

Body

The LogoutRequest body is sent as an empty object ({}) to signal the intention to terminate the current session.

Logout request example JSON

This section contains the detailed JSON payload needed for the logout request:

{
  "MessageHeader": {
    "MessageClass": "Service",
    "MessageCategory": "Logout",
    "MessageType": "Request",
    "ServiceID": "825",
    "SaleID": "POS_01",
    "POIID": "POI_01"
  },
  "LogoutRequest": {}
}

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

Logout request example XML

This section contains the detailed XML payload needed for the logout request:

<?xml version="1.0" encoding="UTF-8"?>
<SaleToPOIRequest xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
	<MessageHeader MessageClass="Service" MessageCategory="Logout" MessageType="Request" ServiceID="9346" SaleID="ECR001" POIID="456"></MessageHeader>
	<LogoutRequest></LogoutRequest>
</SaleToPOIRequest>

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

B. Logout Response

The POI returns a final response confirming the session is closed.

Expected Result: A response with Response.Result: "Success".
Failure: If a parsing error occurs, an EventNotification with EventToNotify: "Reject" is returned.

The MessageHeader you receive in the response echoes the values you provided in the request. The only exception is the MessageType, which is Response.

Body

The Logout Response body confirms the successful or failed termination of the session by containing a mandatory Response object which specifies the final Result (e.g., "Success" or "Failure").

Logout response example JSON

<SaleToPOIResponse>
   <LogoutResponse>
      <Response Result="Success"/>
   </LogoutResponse>
   <MessageHeader MessageCategory="Logout" MessageClass="Service" MessageType="Response" POIID="456" ProtocolVersion="3.1" SaleID="ECR001" ServiceID="9346"/>
</SaleToPOIResponse>

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

Logout response example JSON

{
  "MessageHeader": {
    "MessageCategory": "Logout",
    "MessageClass": "Service",
    "MessageType": "Response",
    "POIID": "POI_01",
    "ProtocolVersion": "3.1",
    "SaleID": "POS_01",
    "ServiceID": "825"
  },
  "LogoutResponse": {
    "Response": {
      "Result": "Success"
    }
  }
}

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

Event notification

An Event Notification in response to a Logout Request signals that the Payment Terminal (POI) failed to process the request due to a fundamental message error, rather than a normal business failure.

The most common cause is a parsing error (e.g., incorrect JSON/XML structure, missing mandatory field in the header, or corrupted encoding). This typically results in an EventToNotify value of "Reject". The POI is unable to validate the request against its schema, so it returns the EventNotification to notify the POS of the structural error.

Event notification example

If parsing error will happen during POI application handles incoming message, EventNotification will be returned:

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

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