Simple Connect Protocol API and Guide - 8 - 1217
Simple Connect Protocol API and Guide - 8 - 1217
6
API and Guide
2861 Pullman Street, Santa Ana, CA 92705 | Phone. 949.486.0320 | Fax. 949.486.0333 | www.exadigm.com
Simple Connect Protocol Version 0.0.6 – API and Guide
Warranty
The information contained in this document is subject to change without notice. ExaDigm
makes no warranty of any kind with regard to this material, including, but not limited to, the
implied warranties or merchantability and fitness for a particular purpose. ExaDigm shall not be
liable for errors contained herein or for incidental or consequential damages in connection with
the furnishing, performance, or use of this material.
Table of Contents
Section 4, titled “Data Connection”, describes the basic data connection options that are available for
setting up a data connection between the ExaDigm terminal and a POS device. This section also
describes how to configure each of these connections in the ExaDigm terminal application.
Section 5, titled “Message Formats”, provides a high-level description of the data formats used for
messages as well as the conventions used in describing the format of each message.
Section 6, titled “Semi-Integration Messages”, describes how semi-integrated messages are exchanged
(section 6.1) as well as the format of the messages that are sent and received (sections 6.2 and 6.3).
Section 7, titled “Additional Messages”, describes additional messages and protocols that are outside the
bounds of basic semi-integration operations, including using messages that allow using the terminal as a
printer (section 7.3 on page 32), or as a card reader (section 7.5 on page 35).
6.1.2 Protocol for Batch Summary Report and Batch Settlement Report
The following sections outline the sequence of messages that are sent back and forth between a POS
device and an ExaDigm terminal to request a batch summary reporting or batch settlement processing
and reporting.
{
"packetID" : "XCRP",
("packetVersion" : "0.0.6",)
"packetData" : {
"packetAuthorization" : "<packet_auth>",
"requestID" : <request_id>,
("customID” : {
"label" : "(custom_id_label)",
"data" : "(custom_id_value)"
},)
"baseAmount" : <base_amt>,
("cashbackAmount" : (cashback_amt),)
("decimals" : <decimals>,)
("currencyChar" : "<currency_char>",)
("receiptCount" : <receipt_qty>,)
("transactionID" : <transaction_id>,)
"transactionType" : <transaction_type>,
"taxAmount" : <tax_amt>,
("tipAmount" : <tip_amt>,)
("emailAddress" : "<email_address>",)
("terminalInputFlag" : <terminal_input_flag>,)
("signatureCaptureFlag" : <signature_capture_flag>,)
("reportLevel" : <report_level>,)
("receiptDetail" : {
"receiptData" : [
{"label" : "<label_1>" (, "data" : "<data_1>")},
{"label" : "<label_2>" (, "data" : "<data_2>")},
...
{"label" : "<label_N>" (, "data" : "<data_N>")},
]
})
}
}
1
The values listed in this table are defined in the enumerated type 'NxPayReqIdEn' that is defined in the ExaDigm SDK header
file “exaipc_payment.h”.
2
Versions of this document prior to revision 5 use request ID 9 for authorization request; versions of this document from revision
5 forward use request ID 99 for the same operation to provide more flexibility
3
The values listed in this table are defined in the enumerated type 'NxTranTypeEn' that is defined in the ExaDigm SDK header
file “exaipc_payment.h”.
o 14 = Debit sale
o 15 = Debit return
o 16 = Debit balance
o 17 = EBT food sale
o 18 = EBT food return
o 19 = EBT food balance
o 20 = EBT cash sale
o 21 = EBT cash balance
o 22 = EBT voucher sale
o 44 = MOTO sale
o 45 = MOTO authorization
o 46 = MOTO postauthorization
o 48 = MOTO force
o 50 = MOTO return
o 52 = MOTO status check
o 59 = Void last transaction
o 61 = Void TRNID
o 99 = Check verify
o 100 = Check conversion
o 112 = Cash sale
o 113 = Cash return
<tax_flag> is an integer value that must be set to one of the following values 4:
o 0 = Tax not provided
o 1 = Tax included
o 2 = Nontaxable purchase
<tax_amt> is an integer value of the amount of tax that is included in the total purchase amount,
with all digits and without decimal point. The same number of decimal places and the same
currency symbol are used for the tax amount as for the base amount.
(tip_amt) is an optional integer value for the tip amount to display to the user, with all digits and
without decimal point. The same number of decimal places and the same currency symbol are
used for the tip amount as for the base amount.
o Negative value = Do not display or use tip amount
o Zero or greater = Display the tip amount to the user
"(email_address)" is an optional string value that indicates the email address where an email
version of the receipt is to be sent. The option will be utilized based on the setting of the flag
'terminal_input_flag':
o If 'terminal_input_flag' is set to 1, and if the email address is sent in this field, then the user
will be prompted by the application to review and confirm the email address.
o If 'terminal_input_flag' is set to 1, and if this field is blank, then the user will be prompted by
the application to enter an email address.
o If 'terminal_input_flag' is set to 1, but this parameter has been omitted, then the user will not
be prompted for an email address and no email will be sent.
o If 'terminal_input_flag' is set to 0, and if the email address is sent in this field, then the
application will send an email using the address without prompting the user.
o If 'terminal_input_flag' is set to 0, and if the email address or this parameter have been
omitted, then no email will be sent.
NOTE: The application must be configured to support receipt emails before this option can be
successfully used. This means that the feature must be enabled, and the email server
parameters for sending emails must be properly configured. If email has not been properly
configured and enabled in the application, then this parameter will be ignored in all cases.
4
The values listed in this table are defined in the enumerated type 'NxTaxFlagEn' that is defined in the ExaDigm SDK header file
“exaipc_payment.h”.
(terminal_input_flag) is an optional integer value that indicates whether the ExaDigm terminal
should prompt the user for input whenever possible.
o If the value is set to zero, then the ExaDigm terminal will not prompt the user for input unless
absolutely required (for example, card swipe).
o If the value is set to 1, then the ExaDigm terminal will prompt the user for input whenever
possible, even if the POS sent the appropriate information (for example, cashback amount on
a debit sale).
o If the value is set to 2, then the ExaDigm terminal will display a dialog box that shows the
total, tax and tip, and then show an input box for editing the tip amount before processing the
card information.
o If the parameter is omitted, then zero is assumed and the ExaDigm terminal will avoid
prompting the user for input.
(signature_capture_flag) is an optional integer value that indicates whether the ExaDigm terminal
should prompt the user to provide a signature during the transaction. If the value is set to zero,
then signature capture is not performed. If the value is set to 1, then the ExaDigm terminal will
display a signature screen and prompt the user to provide a signature; the image of the signature
will then be returned as part of the response messages. If the parameter is omitted, then zero is
assumed and the ExaDigm terminal will not prompt for a signature from the user.
(report_level) is an optional integer value that indicates what level of reporting is to be returned
for messages that can include detail information (e.g. XCRS). A value of zero indicates that only
summary data is requested; a value greater than zero indicates that detail information is
requested in addition to the summary data. If the parameter is omitted, or if the value is not set,
then zero is assumed and the response message will only include summary information.
"<label_1>" … "<label_N>" and "<data_1>" … "<data_N>" elements are used for passing
information to the terminal which will be included in the receipt that the terminal will print. Each
label / data set represents data that will be printed on one line; the label elements will be left-
aligned and the data elements will be right-aligned. If only one element (either label or data) is
included for one line data element, then only that element will be printed for that line (either left-
or right-aligned, depending on which element is included). If the "receiptDetail" object is omitted,
then no detail information will be added to the receipt.
For example, to Perform Credit Sale with a base amount of $50.00 and print two receipts for Credit Sale
transaction with a tax amount of $3.00, the POS would send the following:
{
"packetID":"XCRP",
"packetVersion":"0.0.6",
"packetData":{
"packetAuthorization":"11223344",
"requestID":4,
"baseAmount":5000,
"decimals":2,
"currencyChar":"$",
"receiptCount":2,
"transactionType":1,
"taxAmount":300
}
}
For additional examples of data messages, please refer to section 8.1 on page 40, titled “Semi-Integrated
Message Examples”.
{
"packetID" : "XCRT",
("packetVersion" : "0.0.6",)
"packetData" : {
"transactionDate" : "<transaction_date>",
"transactionTime" : "<transaction_time>",
("hostDate" : "<host_date>",)
("hostTime" : "<host_time>",)
"batchID" : <batch_id>,
"transactionID" : <transaction_id>,
("customID" : {
"label" : "<custom_id_label>"
"data" : "<custom_id_value>"
},)
"baseAmount" : <base_amt>,
"tipAmount" : <tip_amt>,
"cashbackAmount" : <cashback_amt>,
"feeAmount" : <fee_amt>,
"totalAmount" : <total_amt>,
"resultCode" : "<result_code>",
"hostMessage" : "<host_msg>",
"cardNumber" : "<cardno>",
"cardIssuer" : "<card_issuer>",
"cardDataEntry" : "<card_entry>",
"referenceNumber" : "<ref_no>",
"authorizationCode" : "<auth_code>"
("emvTags" : [
"<emv_tag_1>=<emv_value_1>",
"<emv_tag_2>=<emv_value_2>",
…
"<emv_tag_N>=<emv_value_N>"
],)
("signatureImage" : [
"<signature_image_line_1>",
"<signature_image_line_2>",
…
"<signature_image_line_N>"
])
}
}
NOTE: This information is processor dependent, as some hosts do not send this information
under any circumstances.
"(host_time)" is an optional string the represents the transaction time as reported by the host. If
the host did not report a host date and time for the transaction, this data will not be present.
NOTE: This information is processor dependent, as some hosts do not send this information
under any circumstances.
<batch_id> is the terminal batch ID for an approved transaction. If the transaction was not
approved, then this field is empty.
<transaction_id> is the terminal transaction ID for an approved transaction. If the transaction was
not approved, then this field is empty.
"(custom_id_label)" is an optional string that describes the information that is in the value
<custom_id_data>.
"(custom_id_data)" is an optional string that represents an identifier that has been set from the
POS end.
<base_amt> is the base amount to show on the display of the ExaDigm terminal, with all digits
and without decimal point. This amount represents the total amount of sale, including tax, but not
including tips, cashback amount, or any other additional amounts.
<tip_amt> is the tip amount that the user added to the transaction.
<cashback_amt> is the amount in cash that was requested by the customer to receive as part of
the transaction.
<fee_amt> is the amount of any additional fees that were added to the transaction.
<total_amt> is the total amount of the transaction, including all taxes, cashback, tips and fees.
<result_code> is a code that represents the status of the transaction, and is set to one of the
following values5:
o 0 = Transaction approved
o -1 = Transaction declined
o -2 = Error during transaction
o -3 = Transaction canceled
<host_msg> contains any message that may have been sent from the processor gateway to the
ExaDigm terminal during the transaction. If the processor did not send a message, then this field
will be empty.
<cardno> contains the last four digits of the card number used during the transaction.
<card_issuer> is the name of the card's issuer.
<card_entry> is a code that represents the entry method that was used to read the card
information6:
o 0 = Card information not entered
o 1 = Card was swiped through MSR device
o 2 = Card was inserted into EMV reader
o 3 = Card was tapped on NFC reader
o 4 = Card information was read via another method
o 5 = Card was present when card information was keyed in manually
o 6 = Card was not present when card information was keyed in manually
<ref_no> is the reference number that is returned by the host for the transaction. (Please note
that not all processors return this data.) If the transaction was not approved, then this field will be
empty.
<auth_code> contains the host authorization code for the transaction. If the transaction was not
5
The values listed in this table are defined in the enumerated type 'NxPayResultEn' that is defined in the ExaDigm SDK header
file “exaipc_payment.h”.
6
The values listed in this table are defined in the enumerated type 'NxCardEntryEn' that is defined in the ExaDigm SDK header
file “exaipc_payment.h”.
The following example shows the data returned after a successful transaction:
The transaction completed successfully
The transaction ID returned by the processor is 16
A customer-added tip was sent as $10.00, with no cashback and no fee, making the total amount
to be $60.00
The host responded with the message “AUTH/TKT 001572” for a card number with the last 4
digits “5454” that is issued by MasterCard and with an authorization code of 001572
A reference number returned by the host is MTA008016
{
"packetID" : "XCRT",
"packetVersion" : "0.0.6",
"packetData" : {
"batchID":1,
"transactionID":16,
"baseAmount":5000,
"tipAmount":1000,
"cashbackAmount":0,
"feeAmount":0,
"totalAmount":6000,
"resultCode":0,
"hostMessage":"AUTH/TKT 001572",
"cardNumber":"5454",
"cardIssuer":"MasterCard",
"cardDataEntry":1,
"referenceNumber":"001572",
"authorizationCode":"MTA008016"
}
}
If the transaction was declined for the card ending in 0026 with a base amount of $140.00, and no tax, the
ExaDigm terminal would return the following data.
{
"packetID":"XCRT",
"packetVersion":"0.0.6",
"packetData":{
"transactionID":16,
"baseAmount":14000,
"tipAmount":,
"cashbackAmount":,
"feeAmount":,
"totalAmount":14000,
"resultCode":1,
"hostMessage":"DECLINED",
"cardNumber":"0026",
"cardIssuer":"VISA",
"cardDataEntry":1,
"referenceNumber":,
"authorizationCode":
}
}
For additional examples of data messages, please refer to section 8.1 on page 40, titled “Semi-Integrated
Message Examples”.
{
"packetID" : "XCRS",
("packetVersion" : "0.0.6",)
"packetData" : {
"batchID" : <batch_id>,
"batchCount" : <batch_count>,
"batchAmount" : <batch_amount>,
("decimals" : (decimals),)
("currencyChar" : ("currency_char"),)
("reportLevel" : <report_level>)
}
}
{
"packetID" : "XCRS",
("packetVersion" : "0.0.6",)
"packetData" : {
"batchDate" : "<date>",
"batchTime" : "<time>",
"batchID" : <batch_id>,
"batchCount" : <batch_count>,
"batchAmount" : <batch_amount>,
("decimals" : (decimals),)
("currencyChar" : ("currency_char"),)
"resultCode" : "<result_code>",
"hostMessage" : "<host_msg>",
"referenceNumber" : "<ref_no>"
("reportLevel" : <report_level>)
}
}
<host_msg> is the message returned from the processor after the settlement has been run.
(report_level) is an integer value that indicates what level of reporting is being returned with the
summary message. A value of zero indicates that only summary data is being returned; a value
greater than zero indicates that detail information will be sent in a series of XCRZ messages that
will follow the summary data. If the parameter is omitted, or if the value is not set, then zero is
assumed and the response message will only include summary information.
NOTE: The settlement report message is only sent in response to a request for batch summary
information or settlement processing that was received from POS device. If settlement processing is run
manually on the terminal, the settlement report cannot be sent from the ExaDigm terminal to the POS
device.
{
"packetID" : "XCRZ",
("packetVersion" : "0.0.6",)
"packetData" : {
"transactionDate" : "<transaction_date>",
"transactionTime" : "<transaction_time>",
("hostDate" : "<host_date>",)
("hostTime" : "<host_time>",)
"batchID" : <batch_id>,
"transactionID" : <transaction_id>,
("customID" : {
"label" : "<custom_id_label>"
"data" : "<custom_id_value>"
},)
"baseAmount" : <base_amt>,
"tipAmount" : <tip>,
"cashbackAmount" : <cashback_amt>,
"feeAmount" : <fee_amt>,
"totalAmount" : <total_amt>,
"resultCode" : <result_code>,
"hostMessage" : "<host_msg>",
"cardNumber" : "<cardno>",
"cardIssuer" : "<card_issuer>",
"cardDataEntry" : <card_entry>,
"referenceNumber" : "<ref_no>",
"authorizationCode" : "<auth_code>"
("emvTags" : [
"<emv_tag_1>=<emv_value_1>",
"<emv_tag_2>=<emv_value_2>",
…
"<emv_tag_N>=<emv_value_N>"
],)
}
}
NOTE: This information is processor dependent, as some hosts do not send this information
under any circumstances.
"(host_time)" is an optional string the represents the transaction time as reported by the host. If
the host did not report a host date and time for the transaction, this data will not be present.
NOTE: This information is processor dependent, as some hosts do not send this information
under any circumstances.
<batch_id> is the terminal batch ID for an approved transaction. If the transaction was not
approved, then this field is empty.
<transaction_id> is the terminal transaction ID for an approved transaction. If the transaction was
not approved, then this field is empty.
"(custom_id_label)" is an optional string that describes the information that is in the value
<custom_id_data>.
"(custom_id_data)" is an optional string that represents an identifier that was set from the POS.
<base_amt> is the base amount to show on the display of the ExaDigm terminal, with all digits
and without decimal point. This amount represents the total amount of sale, including tax, but not
including tips, cashback amount, or any other additional amounts.
<tip_amt> is the tip amount that the user added to the transaction.
<cashback_amt> is the amount in cash that was requested by the customer to receive as part of
the transaction.
<fee_amt> is the amount of any additional fees that were added to the transaction.
<total_amt> is the total amount of the transaction, including all taxes, cashback, tips and fees.
<result_code> is a code that represents the status of the transaction, and is set to one of the
following values7:
o 0 = Transaction approved
o -1 = Transaction declined
o -2 = Error during transaction
o -3 = Transaction canceled
"<host_msg>" contains any message that may have been sent from the processor gateway to the
ExaDigm terminal during the transaction. If the processor did not send a message, then this field
will be empty.
"<cardno>" is a string that contains the last four digits of the card number used during the
transaction.
"<card_issuer>" is the name of the card's issuer.
<card_entry> is a numeric code that represents the entry method that was used to read the card
information8:
o 0 = Card information not entered
o 1 = Card was swiped through MSR device
o 2 = Card was inserted into EMV reader
o 3 = Card was tapped on NFC reader
o 4 = Card information was read via another method
o 5 = Card was present when card information was keyed in manually
o 6 = Card was not present when card information was keyed in manually
"<ref_no>" is the reference number that is returned by the host for the transaction. (Please note
that not all processors return this data.) If the transaction was not approved, then this field will be
empty.
"<auth_code>" contains the host authorization code for the transaction. If the transaction was not
approved, then this field will be empty.
"<emv_tag_1>=<emv_value_1>" … "<emv_tag_N>=<emv_value_N>" are the EMV tag/value
pairs that were read by the terminal when EMV card data was read, separated by an equal sign
(=). Each tag/value pair's tag is to the left of the equal sign, and the value is to the right of the
equal sign.
7
The values listed in this table are defined in the enumerated type 'NxPayResultEn' that is defined in the ExaDigm SDK header
file “exaipc_payment.h”.
8
The values listed in this table are defined in the enumerated type 'NxCardEntryEn' that is defined in the ExaDigm SDK header
file “exaipc_payment.h”.
{
"packetID" : "XRPT",
("packetVersion" : "0.0.6",)
"packetData" : {
"transactionID" : <request_id>,
"data" : [
"<report_line_1>",
"<report_line_2>",
…
"<report_line_N>"
]
}
}
{
"packetID":"XRPT",
"packetVersion":"0.0.6",
"packetData"{
"transactionID"<request_id>,
"data"[
"<0x0A>",
" Exadigm,Inc <0x0A>",
" 2861 Pullman st <0x0A>",
" Santa Ana, CA <0x0A>",
" 949-486-0320 <0x0A>",
" <0x0A>",
" <0x0A>",
"Device ID: ED12<0x0A>",
"04/06/2016 00:38:51<0x0A>",
"-----------------------------<0x0A>",
" Credit Sale <0x0A>",
"<0x09> APPROVED <0x0A>",
"Batch Number: 7<0x0A>",
"Transaction ID: 44<0x0A>",
"Item num: 36<0x0A>",
"[Mastercard] Swiped<0x0A>",
"Acct#: XXXXXXXXXXXX5454<0x0A>",
"Expiration date: XXXX<0x0A>",
"Auth code: 002302<0x0A>",
"Host Trn ID: MTA007036<0x0A>",
"<0x09>Amount: $9.95<0x0A>",
NOTE: If the print data cannot fit in one message, then the ExaDigm terminal will send the data in
multiple sequential messages to the POS system.
{
"packetID" : "XRSP",
("packetVersion" : "0.0.6",)
"packetData" : {
"status" : "OK"
}
}
{
"packetID":"XRSP",
("packetVersion":"0.0.6",)
"packetData"{
"status" : "ERROR",
("message" : "<msg>")
}
}
{
"packetID":"XRSP",
("packetVersion":"0.0.6",)
"packetData"{
"status" : "END"
}
}
7.1.1 UI Messages
7.2 UI Messages
This section describes the format of the messages related to sending data from a POS device or
application to an ExaDigm terminal for the purpose of displaying information on the terminal screen.
{
"packetID" : "XUID",
("packetVersion" : "0.0.6",)
"packetData" : {
"packetAuthorization" : "<packet_auth>",
("title" : "<dialogbox_title>",)
"message" : [
"<message_line_1>",
"<message_line_2>",
...
"<message_line_N>",
],
("timeout" : <timeout_value>,)
("buttons" : {
("ok" : <ok_button_flag>,)
("cancel" : <cancel_button_flag>)
})
}
}
NOTE: If one or more button values are set so that the terrminal will display one or more buttons at the
bottom of the dialog box, then the terminal will send a XUIR message in response to the user input
selection. On the other hand, if no button values are set, then the terminal will display a modal dialog box
that can only be terminated from the POS by sending a XUIX message to the terminal.
{
"packetID" : "XUII",
("packetVersion" : "0.0.6",)
"packetData" : {
"packetAuthorization" : "<packet_auth>",
("title" : "<inputbox_title>",)
"message" : "<message_text>",
("inputType" : "<input_type>",)
("inputMinLength" : <input_min_length>,)
"inputMaxLength" : <input_max_length>,
("inputDefault" : "<input_default_text>",)
("timeout" : <timeout_value>)
}
}
{
"packetID" : "XUIM",
("packetVersion" : "0.0.6",)
"packetData" : {
"packetAuthorization" : "<packet_auth>",
("title" : "<menu_title>",)
"menu" : [
"<menu_item_1>",
"<message_line_2>",
...
"<menu_item_N>"
],
("timeout" : <timeout_value>,)
}
}
{
"packetID" : "XUIR",
("packetVersion" : "0.0.6",)
"packetData" : {
("button" : "<button_response>",)
("key" : "<key_response>",)
("text" : {
"type" : "<response_type>",
"output" : "<text_response>"
},)
("signatureImage" : [
"<signature_image_line_1>",
"<signature_image_line_2>",
…
"<signature_image_line_N>"
])
}
}
"<response_type>" is a string that indicates what type of data entry is allowed in the input
window:
o "A" = Alphabetic characters only (no numbers)
o "C" = Currency value
o "N" = Numeric characters only (no letters)
o "P" = Password entry (characters are masked during input, making them not viewable)
o "X" = Alphanumeric characters are allowed (letters and numbers)
"<text_response>", if included, returns the text string that was entered by the user into an input
box.
“<signature_image_line_1>” … “<signature_image_line_N>”, if included, is data that represents
the compressed signature image as Base64-encoded data. Each line of data is not to be longer
than 64 characters.
NOTE: The XUIR message only returns a button response, a key response, a text response, or a
signature image; the responses are mutually exclusive.
{
"packetID" : "XUIS",
("packetVersion" : "0.0.6",)
"packetData" : {
"packetAuthorization" : "<packet_auth>",
("title" : "<menu_title>",)
("message" : [
"<message_line_1>",
"<message_line_2>",
...
"<message_line_N>",
],)
("timeout" : <timeout_value>,)
}
}
A POS device terminates a user interface related operation by sending the following message to the
ExaDigm terminal.
{
"packetID" : "XUIX",
("packetVersion" : "0.0.6",)
"packetData" : {
"packetAuthorization" : "<packet_auth>",
}
}
A POS device can send simple plain-text data to an ExaDigm terminal using the XPRP message.
{
"packetID" : "XPRP",
("packetVersion" : "0.0.6",)
"packetData" : {
"data" : [
"<print_line_1>",
"<print_line_2>",
…
"<print_line_N>"
]
}
}
"packetID" : "XSIQ",
("packetVersion" : "0.0.6",)
"packetData" : {
"packetAuthorization" : "<packet_auth>",
("serialNumber" : "<serial_number>",)
("firmwareInfo" : <firmware_info_flag>,)
("appInfo" : <app_info_flag>,)
("ipInfo" : <ip_info_flag>)
}
}
The XSIS message is designed to send information about the terminal to a POS device. There are two
possible trigger events to cause the message to be sent out from the terminal:
The POS device sends an XSIQ message to the terminal; in this case, the terminal sends an
XSIS message in response over the POS-initiated connection in response.
While the terminal’s application is displaying the “wait” screen and waiting for an inbound
message, the user may press the [ENTER] key to signal the terminal to send a status message to
the “attached” POS device.
o In the case of a USB-connected POS, the terminal will send the status message to the device
on the other end of the USB cable
o In the case of an IP-connected POS, the IP address and port of the POS device must have
been configured in the terminal in order for the message to be sent; otherwise, the application
will display a dialog box indicating that the message cannot be sent because the destination
has not been properly configured.
{
"packetID" : "XSIS",
("packetVersion" : "0.0.6",)
"packetData" : {
("serialNumber" : "<serial_number>",)
"semiMode" : "<semi_mode>",
("firmwareInfo" :
{
"bootVersion" : "<bootloader_version>",
"kernelVersion" : "<kernel_version>",
"coreVersion" : "<core_version>",
("userVersion" : "<user_version>")
},)
("appInfo" :
{
"appVersion" : "<application_version>",
"appSlot" : <slot_number>,
},)
("ipInfo" :
{
"device" : "ip_device_type",
"address" : "<ip_address>",
"port" : <ip_port_number>,
})
}
}
WARNING: The card reader messages have been provided for developers who wish to retrieve and
process information from cards that can be read by the terminal. Be advised that if you utilize the card
reader messages to read data from bank issued cards, your application comes into scope for PA-
DSS compliance. This means that your application will need to be PA-DSS certified; otherwise, you will
invalidate the PA-DSS certification provided by the application in the ExaDigm terminal.
The POS system sends the following message to give the ExaDigm terminal an RSA 1024-bit public key
which it can use to encrypt card data in response messages:
{
"packetID" : "XCRK",
("packetVersion" : "0.0.6",)
"packetData" : {
"packetAuthorization" : "<packet_auth>",
"key" : "<key_string>"
}
}
If this message is not sent, or if the message is sent with an empty key value, then the ExaDigm terminal
will be unable to read bank card data. PA-DSS v3.0 requirements 11.1 and 11.2 9 specify that no sensitive
data is to be transmitted in an unencrypted form, so setting the public key is mandatory for handling credit
cards, debit cards, or any other bank issued cards.
9
Requirements and Security Assessment Procedures, version 3.1 (PCI Security Standards Council, May 2015),
https://www.pcisecuritystandards.org/documents/PA-DSS_v3-1.pdf (accessed April 20, 2016)
{
"packetID" : "XCRR",
("packetVersion" : "0.0.6",)
"packetData" : {
"packetAuthorization" : "<packet_auth>",
("message" : "<message>",)
("timeout" : <timeout_value>,)
("decimals" : <decimals>,)
("currencyChar" : "currency_char",)
("baseAmount" : <base_amt>,)
("taxAmount" : <tax_amt>,)
("tipAmount" : <tip_amt>,)
}
}
NOTE: If the public key has not been transmitted to the ExaDigm terminal, the device will assume that
the card is a gift card and process the card accordingly.
Also note that if the total amount has not been transmitted to the ExaDigm terminal, the device will not
look for EMV card data; only MSR or NFC data will be returned.
{
"packetID" : "XCRD",
("packetVersion" : "0.0.6",)
"packetData" : {
"status" : "<status>",
"cardType" : "<card_type>",
("tipAmount" : <tip_amt>,)
("msrData" : [
("track1Data" : "<track_1_data>",)
("track2Data" : "<track_2_data>",)
("track3Data" : "<track_2_data>",)
],)
("emvTags" : [
"<emv_tag_1>=<emv_value_1>",
"<emv_tag_2>=<emv_value_2>",
…
"<emv_tag_N>=<emv_value_N>"
],)
}
}
(status) is a 2-character code that indicates the status of the read operation. If the status
indicates anything other than a successful read, then the remaining fields will not be present.
'00' = Data read successfully (and user accepted total amount)
'01' = Reading operation timed out
'02' = User canceled reading operation
'03' = User did not accept total amount
'99' = Error occurred during reading operation
(card_type) is a 1-character code that indicates the card type that was read:
'0' = MSR card
'1' = NFC card
'2' = EMV card (contact)
'3' = EMV card (contactless)
<tip_amt> is the tip amount that the user added to the transaction.
"<track_1_data>" ... "<track_3_data>" are Base64-encoded strings that represent the data read
from each specified track. If the data element is empty or missing for a specified track, then no
data was read from that track.
"<emv_tag_1>=<emv_value_1>" … "<emv_tag_N>=<emv_value_N>" are the EMV tag/value
pairs that were read by the terminal when EMV card data was read, separated by an equal sign
(=). Each tag/value pair's tag is to the left of the equal sign, and the value is to the right of the
equal sign.
NOTE: If an RSA 1024-bit public key was sent to the terminal, the MSR track data will be encrypted with
that public key. In such cases, the POS device must decrypt the data using the paired private key.
NOTE: The actual prompts and menus may not be exactly same as given in the following examples, as
they will depend on the application as well as the ExaDigm terminal model.
{
"packetID":"XCRP",
"packetVersion":"0.0.6",
"packetData":{
"packetAuthorization":"987pjasd4687",
"requestID":1,
"baseAmount":0,
"taxAmount":0
}
}
After receiving the ‘XCRP’ message, the ExaDigm terminal displays the application’s main menu with
menu options similar to the following:
1.Credit Menu
2.Debit Menu
3.End Of Day
4.EBT Menu
5.Void
6.Admin
7.Reprint
8.Store and Forward
After having performed transactions, when the user cancels out of the main menu, the ExaDigm terminal
would send the following message in response with details of the last transaction performed:
{
"packetID":"XCRT",
"packetVersion":"0.0.6",
"packetData":{
"batchID":0,
"transactionID":0,
"baseAmount":0,
"tipAmount":0,
"cashbackAmount":0,
"feeAmount":0,
"totalAmount":0,
"resultCode":0,
"hostMessage":"",
"cardNumber":"",
"cardIssuer":"",
"cardDataEntry":0,
"referenceNumber":"",
"authorizationCode":""
}
}
{
"packetID":"XCRP",
"packetVersion":"0.0.6",
"packetData":{
"packetAuthorization":"987pjasd4687",
"requestID":2,
"baseAmount":0,
"taxAmount":0
}
}
After receiving ‘XCRP’ message, ExaDigm terminal will display the “Admin” menu similar to:
1.App Setup
2.NetworkMngt
3.User Manager
4.DownloadMngt
5.System
After the user performs admin functions and exits the admin menu by pressing the [CANCEL] key, the
ExaDigm terminal would send the following response:
{
"packetID":"XCRT",
"packetVersion":"0.0.6",
"packetData":{
"batchID":0,
"transactionID":0,
"baseAmount":0,
"tipAmount":0,
"cashbackAmount":0,
"feeAmount":0,
"totalAmount":0,
"resultCode":0,
"hostMessage":"",
"cardNumber":"",
"cardIssuer":"",
"cardDataEntry":0,
"referenceNumber":"",
"authorizationCode":""
}
}
{
"packetID":"XCRP",
"packetVersion":"0.0.6",
"packetData":{
"packetAuthorization":"987pjasd4687",
"requestID":3,
"baseAmount":0,
"taxAmount":0
}
}
After receiving the ‘XCRP’ message or the request from the POS system, the ExaDigm application
prompts the user with the message “Print Report?”. If the user selects [ENTER], the application prints the
batch report of transaction details. Then the application prompts the user with the message “Confirm
Settlement?”. If the user selects [ENTER], the device connects to the processor and settles the batch.
If the batch settlement is successful, the ExaDigm terminal would respond with a message like the
following:
{
"packetID":"XCRS",
"packetVersion":"0.0.6",
"packetData":{
"batchDate":"2017/10/31",
"batchTime":"04:44",
"batchID":2,
"batchCount":0,
"batchAmount":300,
"decimals":2,
"currencyChar":"",
"resultCode":0,
"hostMessage":"CLOSE: 3.00",
"referenceNumber":"000009131009030320",
"reportLevel":0
}
}
{
"packetID":"XCRP",
"packetVersion":"0.0.6",
"packetData":{
"packetAuthorization":"987pjasd4687",
"requestID":6,
"baseAmount":0,
"transactionID":1,
"taxAmount":0
}
}
After receiving ‘XCRP’ message, the ExaDigm terminal prompts the user to enter the transaction ID to
print the receipt. After printing the receipt, the ExaDigm terminal would send a response like the
following:
{
"packetID":"XCRT",
"packetVersion":"0.0.6",
"packetData":{
"batchID":3,
"transactionID":1,
"baseAmount":1000,
"tipAmount":0,
"cashbackAmount":0,
"feeAmount":0,
"totalAmount":1000,
"resultCode":0,
"hostMessage":"AUTH/TKT 000547",
"cardNumber":"0026",
"cardIssuer":"[Visa]",
"cardDataEntry":1,
"referenceNumber":"MTA015547 ",
"authorizationCode":"000547"
}
}
{
"packetID":"XCRP",
"packetVersion":"0.0.6",
"packetData":{
"packetAuthorization":"987pjasd4687",
"requestID":7,
"baseAmount":0,
"taxAmount":0
}
}
The ExaDigm terminal prompts the user to select the report type:
1.Detail
2.Condensed
3.Totals Only
Depending on user input, the ExaDigm terminal prints batch report categorized by card type.
After user cancels out of the menus, the ExaDigm terminal would send the following response:
{
"packetID":"XCRT",
"packetVersion":"0.0.6",
"packetData":{
"batchID":0,
"transactionID":0,
"baseAmount":0,
"tipAmount":0,
"cashbackAmount":0,
"feeAmount":0,
"totalAmount":0,
"resultCode":0,
"hostMessage":"",
"cardNumber":"",
"cardIssuer":"",
"cardDataEntry":0,
"referenceNumber":"",
"authorizationCode":""
}
}