Payment request

The Process transaction function allows the ECR to trigger different transaction types on the terminal:

Transaction Modes

Direct

Dual

Description: this process is done in one step: when the ECR triggers a purchase, the terminal sends directly payment request to the server.

This is the most standard use case of implementation.

Description: this process is done in two steps;

  • Step 1: ECR triggers a purchase; Once card has been presented, card information and details will be sent to back to ECR

  • Step 2: Based on received info, ECR can send transaction online, change the amount or abort the transaction;

This process is used for some use cases to retrieve loyalty information, apply discounts or identify specific cards (e.g. gift card, meal vouchers…).

Perform SaleToPOIRequest

Below you will find a description of the SaleToPOIRequest message, which is used to initiate a payment transaction from an Electronic Cash Register system.

Request MessageHeader

Elements

Required

Description

ProtocolVersion

Yes

3.1

MessageClass

Yes

Service

MessageCategory

Yes

Payment

MessageType

Yes

Request

ServiceID

Yes

Your unique ID for this request, consisting of 1-10 alphanumeric characters. Must be unique within the last 48 hours for the terminal (POIID) being used.

SaleID

Yes

identifier of the ECR initiating the request (e.g., ECR001")

POIID

Yes

identifier of the Terminal receiving the request (e.g., 456)

Request body

Elements

Attributes

Required

Description

PaymentRequest

SaleData

OperatorID

Yes

identifier for the operator performing the transaction for the ECR

SaleTransactionID

TransactionID

Yes

unique reference to identify a payment. In the Hub, this will show as “Store transaction ID” in transaction details

TimeStamp

Yes

date and time of the request in UTC ISO format, e.g., 2025-03-03T10:39:59Z

PaymentTransaction

AmountsReq

Currency

Yes

transaction currency code based on ISO-4217 (ie.g., EUR for Euros)

RequestedAmount

Yes

transaction amount, e.g., 12.34

Example of SaleToPOIRequest

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

Receive SaleToPOIResponse

Example of SaleToPOIResponse for a successful transaction

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

Example of SaleToPOIResponse for a declined transaction

To simulate a generic decline, enter 9100,00 as an amount on our simulator.

<SaleToPOIResponse>
   <MessageHeader MessageCategory="Payment" MessageClass="Service" MessageType="Response" POIID="456" ProtocolVersion="3.1" SaleID="ECR001" ServiceID="3921"/>
   <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: 12</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 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:€ 9 100,00</OutputText>
            <OutputText EndOfLineFlag="true">Declined</OutputText>
            <OutputText EndOfLineFlag="true">TIME: 13:49:30</OutputText>
            <OutputText EndOfLineFlag="true">DATE: 29.03.2025</OutputText>
            <OutputText EndOfLineFlag="true">AUTHENTICATION METHOD: ONLINE</OutputText>
            <OutputText EndOfLineFlag="true">PIN</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: 12</OutputText>
            <OutputText EndOfLineFlag="true">TID: 30010910</OutputText>
            <OutputText EndOfLineFlag="true">NOM DE L&apos;APPAREIL: 1760317010</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:€ 9 100,00</OutputText>
            <OutputText EndOfLineFlag="true">Transaction refusee</OutputText>
            <OutputText EndOfLineFlag="true">TIME: 13:49:30</OutputText>
            <OutputText EndOfLineFlag="true">DATE: 29.03.2025</OutputText>
            <OutputText EndOfLineFlag="true">METHODE D&apos;AUTHENTIFICATION: PIN</OutputText>
            <OutputText EndOfLineFlag="true">EN LIGNE</OutputText>
            <OutputText EndOfLineFlag="true">VEUILLEZ CONSERVER POUR VOS</OutputText>
            <OutputText EndOfLineFlag="true">DOSSIERS</OutputText>
         </OutputContent>
      </PaymentReceipt>
      <PaymentResult OnlineFlag="true" PaymentType="Normal">
         <AmountsResp AuthorizedAmount="9100.00" Currency="EUR"/>
         <PaymentAcquirerData AcquirerID="40105611508" AcquirerPOIID="30010910" MerchantID="000000001231344">
            <ApprovalCode></ApprovalCode>
         </PaymentAcquirerData>
         <PaymentInstrumentData PaymentInstrumentType="Card">
            <CardData EntryMode="Contactless" MaskedPAN="XXXXXXXXXXXX7462" PaymentBrand="MASTERCARD"/>
         </PaymentInstrumentData>
      </PaymentResult>
      <POIData>
         <POITransactionID TimeStamp="2025-03-29T13:49:35.738" TransactionID="12"/>
      </POIData>
      <Response ErrorCondition="Refusal" Result="Failure">
         <AdditionalResponse>100</AdditionalResponse>
      </Response>
      <SaleData OperatorID="666">
         <SaleTransactionID TimeStamp="2025-03-29T12:49:34Z" TransactionID="123"/>
      </SaleData>
   </PaymentResponse>
</SaleToPOIResponse>

Example of SaleToPOIResponse for a Partially approved Authorization

<SaleToPOIResponse>
   <MessageHeader MessageCategory="Payment" MessageClass="Service" MessageType="Response" POIID="456" ProtocolVersion="3.1" SaleID="ECR001" ServiceID="3925"/>
   <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: 14</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">AID: A0000000041010</OutputText>
            <OutputText EndOfLineFlag="true">CARD TYPE: MASTERCARD</OutputText>
            <OutputText EndOfLineFlag="true">PAYMENT</OutputText>
            <OutputText EndOfLineFlag="true">CONTACTLESS</OutputText>
            <OutputText EndOfLineFlag="true">AMOUNT:€ 9,00</OutputText>
            <OutputText EndOfLineFlag="true">Approved</OutputText>
            <OutputText EndOfLineFlag="true">000000</OutputText>
            <OutputText EndOfLineFlag="true">TIME: 13:54:23</OutputText>
            <OutputText EndOfLineFlag="true">DATE: 29.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">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: 14</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">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:€ 9,00</OutputText>
            <OutputText EndOfLineFlag="true">Approuvé</OutputText>
            <OutputText EndOfLineFlag="true">000000</OutputText>
            <OutputText EndOfLineFlag="true">TIME: 13:54:23</OutputText>
            <OutputText EndOfLineFlag="true">DATE: 29.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="9.00" Currency="EUR"/>
         <PaymentAcquirerData AcquirerID="40105611508" AcquirerPOIID="00022302" MerchantID="000000001999065">
            <ApprovalCode></ApprovalCode>
         </PaymentAcquirerData>
         <PaymentInstrumentData PaymentInstrumentType="Card">
            <CardData EntryMode="Contactless" MaskedPAN="XXXXXXXXXXXX7462" PaymentBrand="MASTERCARD"/>
         </PaymentInstrumentData>
      </PaymentResult>
      <POIData>
         <POITransactionID TimeStamp="2025-03-29T13:54:28.478" TransactionID="14"/>
      </POIData>
      <Response Result="Partial">
         <AdditionalResponse>000</AdditionalResponse>
      </Response>
      <SaleData OperatorID="666">
         <SaleTransactionID TimeStamp="2025-03-29T12:54:27Z" TransactionID="123"/>
      </SaleData>
   </PaymentResponse>
</SaleToPOIResponse>