Genius

Home/ Genius / Genius Your Way

Overview

This document serves as a reference guide for Point of Sale (PoS) developers wishing to use the Genius Your Way functions on the Genius device. They are additional features which are not part of the gateway payment process. Please keep the following points in mind:

  • The functions are available from the Idle and the Line Item Display (LID) screens on the Genius device.
  • The functions are separate, and can be used together or independently.
  • Using the Genius Your Way functions on the LID screen does not affect the integrity of the line items. When the functions are complete, the device returns to the LID screen. You do not need to re-submit the line items.
  • While the signature or agreement screens are active, the Genius device will not accept any further line item requests.
  • Cards that are swiped before these functions (via Swipe any time), remain available throughout the transaction, customers do not need to re-swipe.
  • All data is deleted after the sale is complete, is cancelled, or times out.
  • Communication requests between the PoS and the Genius device are made using HTTP/HTTPS and must follow the RFC 3986 specification.
  • All HTTP/HTTPS requests are case sensitive and must be URI encoded.
  • The request Format must be defined as XML or JSON.
  • The parameters for each request are strict and must comply with RFC3986. If you supply a parameter which cannot be handled by the request, an “HTTP 400 Bad Request” error message is sent to the PoS.

Get Agreement

The GetAgreement request prompts the Genius device to display a multi-line agreement with Accept and Decline buttons to capture the customer’s choice. Below is an example of a GetAgreement request.

GetAgreement
POST method
http://[CED-HOSTNAME]:8080/v1/pos
or Additional Connection Methods
POST data, content type x-www-form-urlencoded:

Action=GetAgreement&RequestID=xxx&Title=xxx&AgreementText=xxx&AcceptLabel=xxx&DeclineLabel=xxx&Format=xxx
GetAgreement
POST method
Genius://v2/pos/?request=
or Additional Connection Methods
POST data, content type x-www-form-urlencoded:

{"Action":"GetAgreement","RequestID":"xxx","Title":"xxx","AgreementText":"xxx","AcceptLabel":"xxx","DeclineLabel":"xxx","Format":"xxx"}

Request Parameters

Name Type Required Size Description
Action String Yes 1-23 GetAgreement - Method to initiate an agreement.
RequestID String Yes 1-40 An ID supplied by the POS that is used to identify the GetAgreement request.
Title String optional 1-36 A title that is displayed on the Genius device.
AgreementText String optional 1-2000 The text of the agreement. Tabs are replaced with four spaces prior to being displayed.
AcceptLabel String optional 1-18 The label applied to the Accept button.

Default = "Accept"
DeclineLabel String optional 1-18 The label applied to the Decline button.

Default = "Decline"
Format String X 1-4 The format that the CED should respond in. Possible values are:
  • XML
  • JSON

Response Parameters

Name Type Description
RequestID String The original identifier that was sent by the POS with the GetAgreement request.
Status String The cardholder's decision. Possible values are:
  • Accepted
  • Declined
  • Timeout
  • POSCancelled

Examples

XML response example:

<?xml version="1.0" encoding="utf-8"?>
<AgreementTextResponse>
    <RequestID>1234</RequestID>
    <Status>Accepted/Status>
</AgreementTextResponse>

JSON response example:

{
    "RequestID": "1234",
    "Status": "Accepted"
}

Important clarifications

Calling the GetAgreement function on the LID screen

If you issue a GetAgreement request whilst the Genius device is presenting the Line Item Display; the device returns to the LID screen after the following actions:

  • an agreement is accepted or,
  • an agreement is declined or,
  • the agreement screen times out

Normal LID function operations should then be followed.

Character limits

Spaces should be counted as characters when considering character limits.

The Accept and Decline button labels on the Genius device use a variable width font. This means that whilst the button labels may contain up to 18 characters, we recommend that your chosen text does not exceed 12 Em spaces, and that text is tested to ensure it fits. Exceeding this recommendation will lead to your text overrunning the edge of the buttons.

The title field also uses a variable width font. The title text may contain up to 36 Em spaced characters, however the MX915 has space for only 33 characters. Exceeding this will result in text running off the edge of the screen.

The AgreementText section of the Genius interface wraps text using a soft return at the end of complete words; no soft hyphens are used to split and wrap individual words. Therefore, in order to ensure that your chosen agreement text is correctly displayed, you must ensure that no single word or string of text (e.g. URL) exceeds 27 Em spaces on an MX915, or 40 Em spaces on an MX925. A vertical scroll bar is displayed if necessary.

Note: An Em space is the amount of space occupied by a capital letter “M”.

Bulleted lists can be created by using an asterisk * or hyphen - followed by text and a new line %0A or carriage return and new line %0D%0A.

Sample MX-925 Agreement Screenshot

Get Signature

The GetSignature request prompts the Genius device to capture a customer's signature and return it to the PoS. Below is an example of a GetSignature request:

GetSignature 
GET method
http://[CED-HOSTNAME]:8080/v1/pos?Action=GetSignature&RequestID=xxx&Title=xxx&Format=xxx

or Additional Connection Methods
GetSignature 
GET method
http://[CED-IP-Address]:8080/v1/pos?Action=GetSignature&RequestID=xxx&Title=xxx&Format=xxx

or Additional Connection Methods
GetSignature 
GET method
Genius://v1/pos/?request={"Action":"GetSignature","RequestID":"xxx","Title":"xxx","Format":"xxx"}

Request Parameters

Name Type Required Size Description
Action String Yes 1-16 GetSignature - Method to initiate a signature capture.
RequestID String Yes 1-40 An ID supplied by the PoS that is used to identify the GetSignature request.
Title String optional 1-36 A title that is displayed on the Genius device.
Format String Yes 1-4 The format that the CED should respond in. Possible values are:
  • XML
  • JSON

Response Parameters

Name Type Description
Status String Status of the GetSignature response. Possible values:
  • Success
  • Timeout
  • POSCancelled
SignatureData String The customer's signature as vector data.
RequestID String The original identifier that was sent by the PoS with the GetSignature request.

Examples

XML response example:

<?xml version="1.0" encoding="utf-8"?>

<GetSignatureResult>

    <Status>Success</Status>

    <SignatureData>306,48^306,49^307,49^308,50^309,50^310,51^311,52^313,53^315,55^318,56^322,59^327,61^332,64^338,67^344,70^352,74^360,77^369,81^377,84^386,87^0,65535^~</SignatureData>

    <RequestID>1234</RequestID>

</GetSignatureResult>

JSON response example:

{
  "Status": "Success",
  "SignatureData": "189,45^190,45^190,44^191,43^192,42^192,41^193,40^194,39^195,39^196,37^197,36^199,35^203,33^206,33^209,32^213,32^217,32^223,33^229,34^236,35^243,36^0,65535^~",
  "RequestID": "1234"
}

Important clarification

Cancelling incomplete signatures

The Cancel request should be used if the signature capture is not completed. For example, the consumer chooses not to sign. This cancels only the signature request, send a second Cancel request to cancel the full transaction.

Calling the GetSignature function on the LID screen

If you issue a GetSignature request whilst the Genius device is presenting the Line Item Display; the device returns to the LID screen after the following actions:

  • a GetSignature request is completed or,
  • a Cancel request is processed or,
  • the signature screen times out

Normal LID function operations should then be followed.

Character limits

Spaces should be counted as characters when considering character limits.

The title field uses a variable width font. The title may contain up to 36 Em spaced characters, however space for only 33 characters is available on the MX915. Exceeding this will result in text running of the edge of the screen.

Sample MX-925 Signature Screenshot

 

Get Customer Input

Using the GetCustomerInput function, Genius can capture customer information and feedback. You can use one of two methods, GET, and POST to prompt the Genius device to capture different types of information including:
  • The customer's name: the Genius device can capture the customer's name from a card swipe
  • Date: the Genius device can prompt the customer to enter date information such as their date of birth
  • Text: the Genius device can prompt the customer to enter numeric information such as their Social Security number
  • Responses: the Genius device can prompt the customer to respond to mandatory, and optional questions

GET Method

Using the GET method, you send a URL request over HTTPS. The Genius device can respond only in XML format. Using this method, the Genius device can capture:
  • The customer's name: Captures the customer's name from a card swipe
  • Date: Prompts the customer to enter date information, such as their date of birth
  • Text: Prompts the customer to enter numeric information, for example, their Social Security Number

POST Method

Using the POST method, you send an XML document to the Genius device, using either of the following URLs:
  • https://[CED-HOSTNAME]:8443/v1/pos?Action=GetCustomerInput
  • http://[CED-HOSTNAME]:8080/v1/pos?Action=GetCustomerInput
or see Additional Connection Methods.
Genius can prompt the customer for different types of information using one of the following “Input Types”:
  • ExplicitAgreementGroup - Displays up to six questions. The customer can respond to each question with a Yes or No answer
  • BinaryInputGroup - Displays a list of statements. The customer can select between two responses for each statement
  • MultipleChoice - Displays up to nine options. The customer can select an individual answer, or multiple answers
Note: We may introduce additional "Input Types" in furture releases.
The use cases for using the POST method describe complex customer interaction, and are better expressed in a structured data format such as XML. For more information on our XML structure, refer to the GetCustomerInput XML API.

GET Method 

The following example illustrates the format of a GetCustomerInput request.
GetCustomerInput
GET Method
 https://[CED-HOSTNAME]:8443/v1/pos?Action=GetCustomerInput&RequestID=xxx&Name=xxx&InputType=xxx&Guidance=xxx&Label=xxx&Optional=xxx&Regex=xxx&MaxLength=xxx&Format=XML
Note: You must send the GetCustomerInput request over HTTPS, the Genius device can respond only in XML format.

Request Parameters

Name Type Required Size Description
Action String Yes 1-16 GetCustomerInput - Method to initiate customer input.
RequestID String Yes 1-40 An ID the PoS supplies that Genius uses to identify the GetCustomerInput request.
Name String Yes 1-20 A key used to identify the value entered by the customer in the response to the PoS request. This could be a request for the customer to either their PAN, Social Security number, etc. 
InputType String Yes 1-20 The text of the agreement. The type of customer input required. Possible values are:
  • customerNameFromCard
  • date
  • text
Masked String (boolean) No 4-5 A flag indicating whether the customer input should be masked. Possible values are:
  • false - the customer input will display in plain text on the Genius device
  • true - the customer input will be masked on the Genius device
Default="false". Available only for date or text InputType.
Pattern String No 1-72 Each x or X character in the pattern is displayed on the Genius device as a space for the customer to complete. Any character other than x or X is a separator.

Characters in the pattern can be escaped with a preceding \. A literal backslash is represented by \\.

Available only for text InputType.
Must be present only if you do not specify MaxLength.
Guidance String No 1-144 Additional guidance text explaining what information the customer should enter.
Label String No 1-36 Label displays above the text entry box on the Genius device.

Available only for text InputType
Regex String No 1-144 Regular Expression to be applied to the customer input. Regex specifies the required format of the entry data. For example, a regex for a Social Security number could be \d{3}-\d{2}-\d{4}, in this example the SSN is 3 digits followed by a hyphen, followed by 2 digits followed by a hyphen, followed by 4 digits.

Available only for text InputType.
Optional String (boolean) No 4-5 Determines whether the customer must enter a value for the request. Possible values are:
  • false - the customer must enter a value for the request
  • true - the customer may skip entering a value for the request
Default="false"
MaxLength String No   The maximum length of the input string. The maximum value for MaxLength is 30.

Available only for text InputType.
Must be present only if you do not specify Pattern.
Format String Yes 1-5 The Genius device responds only in XML.

Response Parameters

Name Type Description
Status String Status of the GetCustomerInput response. Possible values are:
  • Success
  • Timeout
  • POSCancelled
  • UserCancelled
RequestID String The original identifier that was sent by the PoS with the GetCustomerInput request.
Values Object Contains information supplied by the customer. Possible fields:
  • <Value type="xxx" name="xxx">xxx</Value> - contains the InputType and Name supplied in the request in addition to the information provided by the customer.
If the value is a PAN, Genius masks it so only the last 4 digits are visible in the response.

Examples

XML response example:

<?xml version="1.0" encoding="UTF-8"?>
<GetCustomerInputResponse>
    <Status>Success</Status>
    <RequestID>1</RequestID>
    <Values>
        <Value inputType="text" name="PAN">************0026</Value>
    </Values>
<GetCustomerInputResponse>

POST Method

The GetCustomerInput request prompts the Genius device to display the requested “Input Type” to capture a response from the customer. This function is available when the Genius device is displaying the splash screen, or the LID screen.
GetCustomerInput
POST Method
 https://[CED-HOSTNAME]:8443/v1/pos?Action=GetCustomerInput
http://[CED-HOSTNAME]:8080/v1/pos?Action=GetCustomerInput
Note: Elements are one continuous string.

Common XML Elements

Each of the three "Input Types" share the following elements:
Element Type Required Size Description
GetCustomerInput.AckDurationMilliseconds String No,
default: 0		 0-10000 Duration, in milliseconds, for which to display the acknowledgment screen when submitted or cancelled. A value of '0' causes the acknowledgment screen to not be displayed.
GetCustomerInput.SubmitLabel String No, default: “Submit” 1-18 Label to display on the “Submit” button.
GetCustomerInput.CancelLabel String No, default: “Cancel” 1-18 Label to display on the “Cancel” button.
GetCustomerInput.InputRequest.RequestID String Yes 1-40 An identifier for this request that is meaningful to the POS. This is echoed back in the response.
GetCustomerInput.InputRequest.Title String No 1-36 Text to display in the title bar at the top of the screen. This is optional, and the default depends on the screen: BinaryInputGroup/ExplicitAgreement - "Customer Response" MultipleChoice - "Customer Selection"
GetCustomerInput.InputRequest.ResponseOptional Boolean No, default: “True” - If set to “True” (or defaulted), a “Cancel” button is rendered to allow the user to cancel. If set to false, the user has no facility to cancel. The POS is always permitted to cancel the input.

ExplicitAgreementGroup

The ExplicitAgreementGroup “Input Type” prompts the user for a “Yes” or “No” response to up to six questions. Each question has two checkboxes that the customer can use to indicate either a “Yes” or “No” response. The customer MUST answer all mandatory questions to proceed. Genius displays red asterisks on all mandatory questions.
The MX-915 supports two questions per screen and the MX-925 supports three questions per screen. If the limit of questions per screen is exceeded for either device, Genius displays “Next” and “Back” navigation buttons.
925_unsubmitted.png
MX-925 ExplicitAgreementGroup before submission

925_submitted.png
MX-925 ExplicitAgreementGroup after submission without answering all required questions

The API for Explicit Agreement is described in the GetCustomerInput XML API.

Request Parameters

Element Type Required Size Description
GetCustomerInput.AckDurationMilliseconds Integer No,
default: 0		 0-10000 Duration, in milliseconds, for which to display the acknowledgment screen when submitted or cancelled. A value of '0' causes the acknowledgment screen to not be displayed.
GetCustomerInput.SubmitLabel String No, default: “Submit” 1-18 Label to display on the “Submit” button.
GetCustomerInput.CancelLabel String No, default: “Cancel” 1-18 Label to display on the “Cancel” button.
GetCustomerInput.InputRequest.RequestID String Yes 1-40 An identifier for this request that is meaningful to the POS. This is echoed back in the response.
GetCustomerInput.InputRequest.Title String No 1-36 Text to display in the title bar at the top of the screen. This is optional, and the default depends on the screen: BinaryInputGroup/ExplicitAgreement - "Customer Response" MultipleChoice - "Customer Selection"
GetCustomerInput.InputRequest.ResponseOptional Boolean NoNo, default: “True” - If set to “True” (or defaulted), a “Cancel” button is rendered to allow the user to cancel. If set to false, the user has no facility to cancel. The POS is always permitted to cancel the input.
GetCustomerInput.InputRequest.
ExplicitAgreementGroup.YesLabel		 String No, default: “Yes” 1-18 Label to display above the left‑hand checkbox column, representing a positive response.
GetCustomerInput.InputRequest.
ExplicitAgreementGroup.NoLabel		 String No, default: “No” 1-18 Label to display above the right‑hand checkbox column, representing a negative response.
GetCustomerInput.InputRequest.
ExplicitAgreementGroup.ExplicitAgreement		 - - - Group to hold statements to present to the user.
GetCustomerInput.InputRequest.
ExplicitAgreementGroup.ExplicitAgreement.InputID		 String Yes 1-40 An identifier for this statement that is meaningful to the POS. This is echoed back in the response.
GetCustomerInput.InputRequest.
ExplicitAgreementGroup.ExplicitAgreement.Text		 String Yes  1-80 The text to display for this statement.
 

Examples

XML response example:

<?xml version="1.0"?>
<GetCustomerInputResponse>
  <InputResponse>
    <RequestID>1234</RequestID>
    <Status>Success</Status>
    <ExplicitAgreementGroupResponse>
      <ExplicitAgreementResponse>
        <InputID>Question1</InputID>
        <ExplicitAgreementResponseValue>YES</ExplicitAgreementResponseValue>
      </ExplicitAgreementResponse>
      <ExplicitAgreementResponse>
        <InputID>Question2</InputID>
        <ExplicitAgreementResponseValue>YES</ExplicitAgreementResponseValue>
      </ExplicitAgreementResponse>
    </ExplicitAgreementGroupResponse>
  </InputResponse>
</GetCustomerInputResponse>

BinaryInputGroup

The BinaryInputGroup “Input Type” prompts the user to respond to a statement with a choice between one of two states.

MX-925 BinaryInputGroup

The API for Explicit Agreement is described in the GetCustomerInput XML API.

Request Parameters

Element Type Required Size Description
GetCustomerInput.AckDuration
Milliseconds		 Integer No,
default: 0		 0-10000 Duration, in milliseconds, for which to display the acknowledgment screen when submitted or cancelled. A value of '0' causes the acknowledgment screen to not be displayed.
GetCustomerInput.SubmitLabel String No, default: “Submit” 1-18 Label to display on the “Submit” button.
GetCustomerInput.CancelLabel String No, default: “Cancel” 1-18 Label to display on the “Cancel” button.
GetCustomerInput.InputRequest.
RequestID		 String Yes 1-40 An identifier for this request that is meaningful to the POS. This is echoed back in the response.
GetCustomerInput.InputRequest.
Title		 String No 1-36 Text to display in the title bar at the top of the screen. This is optional, and the default depends on the screen: BinaryInputGroup/ExplicitAgreement - "Customer Response" MultipleChoice - "Customer Selection"
GetCustomerInput.InputRequest.
ResponseOptional		 Boolean NoNo, default: “True” - If set to “True” (or defaulted), a “Cancel” button is rendered to allow the user to cancel. If set to false, the user has no facility to cancel. The POS is always permitted to cancel the input.
GetCustomerInput.InputRequest.
BinaryInputGroup.InputLabel1		 String No 1-18 Label to display above the left-hand checkbox column. If not specified, a label is not displayed.
GetCustomerInput.InputRequest.
BinaryInputGroup.InputLabel2		 String No 1-18 Label to display above the “Decline” checkbox column. If not specified, a label is not displayed.
GetCustomerInput.InputRequest.
BinaryInputGroup.InputStyle		 String No, default: STANDARD STANDARD POSITIVE_NEGATIVE Defines input type for the customer. “STANDARD” displays option buttons for the customer’s input, “POSITIVE_NEGATIVE” displays check boxes for the customer to provide positive or negative feedback.
GetCustomerInput.InputRequest.
BinaryInputGroup.BinaryInput		 - - - Group to hold statements to present to the user.
GetCustomerInput.InputRequest.
BinaryInputGroup.BinaryInput.InputID		 String Yes  1-40 An identifier for this statement that is meaningful to the POS. This is echoed back in the response.
GetCustomerInput.InputRequest.
BinaryInputGroup.BinaryInput.Default		 String No, default: NONE NONE RESPONSE1 RESPONSE2 The default response to this statement on initial screen render.
GetCustomerInput.InputRequest.
BinaryInputGroup.BinaryInput.
Optional		 Boolean No, Default: “False” - If set to “False” (or defaulted), a response to this statement is required before the “Submit” button is active.
GetCustomerInput.InputRequest.
BinaryInputGroup.BinaryInput.
Text		 String Yes 1-80 The text to display for this statement.

Response Parameters

Element Type Required Size/Constraint Description
GetCustomerInputResponse.InputResponse.RequestID String Yes 1-40 RequestId sent in the request, echoed back in the response.
GetCustomerInputResponse.InputResponse.Status String Yes Success
TimeOut
PosCancelled
UserCancelled		 Response status.
GetCustomerInputResponse.InputResponse.
BinaryInputGroup.BinaryInput.InputID		 String Yes 1-40 StatementId sent in the request, echoed back in the response.
GetCustomerInputResponse.InputResponse.
BinaryInputGroup.BinaryInput.BinaryResponseValue		 String Yes NONE
RESPONSE1
RESPONSE2		 Final state of the statement response on submission.

Examples

XML response example:

<?xml version="1.0"?>
<GetCustomerInputResponse>
  <InputResponse>
    <RequestID>1234</RequestID>
    <Status>Success</Status>
    <ExplicitAgreementGroupResponse>
      <ExplicitAgreementResponse>
        <InputID>Question1</InputID>
        <ExplicitAgreementResponseValue>YES</ExplicitAgreementResponseValue>
      </ExplicitAgreementResponse>
      <ExplicitAgreementResponse>
        <InputID>Question2</InputID>
        <ExplicitAgreementResponseValue>YES</ExplicitAgreementResponseValue>
      </ExplicitAgreementResponse>
    </ExplicitAgreementGroupResponse>
  </InputResponse>
</GetCustomerInputResponse>

MultipleChoice

The MultipleChoice “Input Type” prompts the user to select from up to nine options. You can specify the minimum and maximum number of selections.
Using the default setting for MultipleChoice, the customer can select a single option. In this mode, if the customer selects an option, Genius automatically de-selects any existing selected option. If multiple selections are allowed, Genius greys out the remaining options when the customer makes the maximum number of selections. The customer must de-select an option before they can make a new selection.
925_multiselect_2.png
MX-925 MultipleChoice, three options selected

925_multiselect_3.png
MX-925 MultipleChoice, additional selection required

The API for MultipleChoice is described in the GetCustomerInput XML API.

Request Parameters

Element Type Required Size Description
GetCustomerInput.AckDurationMilliseconds Integer No,
default: 0		 0-10000 Duration, in milliseconds, for which to display the acknowledgment screen when submitted or cancelled. A value of '0' causes the acknowledgment screen to not be displayed.
GetCustomerInput.SubmitLabel String No, default: “Submit” 1-18 Label to display on the “Submit” button.
GetCustomerInput.CancelLabel String No, default: “Cancel” 1-18 Label to display on the “Cancel” button.
GetCustomerInput.InputRequest.RequestID String Yes 1-40 An identifier for this request that is meaningful to the POS. This is echoed back in the response.
GetCustomerInput.InputRequest.Title String No 1-36 Text to display in the title bar at the top of the screen. This is optional, and the default depends on the screen: BinaryInputGroup/ExplicitAgreement - "Customer Response" MultipleChoice - "Customer Selection"
GetCustomerInput.InputRequest.
ResponseOptional		 Boolean No, default: “True" - If set to “True” (or defaulted), a “Cancel” button is rendered to allow the user to cancel. If set to false, the user has no facility to cancel. The POS is always permitted to cancel the input.
GetCustomerInput.InputRequest.
MultipleChoice.MinSelection		 Integer No 1-9 The minimum number of elements that must be selected before the screen can be submitted. Default: “1”
GetCustomerInput.InputRequest.
MultipleChoice.MaxSelection		 Integer No 1-9 The maximum number of elements that can be selected. Default: “1”
GetCustomerInput.InputRequest
.MultipleChoice.Option		 - - - Option to present to the user.
GetCustomerInput.InputRequest.
MultipleChoice.Option.InputID		 String Yes 1-40 An option identifier for this option, meaningful to the POS.
GetCustomerInput.InputRequest.
MultipleChoice.Option.DefaultState		 Boolean No  - The default state of this option. “True” will set the initial state to selected, otherwise the option is initially not selected. Default: “False”
GetCustomerInput.InputRequest.
MultipleChoice.Option.Text		 String Yes 1-18 The text label to display for this option.

Response Parameters

Element Type Required Size/Constraint Description
GetCustomerInputResponse.
InputResponse.RequestID		 String Yes 1-40 RequestId sent in the request, echoed back in the response.
GetCustomerInputResponse.
InputResponse.Status		 String Yes Success
Timeout
PosCancelled
UserCancelled		 Response status.
GetCustomerInputResponse.
InputResponse.MultipleChoiceResponse.
OptionResponse.InputID		 String Yes 1-40 OptionId sent in the request, echoed back in the response.
GetCustomerInputResponse.
InputResponse.MultipleSelectionResponse.
OptionResponse.OptionResponseValue		 Boolean Yes - Final state of the option on submission.

Examples

XML response example:

<?xml version="1.0"?>
<GetCustomerInputResponse>
  <InputResponse>
    <RequestID>1234</RequestID>
    <Status>Success</Status>
    <MultipleChoiceResponse>
      <OptionResponse>
        <InputID>Question1</InputID>
        <OptionResponseValue>true</OptionResponseValue>
      </OptionResponse>
    </MultipleChoiceResponse>
  </InputResponse>
</GetCustomerInputResponse>

Important clarification

Cancelling an incomplete customer input

You should use the Cancel request if the customer input is incomplete. For example, if the customer chooses not to provide a value for the request, this cancels only the customer input request. To cancel the full transaction you must send a second Cancel request.

Character limits

When considering character limits, you should count spaces as characters.
You can wrap the Guidance text section of the Genius interface by using a carriage return and new line %0D%0A, for example, Guidance=Please%20swipe%20your%0D%0Acard. If you do not use carriage return and new line, the Guidance text section of the Genius interface wraps text using a soft return at the end of complete words. Therefore, to display your chosen guidance text correctly, you must ensure:
  • ​If InputType is customerNameFromCard, then no single word or string of text may exceed 15 Em spaces
  • If InputType is date or text then no single word or string of text may exceed 31 Em spaces on an MX915, or 34 Em spaces on an MX925.
Note: An Em space is the amount of space occupied by a capital letter “M”.

Calling the GetCustomerInput function on the Line Item Display (LID) screen

If you issue a GetCustomerInput request while the Genius device is showing the Line Item Display (LID), the device returns to the LID screen after one of the following actions:
  • A GetCustomerInput request is completed
  • A Cancel request is processed
  • The customer input screen times out
  • The customer chooses to skip input on an optional request
  • The customer chooses to cancel input on a mandatory request
Normal LID function operations should then be followed.

Date response format

The Genius device returns the date InputType response in ISO 8601 format (YYYY-MM-DD).

Sample MX-925 Customer Input Screenshots

InputType=date and Optional=true

Genius-DOB-Entry.png

InputType=customerNameFromCard and Optional=false

Genius-MSR-Name-Capture.png
 

GetCustomerInput XML API

<?xml version="1.0" encoding="utf-8"?>
<xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:simpleType name="IdString">
    <xs:restriction base="xs:string">
      <xs:minLength value="1"/>
      <xs:maxLength value="40"/>
    </xs:restriction>
  </xs:simpleType>

  <xs:simpleType name="TitleString">
    <xs:restriction base="xs:string">
      <xs:minLength value="1"/>
      <xs:maxLength value="36"/>
    </xs:restriction>
  </xs:simpleType>

  <xs:simpleType name="LabelString">
    <xs:restriction base="xs:string">
      <xs:minLength value="1"/>
      <xs:maxLength value="18"/>
    </xs:restriction>
  </xs:simpleType>

  <xs:simpleType name="OptionString">
    <xs:restriction base="xs:string">
      <xs:minLength value="1"/>
      <xs:maxLength value="18"/>
    </xs:restriction>
  </xs:simpleType>

  <xs:simpleType name="BinaryInputString">
    <xs:restriction base="xs:string">
      <xs:minLength value="1"/>
      <xs:maxLength value="80"/>
    </xs:restriction>
  </xs:simpleType>

  <xs:simpleType name="DurationInteger">
    <xs:restriction base="xs:integer">
      <xs:minInclusive value="0"/>
      <xs:maxInclusive value="10000"/>
    </xs:restriction>
  </xs:simpleType>

  <xs:simpleType name="SelectionInteger">
    <xs:restriction base="xs:integer">
      <xs:minInclusive value="0"/>
      <xs:maxInclusive value="9"/>
    </xs:restriction>
  </xs:simpleType>

  <xs:simpleType name="BinaryResponseValueType">
    <xs:restriction base="xs:string">
      <xs:enumeration value="NONE"/>
      <xs:enumeration value="RESPONSE1"/>
      <xs:enumeration value="RESPONSE2"/>
    </xs:restriction>
  </xs:simpleType>

  <xs:simpleType name="InputStyleType">
    <xs:restriction base="xs:string">
      <xs:enumeration value="STANDARD"/>
      <xs:enumeration value="POSITIVE_NEGATIVE"/>
    </xs:restriction>
  </xs:simpleType>

  <xs:simpleType name="ExplicitAgreementResponseValueType">
    <xs:restriction base="xs:string">
      <xs:enumeration value="NONE"/>
      <xs:enumeration value="YES"/>
      <xs:enumeration value="NO"/>
    </xs:restriction>
  </xs:simpleType>

  <xs:simpleType name="StatusType">
    <xs:restriction base="xs:string">
      <xs:enumeration value="Success"/>
      <xs:enumeration value="Timeout"/>
      <xs:enumeration value="PosCancelled"/>
      <xs:enumeration value="UserCancelled"/>
    </xs:restriction>
  </xs:simpleType>

  <xs:element name="GetCustomerInput">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="CancelLabel" type="LabelString" minOccurs="0" maxOccurs="1"/>
        <xs:element name="SubmitLabel" type="LabelString" minOccurs="0" maxOccurs="1"/>
        <xs:element name="AckDurationMilliseconds" type="DurationInteger" minOccurs="0" maxOccurs="1"/>
        <xs:element name="InputRequest" minOccurs="1" maxOccurs="1">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="RequestID" type="IdString" minOccurs="1" maxOccurs="1"/>
              <xs:element name="Title" type="TitleString" minOccurs="0" maxOccurs="1"/>
              <xs:element name="ResponseOptional" type="xs:boolean" minOccurs="0" maxOccurs="1"/>
              <xs:choice>
                <xs:element name="BinaryInputGroup">
                  <xs:complexType>
                    <xs:sequence>
                      <xs:element name="InputLabel1" type="LabelString" minOccurs="0" maxOccurs="1"/>
                      <xs:element name="InputLabel2" type="LabelString" minOccurs="0" maxOccurs="1"/>
                      <xs:element name="InputStyle" type="InputStyleType" minOccurs="0" maxOccurs="1"/>
                      <xs:element name="BinaryInput" minOccurs="1" maxOccurs="6">
                        <xs:complexType>
                          <xs:sequence>
                            <xs:element name="InputID" type="IdString" minOccurs="1" maxOccurs="1"/>
                            <xs:element name="Default" type="BinaryResponseValueType" minOccurs="0" maxOccurs="1"/>
                            <xs:element name="Optional" type="xs:boolean" minOccurs="0" maxOccurs="1"/>
                            <xs:element name="Text" type="BinaryInputString" minOccurs="1" maxOccurs="1"/>
                          </xs:sequence>
                        </xs:complexType>
                      </xs:element>
                    </xs:sequence>
                  </xs:complexType>
                </xs:element>
                <xs:element name="ExplicitAgreementGroup">
                  <xs:complexType>
                    <xs:sequence>
                      <xs:element name="YesLabel" type="LabelString" minOccurs="0" maxOccurs="1" default="Yes"/>
                      <xs:element name="NoLabel" type="LabelString" minOccurs="0" maxOccurs="1" default="No"/>
                      <xs:element name="ExplicitAgreement" minOccurs="1" maxOccurs="6">
                        <xs:complexType>
                          <xs:sequence>
                            <xs:element name="InputID" type="IdString" minOccurs="1" maxOccurs="1"/>
                            <xs:element name="Text" type="BinaryInputString" minOccurs="1" maxOccurs="1"/>
                          </xs:sequence>
                        </xs:complexType>
                      </xs:element>
                    </xs:sequence>
                  </xs:complexType>
                </xs:element>
                <xs:element name="MultipleChoice">
                  <xs:complexType>
                    <xs:sequence>
                      <xs:element name="MinSelection" type="SelectionInteger" minOccurs="0" maxOccurs="1"/>
                      <xs:element name="MaxSelection" type="SelectionInteger" minOccurs="0" maxOccurs="1"/>
                      <xs:element name="Option" minOccurs="1" maxOccurs="9">
                        <xs:complexType>
                          <xs:sequence>
                            <xs:element name="InputID" type="IdString" minOccurs="1" maxOccurs="1"/>
                            <xs:element name="DefaultState" type="xs:boolean" minOccurs="0" maxOccurs="1"/>
                            <xs:element name="Text" type="OptionString" minOccurs="1" maxOccurs="1"/>
                          </xs:sequence>
                        </xs:complexType>
                      </xs:element>
                    </xs:sequence>
                  </xs:complexType>
                </xs:element>
              </xs:choice>
            </xs:sequence>
          </xs:complexType>
        </xs:element>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
  <xs:element name="GetCustomerInputResponse">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="InputResponse" minOccurs="1" maxOccurs="1">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="RequestID" type="IdString" minOccurs="1" maxOccurs="1"/>
              <xs:element name="Status" type="StatusType" minOccurs="1" maxOccurs="1"/>
              <xs:choice>
                <xs:element name="BinaryInputGroupResponse">
                  <xs:complexType>
                    <xs:sequence>
                      <xs:element name="BinaryInputResponse" minOccurs="1" maxOccurs="10">
                        <xs:complexType>
                          <xs:sequence>
                            <xs:element name="InputID" type="IdString" minOccurs="1" maxOccurs="1"/>
                            <xs:element name="BinaryResponseValue" type="BinaryResponseValueType" minOccurs="1" maxOccurs="1"/>
                          </xs:sequence>
                        </xs:complexType>
                      </xs:element>
                    </xs:sequence>
                  </xs:complexType>
                </xs:element>
                <xs:element name="ExplicitAgreementGroupResponse">
                  <xs:complexType>
                    <xs:sequence>
                      <xs:element name="ExplicitAgreementResponse" minOccurs="1" maxOccurs="10">
                        <xs:complexType>
                          <xs:sequence>
                            <xs:element name="InputID" type="IdString" minOccurs="1" maxOccurs="1"/>
                            <xs:element name="ExplicitAgreementResponseValue" type="ExplicitAgreementResponseValueType" minOccurs="1" maxOccurs="1"/>
                          </xs:sequence>
                        </xs:complexType>
                      </xs:element>
                    </xs:sequence>
                  </xs:complexType>
                </xs:element>
                <xs:element name="MultipleChoiceResponse">
                  <xs:complexType>
                    <xs:sequence>
                      <xs:element name="OptionResponse" minOccurs="1" maxOccurs="9">
                        <xs:complexType>
                          <xs:sequence>
                            <xs:element name="InputID" type="IdString" minOccurs="1" maxOccurs="1"/>
                            <xs:element name="OptionResponseValue" type="xs:boolean" minOccurs="1" maxOccurs="1"/>
                          </xs:sequence>
                        </xs:complexType>
                      </xs:element>
                    </xs:sequence>
                  </xs:complexType>
                </xs:element>
              </xs:choice>
            </xs:sequence>
          </xs:complexType>
        </xs:element>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>

Alternative Device Communication Methods

There are two methods you can use to send requests from your POS to the Genius device:
  • HTTPS communication method, which uses a host name to target the Genius device
  • IP-address communication method, which uses an IP address to target the Genius device
We recommend using the HTTPS communication method as it is a secure and reliable connection. You need to modify the request depending on the communication method you want to use. The remainder of the integration, including Endpoints and URLs, is the same for both communication methods.

Example Requests

HTTPS
https://[CED-IP-Address]:8443/v2/pos?TransportKey=xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxxx&Format=xxx
HTTPS
https://[CED-HOSTNAME]:8443/v2/pos?TransportKey=xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxxx&Format=xxx
IP Address
http://[CED-IP-Address]:8080/v1/pos?TransportKey=xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxxx&Format=xxx

HTTPS Communication Method

The HTTPS communication method lets you connect your web-based POS to the Genius device using its host name. This method is a secure and reliable connection that is not affected by a change to the IP address of the Genius device. To use the HTTPS communication method, you must install a Cayan certificate on any device that connects to a Genius device. For more information about how to install this certificate, refer to How to install a Cayan certificate.
Important: You must use the HTTPS communication method when using any web-based POS that uses CORS within the Genius application.

Example Request

HTTPS Cancel Example
https://[CED-HOSTNAME]:8443/v1/pos?Action=Cancel&Format=xxx

IP-Address Communication Method

The IP-address communication method lets you connect to the Genius device using its current IP address. We no longer recommend this method as the connection to the POS is lost if the IP address of the Genius device changes. For more information on how to locate and configure an IP address on a Genius device, refer to  How can I Locate and Configure the IP Address on a Genius Device.

Example Request

IP Address
http://[CED-IP-Address]:8080/v1/pos?TransportKey=xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxxx&Format=xxx

Android Intent Example

When using Android Intents, you can use the following sample to initiate a transaction.

Java code: