Standard POS integration

The basic Payment flow details the necessary messages your POS should manage to perform efficiently:

Login: starts an operational session with the terminal, allowing to process transactions from the POS.
Payment: sale transaction, using a card or other instrument to complete a purchase at the Point of Sale.
Abort: immediately stops and cancels an in-progress transaction before authorization was started.
TransactionStatus: check the final outcome or the last known processing state of a previous transaction, typically trigerred after lost communication between POS and POI.
Reversal: undo a recently approved transaction by crediting the funds back to the customer's account or card before transaction has been financially settled.
Refund: return funds to a customer following a sale that has already been settled, typically due to a product return.
Logout: This request closes the active operational session on the terminal, concluding the cashier's shift or usage period.

With these 7 messages, your POS will cover the standard integration scope. You will find the details of these messages below. We offer additional features which may also interest you to bring additional value or security to your customers.

1. Login

The Login Request is the mandatory first step in initiating communication with the Payment Terminal (POI) and establishing an operational session.

This operation must be triggered upon application startup or whenever the cashier logs into the Point of Sale (POS) system. Its primary purpose is to convey system identity (POS software details) and operational context (Operator ID, Date/Time) to the POI, ensuring all subsequent transactions are correctly logged and authorized.

Click to View: Login Request/Response Sequence Diagram

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

A. Login Request

Header

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

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
`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 your POS application sending the request (e.g., `"POS Simulator"`).
`SaleSoftware.ProviderIdentification`	String	Yes	Identification of your software provider (e.g., `"POS Provider ID"`).
`SaleSoftware.SoftwareVersion`	String	Yes	The version number of your 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

The Login Response confirms that the operational session has been successfully established, providing the POS system with vital status and software information about the Payment Terminal (POI).

Two different results can be expected:

Success: 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

This table details the fields required within the LoginResponse object, which identifies the POS software and the operator for the new session. You will find an example of request after the table

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

When a Login Request fails, the Payment Terminal (POI) responds with a specialized EventNotification message, signaling that the message was rejected or could not be processed. This is typically the POI's method of communicating an unrecoverable structural or parsing error immediately to the Point of Sale (POS).

The MessageHeader you receive for an EventNotification echoes the values you provided in the request. The two exceptions are the MessageCategory which is EventNotification and MessageType, which is 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.

These occur when the POI cannot be reached or the session parameters are incorrect.

Invalid Message Format: The LoginRequest is missing required fields (e.g., DateTime, SaleSoftware), or the structure is corrupted.
POI Unreachable: The terminal is powered off, disconnected from the network, or its IP address is unknown/incorrect.
Session Conflict: The terminal is already logged in with another SaleID (POS ID), or the POI application is busy.

When POI starts, it can take some time before it is fully operating and ready to receive a message. If you notice such case, we advise you to add a delay and a retry mechanism with the login request.

2. Payment

The Payment Request is the core transaction message used to initiate a wide range of financial operations on the payment terminal (POI). It allows the Point of Sale (POS) to start operations such as a standard payment, a card acquisition completion, a refund, a pre-authorization, or a pre-authorization completion. Here we will focus on a standard payment. Other types are detailed in dedicated chapters.

A. Payment 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 financial details, specifically the transaction amount and the unique identifier for the transaction.

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 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

A payment transaction is running asynchronously, the Payment Terminal (POI) uses Display Request messages to inform the Point of Sale (POS) about the customer's required interaction or the current terminal state. The POS can interpret this information to update the customer display or cashier interface and then continue waiting for the final result.

Header

The MessageHeader you receive in the response echoes the values you provided in the request. The exceptions are the MessageCategory which is Display and the MessageType, which is 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

The Payment Response is the final, definitive message delivered by the terminal (POI) to the POS, confirming the outcome of a financial request initiated by the POS. It marks the successful end of the payment flow and provides all necessary data for the POS to conclude the sale.

Expected results are communicated via the primary Response.Result field:

Success: Funds were successfully captured, reserved, or refunded. The response contains all transaction details and receipts.
Failure: The operation could not be completed (e.g., card declined, transaction timeout). The response includes diagnostic information via AdditionalResponse and ErrorCondition (if present)

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 PaymentResponse body provides a comprehensive record of the transaction. The POS must interpret the response to know the transaction result and print receipts. This table details the expected fields within the PaymentResponse object.

Field Name	Type	Key Information & POS Action
`PaymentResponse.Response.Result`	Enum	Transaction Outcome: Confirms the final status of the operation (`Success`, `Failure` or `Partial`). Must be checked first.
`PaymentResponse.PaymentResult.OnlineFlag`	Boolean	Exact amount authorized (key information for `Partial` results)
`PaymentResponse.PaymentResult.PaymentAcquirerData.ApprovalCode`	String	Authorization code assigned during payment processing
`PaymentResponse.PaymentResult.PaymentAcquirerData.ApprovalCode`	String	Authorization code assigned during payment processing
`PaymentResponse.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...).
`PaymentResponse.PaymentResult.PaymentInstrumentData.PaymentInstrumentType`	String	Type of payment instrument: `Card`, `Mobile`, `StoredValue` ...
`PaymentResponse.PaymentResult.PaymentInstrumentData.CardData.EntryMode`	Enum	Entry mode of the payment instrument information: `ICC`, `Contactless`, `Scanned` ...
`PaymentResponse.PaymentResult.PaymentInstrumentData.CardData.PaymentBrand`	String	Card Type: Identifies the payment brand (e.g., VISA, MASTERCARD). Used for routing and receipt display.
`PaymentResponse.PaymentReceipt`	Array	Contains the text lines for the `CashierReceipt` and `CustomerReceipt`.
`PaymentResponse.PaymentReceipt.RequiredSignatureFlag`	Boolean	indicates whether the transaction requires customer's signature on the printed receipt.
`PaymentResponse.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

When a payment operation fails, the Point of Sale (POS) must categorize the error to determine the appropriate recovery action and prevent financial discrepancies.

Communication Conflict Error

This failure occurs before the Payment Terminal (POI) can even start processing the transaction logic. Payment Terminal (POI) is busy with another operation.

Decline transaction

The POI delivers a final response message containing the definitive outcome field set to Result: "Failure".

The card was declined by the issuer, a payment host was unreachable, or a host-specific error prevented authorization. The response body contains diagnostic fields like AdditionalResponse and, potentially, ErrorCondition explaining the reason for the decline.

Event Notification

This signals that the POI could not understand the structure of the message sent by the POS. The POI sends an EventNotification message with the EventToNotify field set to Reject. The payment request message was syntactically incorrect, missing a required field, or corrupted during transmission.

POS needs to inspect the payload sent to the POI, correct the structural error (formatting, required fields...), and then re-attempt the 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

You can then send an Abort Request to interrupt an in-progress transaction. When this request is received before the transaction is was sent in authorization, the payment is cancelled. If customer inserted his card but did not validate PIN code yet, operation can still be aborted.

For complex transactions that begin with a Card Acquisition (a two-step payment), the standard AbortRequest is bypassed. Refer to Card Acquisition documentation for more information.

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 ReversalRequest 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 : CustCancel, MerchantCancel, Malfunction, Unable2Compl.
`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.

Standard POS integration

1. Login

A. Login Request

Header

Body

B. Login Response

Body

EventNotification

2. Payment

A. Payment Request

Header

Body

B. Intermediate Status

Header

Body

C. Payment Response

Body

D. Error handling

Communication Conflict Error

Decline transaction

Event Notification

3. Abort

A. Abort Request

Header

Body

B. Abort Reponse

C. Error handling

Cancel from the terminal

Handling failed cancel requests

4. Transaction Status

A. Transaction Status Request

Header

Body

B. Transaction Status Responses

Transaction not found

Error handling

5. Reversal

A. Reversal Request

Header

Body

Reversal when you do not know the POI TransactionID

B. Reversal Response

Header

Body

Reversal not found

Error handling

6. Refund

A. Refund Request

Header

Body

7. Logout

A. Logout request

Header

Body

B. Logout Response

Body

Event notification

Was this article helpful?