CED Peripherals

Home/Developers / CED PeripheralsQuick Links

Genius Your Way

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, JSON, or JSONP.
  • 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.

1 Start 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-IP-Address]: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
 

Request Parameters

Name Type Required Size Description
Action String Yes 1-16 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-1000 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-5 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
RequestID String The original identifier that was sent by the PoS with the GetAgreement request.

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 Vera bold, which is 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 Agreement Text 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 34 Em spaces on an MX915, or 43 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”.

Creating bulleted lists


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

2 Start Signature Capture

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-IP-Address]:8080/v1/pos?Action=GetSignature&RequestID=xxx&Title=xxx&Format=xxx

or Additional Connection Methods
 

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-5 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 MessageList 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 Signature request is completed or,
  • a Cancel request is processed or,
  • the signature screen times out
Normal LID function operations should then be followed.

Sample MX-925 Signature Screenshot

 

3 Alternative Device Communication Methods

The request from the PoS to the Genius device has a few optional alternative formats. All alternative device communication methods require the modification of the request itself in a few simple ways, as well as a few additional steps to ensure the PoS can connect securely to the device. It is important to note that nothing changes about the Genius integration at all, including Endpoints and URLs with the exception of the use of HTTPS and port 8443, or the use of the FQDN in the case of the mDNS option. Examples of the requests and descriptions of these formats can be found below:

HTTPS
https://[CED-IP-Address]:8443/v2/pos?TransportKey=xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxxx&Format=xxx
mDNS
https://[CED-SERIAL-NUMBER]-geniusced.local:8443/v1/pos?TransportKey=xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxxx&Format=xxx
 

HTTPS communication method

HTTPS communication method allows for secure connection to the device from a web based PoS and is required for any web PoS that requires the use of CORS within the Genius application. HTTPS support requires that any hardware connecting to a Genius device have a Cayan certificate installed. That certificate can be obtained here. For more information on how to install this certificate please see our knowledge base article found here. (coming soon)
HTTPS Cancel Example
https://[CED-IP-Address]:8443/v1/pos?Action=Cancel&Format=xxx
HTTPS LID Example
https://[CED-IP-Address]:8443/v2/pos?Action=StartOrderx&Order=1000&Format=xxx

mDNS communication method

Multicast DNS is enabled on all Genius devices using software version 5.0.0.0 and above. This functionality allows the device to broadcast across the local network, enabling the PoS to connect via the desegnated device name. This protects the PoS from needing to update the device IP in the event it has changed. mDNS connection supports both HTTP and HTTPS. HTTPS support requires that any hardware connecting to a Genius device have a Cayan certificate installed. That certificate can be obtained here. For more information on mDNS uses and functionality please see our knowledge base article found here. (coming soon)
mDNS HTTP
http://[CED-SERIAL-NUMBER]-geniusced.local:8080/v1/pos?TransportKey=xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxxx&Format=xxx
mDNS HTTPS
https://[CED-SERIAL-NUMBER]-geniusced.local:8443/v1/pos?TransportKey=xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxxx&Format=xxx
 

4 Get Customer Input

The GetCustomerInput request prompts the Genius device to capture a customer's information and return it to the PoS. The Genius device can capture the following information:

  • 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

The following example illustrates the format of a GetCustomerInput request.

GetCustomerInput
GET Method
https://[CED-IP-Address]: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>
						

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