Genius

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.

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.

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

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:

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

Example Request

HTTPS Cancel Example

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

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

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

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

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.

MX-925 ExplicitAgreementGroup before submission


MX-925 ExplicitAgreementGroup after submission without answering all required questions

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

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.

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.

MX-925 MultipleChoice, three options selected


MX-925 MultipleChoice, additional selection required

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

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

InputType=customerNameFromCard and Optional=false

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>