Handle progress events

Progress events are sent from the POI (also known as Pin Entry Device (PED)) to the Sale system (also known as Point of Sale or Cash Register). Progress events do not require any action by the cash register. They inform the staff of what is happening on the POI.

There are two types of messages, display messages and event notifications.

  • Display messages: messages and events sent during services (such as payment) that include transaction status information. Will be sent to the IP that started the transaction (in a local setup) and at endpoints configured by the POS Support Team
  • Event messages: sent to the Sale System outside of the payment flow, for example, going down for maintenance, available after maintenance, etc.

To receive progress events, the Sale System or Sale Server must run a HTTP server. Contact the Support Team to configure these end-points (IP or URL).

Progress events are returned in the ReferenceID, as an event value (possible values are listed in the Progress events section)ReferenceID is form encoded and can contain multiple values, including event, TransactionID (POI ID / tender reference) and timestamp.

The SaleID and ServiceID in the MessageHeader should be unique. SaleID and ServiceID combinations are rejected if used recently, within 48 hours.

No content is expected in the HTTP response body for these messages. If the response does not arrive, we do not retry.

Progress events

Name Description
TENDER_CREATED

The tender was successfully created.

WAIT_FOR_APP_SELECTION

The terminal is waiting for the shopper to select a payment application.

ASK_SIGNATURE The PED has requested a signature from the shopper.
WAIT_FOR_PIN

A PIN is requested at the terminal.

ASK_GRATUITY

The terminal is waiting for a possible gratuity.

ASK_DCC

The terminal is checking if the customer requires dynamic currency conversion.

PROVIDE_CARD_DETAILS The terminal is waiting for card details.
PRINT_RECEIPT

The terminal is printing the receipt.

APPLICATION_SELECTED

The customer has selected their preferred payment application.

CARD_INSERTED

A card was inserted.

CARD_REMOVED  A card was removed.
CARD_DETAILS_PROVIDED
The card details have been entered.

EventToNotify types

Name
Description
Shutdown

The POI Terminal or the POI System is shutting down.

BeginMaintenance Beginning POI maintenance.
EndMaintenance Ending POI maintenance.
OutOfOrder

The POI Terminal or the POI System is currently out of order.

Initialised The POI Terminal or the POI System is now ready to work.
Reject

A message request is rejected. An error explanation and the message in error have to be put in the EventDetails data element.

Examples

Display Events

PROVIDE_CARD_DETAILS

{  
   "SaleToPOIRequest":{  
      "DisplayRequest":{  
         "DisplayOutput":[  
            {  
               "OutputContent":{  
                  "OutputFormat":"MessageRef",
                  "PredefinedContent":{  
                     "ReferenceID":"event=PROVIDE_CARD_DETAILS"
                  }
               },
               "InfoQualify":"Status",
               "Device":"CashierDisplay"
            }
         ]
      },
      "MessageHeader":{  
         "SaleID":"DefaultSaleID",
         "ProtocolVersion":"3.0",
         "MessageType":"Request",
         "POIID":"MX925-261078152",
         "ServiceID":"130460745",
         "MessageClass":"Device",
         "MessageCategory":"Display",
         "DeviceID":"1502960677"
      }
   }
}

TENDER_CREATED

{  
   "SaleToPOIRequest":{  
      "DisplayRequest":{  
         "DisplayOutput":[  
            {  
               "OutputContent":{  
                  "OutputFormat":"MessageRef",
                  "PredefinedContent":{  
                     "ReferenceID":"TransactionID=oLkO001502962284004&TimeStamp=2017-08-17T09%3a31%3a24.000Z&event=TENDER_CREATED"
                  }
               },
               "InfoQualify":"Status",
               "Device":"CashierDisplay"
            }
         ]
      },
      "MessageHeader":{  
         "SaleID":"DefaultSaleID",
         "ProtocolVersion":"3.0",
         "MessageType":"Request",
         "POIID":"MX925-261078152",
         "ServiceID":"542107365",
         "MessageClass":"Device",
         "MessageCategory":"Display",
         "DeviceID":"1502960678"
      }
   }
}

PROVIDE_CARD_DETAILS

{  
   "SaleToPOIRequest":{  
      "DisplayRequest":{  
         "DisplayOutput":[  
            {  
               "OutputContent":{  
                  "OutputFormat":"MessageRef",
                  "PredefinedContent":{  
                     "ReferenceID":"event=PROVIDE_CARD_DETAILS"
                  }
               },
               "InfoQualify":"Status",
               "Device":"CashierDisplay"
            }
         ]
      },
      "MessageHeader":{  
         "SaleID":"DefaultSaleID",
         "ProtocolVersion":"3.0",
         "MessageType":"Request",
         "POIID":"MX925-261078152",
         "ServiceID":"542107365",
         "MessageClass":"Device",
         "MessageCategory":"Display",
         "DeviceID":"1502960679"
      }
   }
}

CARD_DETAILS_PROVIDED

{  
   "SaleToPOIRequest":{  
      "DisplayRequest":{  
         "DisplayOutput":[  
            {  
               "OutputContent":{  
                  "OutputFormat":"MessageRef",
                  "PredefinedContent":{  
                     "ReferenceID":"event=CARD_DETAILS_PROVIDED"
                  }
               },
               "InfoQualify":"Status",
               "Device":"CashierDisplay"
            }
         ]
      },
      "MessageHeader":{  
         "SaleID":"DefaultSaleID",
         "ProtocolVersion":"3.0",
         "MessageType":"Request",
         "POIID":"MX925-261078152",
         "ServiceID":"542107365",
         "MessageClass":"Device",
         "MessageCategory":"Display",
         "DeviceID":"1502960680"
      }
   }
}

ASK_SIGNATURE

{  
   "SaleToPOIRequest":{  
      "DisplayRequest":{  
         "DisplayOutput":[  
            {  
               "OutputContent":{  
                  "OutputFormat":"MessageRef",
                  "PredefinedContent":{  
                     "ReferenceID":"event=ASK_SIGNATURE"
                  }
               },
               "InfoQualify":"Status",
               "Device":"CashierDisplay"
            }
         ]
      },
      "MessageHeader":{  
         "SaleID":"DefaultSaleID",
         "ProtocolVersion":"3.0",
         "MessageType":"Request",
         "POIID":"MX925-261078152",
         "ServiceID":"542107365",
         "MessageClass":"Device",
         "MessageCategory":"Display",
         "DeviceID":"1502960681"
      }
   }
}

Event notification

{  
  "SaleToPOIRequest": {
        "EventNotification": {
            "EventDetails"EventDetails": "newstate=IDLE&oldstate=TX_IN_PROGRESS"": "TX_IN_PROGRESS->IDLE",
            "EventToNotify": "Initialised",
            "TimeStamp": "2017-09-11T10:20:55.000Z"
        },
        "MessageHeader": {
            "SaleID": "John",
            "ProtocolVersion": "3.0",
            "MessageType": "Notification",
            "POIID": "MX925-260193322",
            "MessageClass": "Event",
            "MessageCategory": "Event",
            "DeviceID": "1505118720"
        
      }
   }
}

Questions

Can't find something you are looking for? Look at our FAQ for answers or contact Support.