Split the screen to show two requests

Split the screen on M400 payment terminals to show data while collecting input.

You can vertically split the landscape display of the M400 payment terminal. This allows you to show data on one side of the screen and collect input from a shopper on the other side of the screen. For example, show a receipt on the left side, and take a survey on the right side.

You can send two display requests at the same time, or one input request and one display request.

This feature is currently only available on M400 payment terminals.

How it works

You specify in an XML file what data you want to show. You convert that XML file to Base64.
You will pass the Base64-encoded string inside the DisplayOutput.OutputContent.OutputXHTML of the DisplayRequest.
You specify in an XML file what data you want to collect. You convert that XML file to Base64.
You will pass the Base64-encoded string inside the DisplayOutput.OutputContent.OutputXHTML of the InputRequest.
You send both requests simultaneously. If you do not send both requests at the same time, the terminal screen shows the first request on one side. The other side shows a black background until you send the second request.
If input is collected, you receive the data inside InputResult.Input of the InputResponse.
You then pass the relevant data from InputResult.Input to your system for validation and further use.

Show data

We currently support showing an image or a virtual receipt without a QR code.

In the XML example below, specify:

<screen name>: the screen split ratio. Can be split_50x50, split_40x60, and split_60x40.
<screen side>: the side of the split screen on which to show the request. Can be left or right.
<ReferenceID>: the type of request: Image.
<Text>: the image file converted to a Base64-encoded string.

Example XML file

 <?xml version="1.0" encoding="UTF-8"?>
<screen name="split_40x60" side="left">
	   <OutputFormat>
		   <PredefinedContent>
			   <ReferenceID>Image</ReferenceID>
		   </PredefinedContent>
		   <OutputText>
			   <Text>...your Base64-encoded image file...</Text>
		   </OutputText>
	   </OutputFormat>
</screen>

Encode the XML object to Base64. You will pass the resulting string in OutputContent.OutputXHTML.

Converted to a Base64-encoded string

PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4KPHNjcmVlbiBuYW1lPSJzcGxpdF80MHg2MCIgc2lkZT0ibGVmdCI+CiAgICA8T3V0cHV0Rm9ybWF0PgogICAgICAgIDxQcmVkZWZpbmVkQ29udGVudD4KICAgICAgICAgICAgPFJlZmVyZW5jZUlEPkltYWdlPC9SZWZlcmVuY2VJRD4KICAgICAgICA8L1ByZWRlZmluZWRDb250ZW50PgogICAgICAgIDxPdXRwdXRUZXh0PgogICAgICAgICAgICA8VGV4dD4uLi55b3VyIEJhc2U2NC1lbmNvZGVkIGltYWdlIGZpbGUuLi48L1RleHQ+CiAgICAgICAgPC9PdXRwdXRUZXh0PgogICAgPC9PdXRwdXRGb3JtYXQ+Cjwvc2NyZWVuPg==

Make a POST request to a Terminal API endpoint, specifying:

MessageHeader: the standard SaleToPOIRequest.MessageHeader object. Specify:

Parameter	Required	Description
`ProtocolVersion`		3.0
`MessageClass`		Device
`MessageCategory`		Display
`MessageType`		Request
`ServiceID`		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`		Your unique ID for the POS system component to send this request from.
`POIID`		The unique ID of the terminal to send this request to. Format: [device model]-[serial number].

DisplayRequest.DisplayOutput: an array with one array item containing:

Parameter Description

Device CustomerDisplay

InfoQualify Display

OutputContent.OutputFormat XHTML

OutputContent.OutputXHTML The Base64-encoded string from Step 2.

Show an image on the left

 	{
		"SaleToPOIRequest": {
			"MessageHeader": {
				"ProtocolVersion": "3.0",
				"MessageClass": "Device",
				"MessageCategory": "Display",
				"MessageType": "Request",
				"ServiceID": "1116172359",
				"SaleID": "POSSystemID12345",
				"POIID": "M400-284251175"
			},
			"DisplayRequest": {
				"DisplayOutput": [
					{
						"Device": "CustomerDisplay",
						"InfoQualify": "Display",
						"OutputContent": {
							"OutputFormat": "XHTML",
							"OutputXHTML": "PD94bWwgdmVyc2lvbj0iMS4wIiBlb..."
						}
					}
				]
			}
		}
	}

Check the result.

If the request is successful, the payment terminal shows the data on the specified side of the screen and you receive a display response with OutputResult.Response.Result: Success.
The other side of the screen shows a black background until you send the other request.

Display response

 	{
		"SaleToPOIResponse": {
			"DisplayResponse": {
				"OutputResult": [
					{
						"Device": "CustomerDisplay",
						"InfoQualify": "Display",
						"Response": {
							"Result": "Success"
						}
					}
				]
			},
			"MessageHeader": {...}
		}
	}

If an error occurs while decoding the image, the image won't be shown and you receive a display response with OutputResult.Response.Result: Failure. See XML validation for information about how errors in the XML content are reported.

After the input is collected on the other part of the screen, the shown data resizes to the full width of the screen and continues to show.
To stop it from showing, you need to send a payment request, or a request to show the standby screen.

Collect input

We currently support presenting shoppers with a form to collect their phone number or a multiple choice form that allows a single answer.

When using split screen input requests, the users cannot select the Confirm or Cancel keys on the terminal keypad. Instead, you need to implement logic to confirm or decline the request using the buttons on the input screen.
The numerical keypad and the Clear key can still be used.

In the XML example below, specify:

<screen name>: the screen split ratio. Can be split_50x50, split_40x60, and split_60x40.
<screen side>: the side of the split screen on which to show the request. Can be left or right.
<ReferenceID>: the type of request: GetPhoneNumber.
<Text>: shows the specified text on screen, for example Enter your phone number:.

Example XML file

 	<?xml version="1.0" encoding="UTF-8"?>
	<screen name="split_40x60" side="right">
		<OutputFormat>
			<PredefinedContent>
				<ReferenceID>GetPhoneNumber</ReferenceID>
			</PredefinedContent>
			<OutputText>
				<Text>Enter your phone number:</Text>
			</OutputText>
		</OutputFormat>
	</screen>

Encode the XML object to Base64. You will pass the resulting string in OutputContent.OutputXHTML.

Converted to a Base64-encoded string

PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4KPHNjcmVlbiBuYW1lPSJzcGxpdF80MHg2MCIgc2lkZT0icmlnaHQiPgogICAgPE91dHB1dEZvcm1hdD4KICAgICAgICA8UHJlZGVmaW5lZENvbnRlbnQ+CiAgICAgICAgICAgIDxSZWZlcmVuY2VJRD5HZXRQaG9uZU51bWJlcjwvUmVmZXJlbmNlSUQ+CiAgICAgICAgPC9QcmVkZWZpbmVkQ29udGVudD4KICAgICAgICA8T3V0cHV0VGV4dD4KICAgICAgICAgICAgPFRleHQ+RW50ZXIgeW91ciBwaG9uZSBudW1iZXI6PC9UZXh0PgogICAgICAgIDwvT3V0cHV0VGV4dD4KICAgIDwvT3V0cHV0Rm9ybWF0Pgo8L3NjcmVlbj4=

Make a POST request to a Terminal API endpoint, specifying:

MessageHeader: the standard SaleToPOIRequest.MessageHeader object. Specify:

Parameter	Required	Description
`ProtocolVersion`		3.0
`MessageClass`		Device
`MessageCategory`		Display
`MessageType`		Request
`ServiceID`		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`		Your unique ID for the POS system component to send this request from.
`POIID`		The unique ID of the terminal to send this request to. Format: [device model]-[serial number].

DisplayRequest.DisplayOutput: an array with one array item containing:

Parameter Description

Device CustomerDisplay

InfoQualify Display

OutputContent.OutputFormat XHTML

OutputContent.OutputXHTML The Base64-encoded string from Step 2.

InputRequest.InputData: this part of the request body handles the user input.

Parameter	Description
`Device`	CustomerInput
`InfoQualify`	Input
`InputCommand`	DigitString
`MaxInputTime`	(Integer) Time-out in seconds. This is the time that the user gets to finish their input.
`InputData.DefaultInputString`	Placeholder text for the input box, to let the user know what input format you are expecting.

Collect phone number on the right

 	{
		"SaleToPOIRequest": {
			"MessageHeader": {
				"ProtocolVersion": "3.0",
				"MessageClass": "Device",
				"MessageCategory": "Input",
				"MessageType": "Request",
				"ServiceID": "1116172359",
				"SaleID": "POSSystemID12345",
				"POIID": "M400-284251175"
			},
			"InputRequest": {
				"DisplayOutput": {
					"Device": "CustomerDisplay",
					"InfoQualify": "Display",
					"OutputContent": {
						"OutputFormat": "XHTML",
						"OutputXHTML": "PD94bWwgdmVyc2lvbj0iMS4wI..."
					}
				},
				"InputData": {
					"Device": "CustomerInput",
					"InfoQualify": "Input",
					"InputCommand": "DigitString",
					"MaxInputTime": 40,
					"DefaultInputString": "0612345678"
				}
			}
		}
	}

The payment terminal shows the input request on the specified side of the screen. The other side of the screen shows a black background, until you send the other request.

Wait for the user to supply the requested input.

The provided input is not validated against a format.

If the input is received from the terminal, the InputResult.Input contains the entered numerals (phone number) inside DigitInput.

Example response when the user entered a phone number

 	{
		"SaleToPOIResponse": {
			"InputResponse": {
				"InputResult": {
					"Device": "CustomerInput",
					"InfoQualify": "Input",
					"Input": {
						"DigitInput": "+31 0690758074",
						"InputCommand": "DigitString"
					},
					"Response": {
						"AdditionalResponse": "responseData=%7b%20%20%7d",
						"Result": "Success"
					}
				},
				"OutputResult": {
					"Device": "CustomerDisplay",
					"InfoQualify": "Display",
					"Response": {
						"Result": "Success"
					}
				}
			},
			"MessageHeader": {...}
		}
	}

If the input request times out, the InputResult.Response has AdditionalResponse: message=Screen%20timeout, Result: Failure, and ErrorCondition: Cancel.
If you make a payment request while the input request is waiting for input on the terminal, the payment request overrides the input request. The InputResult.Response has AdditionalResponse: message=A%20higher%20priority%20request%20has%20been%20received, Result: Failure, and ErrorCondition: Busy.
If the user declines to respond (by selecting the Skip button), the InputResult.Input.DigitInput field is empty. The InputResult.Response has Result: Failure and ErrorCondition: Cancel.

Pass the phone number from the DigitInput field to your system for validation and further use.

See XML validation for information about how errors in the XML content are reported.

XML validation

When we receive your display and input requests, we check if we can parse the XML content. We can also check whether the XML content matches the XML Schema Definition (XSD). We only do this XSD check if it is enabled for your account.

Parsing
We always check whether we can parse the XML content of your request.

For example, if the XML contains a syntax error like a missing caret >, we cannot parse the XML. We'll send a failure response with XHTML data could not be parsed.
XHTML data could not be parsed
Expand view
Copy link to code block
Copy code
Copy code
{ ... "Response": { "AdditionalResponse": "message=XHTML%20data%20could%20not%20be%20parsed.", "ErrorCondition": "MessageFormat", "Result": "Failure" } }
XSD
If we can parse the XML content and XSD checking is enabled, we validate the XML against the XSD.

To use this validation, ask our Support Team to enable the virtual receipt XSD check.

For example, if you add an element that is not in the XSD or if you omit a required element, the XML doesn't match the XSD. We'll send a failure response with XSD validation failed.
XSD validation failed
Expand view
Copy link to code block
Copy code
Copy code
{ ... "Response": { "AdditionalResponse": "message=XSD%20validation%20failed.", "ErrorCondition": "MessageFormat", "Result": "Failure" } }
The details of any XSD errors are in the terminal log.