Capms MD

micros Systems, Inc.
3700 POS
CA/EDC PMS Interface Specifications Manual
Copyright 2000-2002
MICROS Systems, Inc.
Columbia, MD USA
All Rights Reserved
Part Number: 150502-070

Declarations
Declarations
Warranties
Although the best efforts are made to ensure that the information in this
manual is complete and accurate, MICROS Systems, Inc. makes no
warranty of any kind with regard to this material, including but not limited
to the implied warranties of marketability and fitness for a particular
purpose. Information in this manual is subject to change without notice.
MICROS Systems, Inc. shall not be liable for errors contained herein or for
incidental or consequential damages in connection with the furnishing,
performance, or use of this manual.
Non-Disclosure Statement
Information contained in this manual is proprietary and therefore is only
intended for use by MICROS installers, and third-party programmers, who
may use it to develop custom reports, etc. This information must not be
disclosed to MICROS competitors without the express written consent of
MICROS Systems, Incorporated.
Printing History
New editions of this manual incorporate new and changed material since
the previous edition. Minor corrections and updates may be incorporated
into reprints of the current edition without changing the date or the edition
number.
Edition Month Year Software Version
1st July 2000 1.00

2nd June 2002 3.10
ii
Table of Contents
Table of Contents
Why Read This Manual? ............................................................................................................... v
How This Manual is Organized .................................................................................................. vi
Overview of CA/EDC PMS Interface .......................................................................................... 1
Message Formats ............................................................................................................................ 2
POS Source ID Segment ..................................................................................................... 2
Applications Sequence Segment ......................................................................................... 3
Applications Data Segment ................................................................................................. 3
Checksum Field................................................................................................................... 4
Interfaces......................................................................................................................................... 5
Asynchronous Serial Interface ............................................................................................ 5
TCP Interface ...................................................................................................................... 6
Messages .......................................................................................................................................... 7
Messages Fields .................................................................................................................. 7
Field Types and Sizes .......................................................................................................... 7
Message Types .................................................................................................................... 8
Credit Authorization Process .............................................................................................. 9
Batch Settlement Process .................................................................................................. 12
Interface Considerations.............................................................................................................. 21
Full Duplex Messages ....................................................................................................... 21
Multiple Authorization Requests From a Workstation ..................................................... 21
Redundant Connections .................................................................................................... 21
Charge Backs and Credit Card Inquiries........................................................................... 21
ABA Track 1 Information ................................................................................................. 21
Zero Payment Records ...................................................................................................... 22
Appendix ....................................................................................................................................... 23
3700 POS CA/EDC PMS Interface Specification iii

Table of Contents
iv
Why Read This Manual?
Why Read This Manual?
Purpose
The 3700 CA/EDC PMS Interface Specification Manual provides the
information necessary to develop a communication interface between the
PMS and the MICROS 3700 System for the purpose of performing Credit
Authorization and Settlement procedures.
Who Should Use This Manual

This manual is designed for software engineers, or programmers, who are
designing the interface between a PMS System and the 3700 HMS System.
3700 POS CA/EDC PMS Interface Specification v

How This Manual is Organized
How This Manual is Organized

This manual is divided into the five sections and appendix described below.
Interface Overview
This section contains a brief description of the CA/EDC PMS Interface and
its features.
Message Formats
This section describes the message formats for asynchronous serial and
TCP connections.
Interfaces
This section describes the two interfaces that are supported by the 3700
CA/EDC: the traditional asynchronous serial interface and a TCP-based
interface.
Messages
This section explains message field types and sizes.
Interface Considerations
This section describes certain features that should be considered when
designing a CA/EDC PMS Interface.
Appendix
This appendix provides sample code for the CA/EDC PMS Interface.
vi
Overview of CA/EDC PMS Interface
Overview of CA/EDC PMS Interface

The purpose of this interface is to allow a MICROS 3700 POS System to
authorize credit card transactions and perform Electronic Draft Capture via
a Property Management System (PMS). The interface may be achieved
using a traditional asynchronous serial connection (typically RS232), or a
LAN-based TCP/IP connection. In either case, the connection is between
the PMS and a 3700 PC-based Windows server. This connection handles
messages for all of the 3700 POS terminals. The TCP connection may also
be used when the PMS application resides on the same Windows server.
The MICROS 3700, a multi-user system capable of supporting 1 to 300+
POS users, initiates Credit Authorizations and has the ability to print Credit
Authorization vouchers. It also maintains a complete draft capture
database.
When an authorization is requested by a 3700 user, the system will format

a message and send it to the PMS. The PMS, in turn, will process it and
return an appropriate response (approval, decline, etc.) to the 3700. The
3700 maintains the complete payment information, including tip, multiple
authorization codes, and authorized amounts. Periodically (e.g., usually at
the “end of day”), the 3700 will “settle” payments for the previous day by
transferring each payment record to the PMS. This settlement is required
to provide the final payment information, as the guest may have added a
tip. The 3700 also provides features to support PS2000, estimated tips,
secondary floor limits, and manual authorizations.
3700 POS CA/EDC PMS Interface Specification 1

Message Formats
Message Formats
The message formats for both asynchronous serial and TCP connections
are the same. They are sent by both the 3700 and the PMS, and include
three segments:
SOH <POS Source ID> STX <Application Sequence>

<Application Data> ETX <Checksum> EOT
The segments are enveloped using the standard ASCII control characters:
SOH (01H), STX (02H), ETX (03H), and EOT (04H). Also, IBM PC
character codes and an ASCII superset are used throughout to provide
support for international characters.
POS Source ID Segment

The POS source ID segment includes information about the POS User
Workstation that initiates the message as well as interface identification.
The format of this segment is as follows:
Field Length Format Remarks
POS User Workstation 2 or 9 Bytes 2 or 9 ASCII Digits The format (2 or 9) will depend
Number on the 3700 configuration. It may
contain leading spaces or zeros
and is between 1 and 99 or 1
and 999999999.
Interface Name 16 Bytes 16 ASCII Characters Uses IBM PC character set.
2
Message Formats
Applications Sequence Segment

The applications sequence segment comprises a two-digit sequence number
and a retransmission flag. Each POS User workstation application will
increment the sequence number with each message. When a message is
being retransmitted, the same sequence number will be used as the original
message; in addition, a retransmit flag character is provided. The format of
this segment is as follows:
Applications Sequence 2 Bytes 2 ASCII Digits May contain leading spaces or

Number zeros and is between 00 and 99.
Retransmission Flag 1 Byte Space or ‘R’ ‘R’ character (ASCII 52H) is

Character placed in this field if this is a
retransmitted message.
The applications sequence number is initially set to “00” when the

application starts. The application rolls the sequence number back to “01”
after “99.” The receiver should ignore messages from the same User
Workstation that have duplicate sequence numbers.
Applications Data Segment

The applications data segment comprises a message ID field which
identifies the message. In addition to the ID field, a number of other fields
may be included depending upon the nature of the message. These fields
will be separated by an ASCII File Separator character (FS-1CH). These
fields are variable in length and so the FS character should be used to
determine the start of each field. The format is as follows:
<Message ID> FS <Msg Field 1> FS . . . . FS <Msg

Field n>

Message Formats
Checksum Field
The Checksum field is only used when communicating over the
asynchronous serial interface. In the case of TCP interfaces, this field is
ignored and may be omitted. When the Checksum is used, it should be
formatted as follows:
Checksum 4 Bytes 4 ASCII-Hex characters Contains ASCII characters in the

range 30H – 39H and 41H –
46H (0-9 and A-F).
The Checksum is initially set to zero and is the 16-bit binary addition
(excluding parity if applicable) of all characters after, but not including, the
SOH character and through (and including) the ETX character. The
Checksum is then represented as four ASCII-Hex character for
transmission.
4
Interfaces
Interfaces
The 3700 CA/EDC supports two interfaces: the traditional asynchronous
serial interface and a TCP-based interface.
Asynchronous Serial Interface

This interface is defined in the document 1700/2000/3700/4700/8700 PMS
Interface Specifications Manual (MICROS P/N 150502-029). It is a full
duplex interface supporting transmission speeds of 110 to 38,400 baud.
(Refer to the document above for more information about this interface.)
Currently, the CA/EDC Interface must use a separate RS232 connection
from the PMS/SIM Room Charge/Inquiry Interface.
Asynchronous Serial Message Format

The CA/EDC messages are formatted as:

<Applications Data> ETX <Checksum> EOT
The POS application provides a configurable time-out. If this time-out

elapses before a response is received, the message will be re-sent twice.
After three transmissions, the message will be aborted.
Pinging
Both the Asynchronous Serial Interface and the TCP Interface (described
on the following page) have a “keep alive” time-out which is typically in
the order of two hours. To detect a “down” interface more quickly and re-
establish the connection, the CA/EDC Interface will periodically (typically
every five minutes) send a “ping” message to the server. The ping message
is formatted as:
SOH <POS Source ID> STX ETX EOT
The POS ID source segment will contain a null address (the POS User
Workstation number will be zero and the interface name will contain
spaces). The server should detect the message and return it “as is.”

Interfaces
TCP Interface
This interface is designed to be used by Windows and other systems that
are connected using TCP/IP. This interface is LAN-independent and
supports Ethernet, Token Ring, FDDI, Arcnet, PPP, and others. In addition,
this interface may be used by applications that reside on the same Windows
platform as the 3700.
TCP Connection
The CA/EDC Interface connects to the TCP port as a client. The server
should accept TCP connections from the 3700 POS client on port “micros-
ca.” If this service is not defined, port number 5008 should be used as the
default. The CA/EDC messages are formatted as:

<Applications Data> ETX <Checksum> EOT
The Checksum field is ignored and may be omitted in both cases, so that
the EOT character may immediately follow the ETX character.
The POS application provides a configurable time-out. If this time-out

elapses before a response is received, the message will be re-sent twice.
After three transmissions, the message will be dropped and the appropriate
error recovery will be executed. If the receiving system detects an error in
the message or some other applications-related error, it should provide an
appropriate error message response to the POS application.
TCP Interface Code Example

A code sample for this interface is provided in the appendix of this manual.
6
Messages
Messages
This section describes message fields as well as field types and sizes.
Message Fields
Message fields are separated by ASCII File Separator characters (FS-1CH).
The PMS Interface software should access fields by parsing field separators
to find the start of each field. Since fields are not of a fixed length, their
absolute position within a message cannot be guaranteed. When a field is
omitted (because it is either optional or not applicable), the field separator
must still be present.
Field Types and Sizes

The system allows several types of fields to be used; these support numeric,
amount, alphanumeric, and hexadecimal data. In addition, their maximum
size can be defined. The following table shows the field types and their
abbreviations.
Field
Abbreviation Maximum Field Length Description and Remarks
Type
Numeric Nx x bytes plus an addi- These fields are used for numeric information
tional byte for minus sign and may comprise x digits.
if negative Example: N4 supports -9999 to 9999
Leading spaces should be suppressed.
Amount $x x bytes plus additional These fields are used for monetary amounts.
bytes for decimal point They will include a decimal point and may be
and minus sign if nega- preceded by a minus sign. They may comprise
tive x digits.
Example: $4 in the US will support -99.99 to
99.99
Leading spaces should be suppressed.
Alpha- Ax x bytes These fields may include any non-control char-

numeric acter including punctuation marks. They may
comprise x characters.
Hexa- Hx x bytes These fields are used for hexadecimal infor-

decimal mation. Each character will be in the range 0-9
(30H – 39H) and A-F (41H – 46H). They may
comprise x hexadecimal digits. In most cases,
there will be an even number of digits.

Messages
Message Types
The interface supports two categories of messages; those provided to
support the Credit Authorization process and those provided to support the
draft capture or batch settlement process. Typically, authorizations will
occur while food service or retail outlets are open. Depending upon the
installation, these may be open 24 hours a day and therefore require that
Credit Authorization be supported at all times.
Draft capture will most often occur once a day, usually during the “end of
day” process. This interface is designed to allow authorizations to occur
while batch settlement is taking place. However, a facility is also provided
to prevent simultaneous processing for those PMS Systems that cannot
support it.
The following message types supporting authorization and batch settlement

are provided:
Message Message ID Sender Description
Credit Authorization CA_REQ 3700 Message requesting an authorization.

Request
Credit Authorization CA_RSP PMS Message responding to a Credit Authorization

Response request.
Batch Open BO_REQ 3700 Message requesting a new batch be started.

Request
Batch Open BO_RSP PMS Message acknowledging the start of a new batch.
Response
Batch Transfer BX_REQ 3700 Message requesting the transfer of a payment

Request record.
Batch Transfer BX_RSP PMS Message responding to a batch transfer request.

Response
Batch Close BC_REQ 3700 Message requesting that the current batch be
Request closed.
Batch Close BC_RSP PMS Message acknowledging the closure of the current
Response batch.
Batch Inquiry BI_REQ 3700 Message requesting information about the current
Request batch.
Batch Inquiry BI_RSP PMS Message providing information about the current
Response batch.
8
Messages
Credit Authorization Process

The 3700 will send the PMS Credit Authorization request messages. The
PMS System should respond to these requests within a preconfigured time
frame. The response will contain the status of the authorization. The 3700
is a multi-user system, so it is likely that multiple authorization requests
may be sent, each initiated by the same or different workstations, before
the first response is received. It is the responsibility of the PMS to buffer
these requests, if necessary. (This feature has been provided to optimize
performance when fully duplex leased-lines to an acquiring bank or CA
Processor are being used.)

Messages
The authorization request message contains the following fields:
Field Name Field Type Description
Message ID A6 Contains the string “CA_REQ.”
Authorization Sequence N2 An arbitrary sequence number that is returned in the response

Number and used to keep track of multiple outstanding authorizations
from a single workstation.
Merchant ID A16 Contains the Merchant ID associated with this outlet or Reve-
nue Center.
Card Info Format N1 Indicates the format of the credit card information:
1 = ABA track 2 information
2 = ABA track 2 information and guest name field
3 = Manually entered credit card information
4 = Manually entered credit card information with issue number
and start date
Note: Only one set of fields will appear in each message.
Track 2 Card Info A40 ABA specified format including start sentinel (3BH), field sepa-
rator (3DH), and end sentinel (3FH). This field is only present if
the card information is format 1 or 2.
Guest Name A26 Guest name as read from ABA track 1. This field is only
present if the card information is format 2.
Manually Entered Info – N19 Manually entered credit card account number. This field only
Account Number appears if the card information is format 3.
Manually Entered Info – N4 Expiration date formatted as MMYY. This field is only present if
Expiration Date the card information is format 3.
Manually Entered Info – A2 The issue number of the credit card presented for authoriza-
Issue Number1 tion. This field is only present if the driver is configured to
include it (card information is format 4).
Manually Entered Info – N4 The start date of the credit card presented for authorization.
Start Date1 This field is only present if the driver is configured to include it
(card information is format 4).
Amount $8 The amount to be authorized including an estimated tip (if con-

figured).
Revenue Center N3 The revenue center in which the CA was performed.
Guest Check Number2 N6 Guest check number associated with the transaction.
Authorization Date2 N4 Calendar date the transaction was authorized, formatted as

MMDD.
Authorization Time2 N4 Time of day the transaction was authorized, formatted as

HHMM.
1
These fields will be empty if Ops is not configured to prompt for them. (POS Configurator | Sales |
Tender/Media | CC Tender | Prompt for...).
2These fields are only transmitted when the Dollars in the Bank (DITB) option is enabled on the
CA/EDC Drivers | System tab in POS Configurator.
10
Messages
The format of the Credit Authorization response is as follows:
Message ID A6 Contains the string “CA_RSP.”
Authorization Sequence N2 Contains the Authorization Sequence Number from the

Number “CA_REQ” message.
Authorization Status N1 Indicates the authorization status as follows:

1 = Approved
2 = Declined
3 = Referral (Manual Authorization Required)
Authorization Code A6 Ignored if the authorization status is 2 or 3 (decline or referral).
Message A32 Ignored if left blank. This may be used with any response. Typi-
cally used to describe the reason for a decline or a referral. It
may also be used with an approval, in which case the operator
must read the message before continuing.
PMS Discretionary Data A32 May be used to store discretionary information. It is returned to
the PMS during the batch settlement process. Typically, it is
used for storing PS2000-related data elements.
If the PMS System is in the process of settling a batch when an authorization

message is encountered, it should process that authorization. If it cannot, it
should return a “Referral” status and require the POS operator to seek
manual approval.

Messages
Batch Settlement Process

The batch settlement process consists of several phases. First, the batch is
opened, then the payment or draft capture information is transferred, and
finally, the batch is closed. This interface includes mechanisms to allow a
recovery after a failure during the Settlement process. A Batch Inquiry
message has been provided that allows the 3700 to query a PMS to
determine if a batch is open. If it is, the number and value of the records
that have been transferred is provided. The notion of a batch is used to keep
track of the transferred records. It is independent of an Acquiring Bank’s
or Processor’s batch.
There are two batch settlement methods available. If the CA/EDC Interface
is configured for host-based settlement, every record will be marked as
“settled” in the Credit Card Batch immediately following settlement.
If the CA/EDC Interface is configured for terminal-based settlement, all

records are marked as “settled” when a successful response to the Batch
Close command has been received from the PMS System.
12
Messages
Since Settlement is performed centrally on the 3700, the POS workstation

number will be 0 (zero) in all batch-related messages.
The sequence of performing a Settlement is as follows:.
MICROS
PMS Notes
3700
BO_REQ Batch Open checks to see if another batch

BO_RSP is open. It may start a new batch or continue
with the previous batch.
BX_REQ All payment records are transferred.

BX_RSP
BX_REQ
BX_RSP
After all payment records are transferred,
the batch is closed.
BC_REQ
BC_RSP

Messages
In the event the batch settlement process fails, the Batch Inquiry message
is used to recover. An example is provided below.
MICROS
PMS Notes
3700
BO_REQ Batch Open closes any previous batch and

BO_RSP starts a new one.
All payment records are transferred.
BX_REQ
BX_RSP
BX_REQ Failure No response is received.
BI_REQ 3700 performs a batch inquiry to determine

BI_RSP how many records have been received by
the PMS. It then continues from the point at
which the failure occurred.
BX_REQ
BX_RSP After all payment records are transferred,
the batch is closed.
BC_REQ
BC_RSP
14
Messages
Batch Open Messages

The format of the batch open request is as follows:
Message ID A6 Contains the string “BO_REQ.”
If a batch is already open and has associated records, it should be left open
and the number and value of these records should be returned. If no batch
is open, one should be started and the record count and value should be
reset. An error should only be returned if it is not possible to begin the
Settlement process. Please note that if a batch is already open, the 3700
application will report the total (including any existing records) at the end.
The format of the batch open response is as follows:
Message ID A6 Contains the string “BO_RSP.”
Status N1 Indicates the batch status as follows:

1 = Batch opened (record count and value accumulator reset).
2 = Batch already open, record count and value of existing
batch is returned.
3 = Failure — batch cannot be opened.
Number of Records N5 Contains the number of records currently in the open PMS
batch. This field is only present if the status is 2.
Record Value $10 Contains the value of the records currently in the open PMS
batch. This field is only present if the status is 2.
Failure Message A32 Contain a message describing the nature of the failure. This
field is only present if the status is 3.

Messages
Batch Transfer Messages

The following message formats are used to transfer a batch:
Message ID A6 Contains the string “BX_REQ.”
Merchant ID A16 Contains the Merchant ID associated with this outlet or Reve-
nue Center.
Revenue Center Type A2 Contains an arbitrary 2-character field denoting the outlet type
(restaurant, bar, retail, etc.).
Transaction Type N1 Indicates the transaction type as follows:

1 = Sales
2 = Credit
Card Info Format N1 Indicates the format of the credit card information:
1 = ABA track 2 information
2 = ABA track 2 information and guest name field
3 = Manually entered credit card information
4 = Manually entered credit card information with issue number
and start date
Note: Only one set of fields will appear in each message.
Track 2 Card Info A40 ABA-specified format including start sentinel (3BH), field sepa-
rator (3DH), and end sentinel (3FH). This field is only present if
the card information is format 1 or 2.
Guest Name A26 Guest name as read from ABA track 1. This field is only
present if the card information is format 2.
Manually Entered Info – N19 Manually entered credit card account number. This field only
Account Number appears if the card information is format 3.
Manually Entered Info – N4 Expiration date formatted as MMYY. This field is only present if
Expiration Date the card information is format 3.
Manually Entered Info – A2 The issue number of the credit card presented for authoriza-
Issue Number1 tion. This field is only present if the driver is configured to
include it (card information is format 4).
Manually Entered Info – N4 The start date of the credit card presented for authorization.
Start Date1 This field is only present if the driver is configured to include it
(card information is format 4).
Payment Amount $8 The payment amount including tip. This may be zero — refer to
the “Interface Considerations” section.
Tip Amount $8 The tip amount (if appropriate).
Payment Date N4 The payment date in the format MMDD.
Payment Time N4 The payment time in the format HHMM.
1
These fields will be empty if Ops is not configured to prompt for them. (POS Configurator | Sales |
Tender/Media | CC Tender | Prompt for...).
16
Messages
Number of Authoriza- N1 Indicates the number of authorizations (0, 1, or 2).

tions
1st Authorization Type N1 Indicates the 1st authorization type as follows:

1 = Electronic
2 = Manual
Note: This field will not be presented if there were no authoriza-
tions.
1st Authorization Code A6 The code associated with the first authorization.
Note: This field will not be presented if there were no authoriza-
tions.
1st Authorization $8 The amount associated with the first authorization.

Amount Note: This field will not be presented if there were no authoriza-
tions.
Discretionary Data A32 Discretionary data (e.g., PS2000) associated with the first
Associated with the 1st authorization.
Authorization Note: This field will not be present if there were no authoriza-
tions.
2nd Authorization Type N1 Indicates the 2nd authorization type as follows:

1 = Electronic
2 = Manual
Note: This field will not be presented if there was no second
authorization.
2nd Authorization Code A6 The code associated with the second authorization.
Note: This field will not be presented if there was no second
authorization.
2nd Authorization $8 The amount associated with the second authorization.

Amount Note: This field will not be presented if there was no second
authorization.
Discretionary Data A32 Discretionary data (e.g., PS2000) associated with the second
Associated with the 2nd authorization.
Authorization Note: This field will not be presented if there was no second
authorization..
Guest Check Number N6 The guest check number.
Employee Number N9 The number of the employee performing the payment.
Revenue Center Num- N3 The revenue center in which the payment was performed.
ber

Messages
The format of the batch transfer response is as follows:
Message ID A6 Contains the string “BX_RSP.”
Status N1 Indicates the batch status:

1 = Transfer Accepted
2 = Transfer Failure
Failure Message A32 Contain the reason for the failure. This field will only be present
when a batch transfer fails.
18
Messages
Batch Close Messages

The following messages are used to close a batch:
Message ID A6 Contains the string “BC_REQ.”
The format of the batch close response is as follows:
Message ID A6 Contains the string “BC_RSP.”
Status N1 Indicates the batch status as follow:

1 = Batch Closed
2 = Failure (batch cannot be closed)
Number of Records N5 Contains the number of records in the closed batch. The field is
only present if the status is 1.
Record Value $10 Contains the value of the records currently in the closed PMS
batch. The field is only present if the status is 1.
Failure Message A32 Contain a message describing the nature of the failure. This
field is only present if the status is 2.
The 3700 application software will report the value and number of records
in the closed batch.

Messages
Batch Inquiry Messages

The following message formats are used for batch inquiries:
Message ID A6 Contains the string “BI_REQ.”
The batch inquiry response is formatted as follows:
Message ID A6 Contains the string “BI_RSP.”
Status N1 Indicates the batch status as follows:

1 = Batch Open
2 = No Open Batch
Number of Records N5 Contains the number of records currently in the open or last
PMS batch.
Record Value $10 Contains the value of the records currently in the open or last
PMS batch.
The Batch Inquiry command may be sent at any time and used during
diagnostics to troubleshoot Settlement problems.
20
When designing the interface between the 3700 and PMS Systems, the
following features should be considered.
Full Duplex Messages

Authorization request messages may be received before a previous request
has been authorized. This may require buffering to be implemented on the
PMS.
Multiple Authorization Requests From a Workstation

Since the 3700 System may have many workstations active at the same
time, it is possible for the 3700 to send multiple authorization requests from
different workstations prior to receiving an authorization response to the
first request.
Redundant Connections
The 3700 supports redundant connections to maximize system availability
through Backup Server Mode (BSM).
Charge Backs and Credit Card Inquiries

The 3700 System can support operator inquiries and may be configured to
save historical credit card transaction information for this purpose.
ABA Track 1 Information

The 3700 UWS/3 Touchscreen terminals support the reading of track 1 and
track 2 information. The card holder’s name is extracted from track 1 and
passed to the PMS. As an option, it may also be printed on the guest’s Credit
Card Voucher.

Zero Payment Records

The MICROS 3700 CA/PMS Driver may be configured to include or
discard zero payment records when creating a Credit Card Batch. A zero
payment record is created when a Credit Authorization is approved, but the
net payment tendered against that authorization is zero. This situation may
occur if a customer decides to pay cash after the Credit Authorization has
occurred, or if a credit card tender has been voided after an approved
authorization.
The PMS System may use these zero payment records to cancel an existing
authorization record or to clear a customer’s credit for the amount of the
authorization.
Alternatively, the MICROS 3700 CA/PMS Driver may be configured to

discard zero payment records, so they will not appear in the Credit Card
Batch File, and therefore will not be settled to the PMS System.
22
Appendix
Appendix
This appendix includes sample code designed for the CA/EDC PMS
Interface.
/*
* MICROS CA/PMS TCP Server
*
* This code implements a server process that accepts CA/PMS messages
* from the MICROS CA/PMS driver, which acts as client process over a
* TCP link.
* This sample code is written for UNIX System V using the AT&T SVID
* Transport Layer Interface (TLI) API. It should be easily portable
* to the X/Open Transport Interface (XTI). Porting to a
* Berkeley-style socket library is left as an exercise for the
* reader.
*
*/
#include <stdio.h>
#include <fcntl.h>
#include <signal.h>
#include <sysexits.h>
#include <sys/types.h>
#include <netdb.h>
#include <tiuser.h>
#include <stropts.h>
#include <arpa/inet.h>
#include <sys/socket.h>
#include <sys/netinet/in.h>
extern int t_errno;
/* operating-system specific device name: */

#define TCP_DEVICE_NAME “/dev/inet/tcp”
/* define CA/PMS TCP service: */

#define CA_SERVICE_NAME “micros-ca”
#define CA_SERVICE_TYPE “tcp”
#define DEFAULT_CA_PORT 5008
#define MAX_MSG 32767

#define MAX_MSG_BODY (32767 – 25 — 4 — 4)
/* supplied by vendor: */
extern void process_pos_request (const char *header,
const char *body,
char reply_body [MAX_MSG_BODY]);

Appendix
/* supplied below: */
static void transfer_pos_messages (int fd);
void run_server (void)

{
int listen_fd, conn_fd;
struct sockaddr_in *sin;
struct servent *servp;
struct t_bind *bind;
struct t_call *call;
u_short serviceport;
int retries;
/* Open a TCP server endpoint in order to listen for

* requests from POS client processes.
*
* If the requested address is in use, retry up to 10 times.
* This can occur if another server was running on the same
* address, and the TCP port has not yet completed its shutdown
* processing.
*/
if ((servp = getservbyname(CA_SERVICE_NAME, CA_SERVICE_TYPE)) ==

NULL)
serviceport = htons (DEFAULT_CA_PORT);
else
serviceport = (u_short) servp->s_port;
retries = 10;
while (retries--) {
if ((listen_fd = t_open(TCP_DEVICE_NAME, O_RDWR, NULL)) < 0) {

t_error(“run_server: t_open”);
exit(EX_OSFILE);
}
if ((bind = (struct t_bind *)t_alloc(listen_fd, T_BIND, T_ALL))

== NULL) {
t_error(“run_server: t_alloc(T_BIND)”);
t_close(listen_fd);
exit(EX_OSERR);
}
sin = (struct sockaddr_in *) bind->addr.buf;

sin->sin_family = AF_INET;
sin->sin_addr.s_addr = INADDR_ANY;
sin->sin_port = serviceport;
bind->addr.len = sizeof *sin;
bind->glen = l;
24
Appendix
if (t_bind(listen_fd, bind, bind) < 0 {

t_error(“run_server: t_bind”);
t_close(listen_fd);
exit(EX_OSERR);
}
if (sin->sin_port != serviceport) {
fprintf(stderr,
“run_server: wanted port %d, got port %d, retrying\n”,
ntohs(serviceport), ntohs(sin->sin_port));
t_close(listen_fd);
t_free((char *)bind, T_BIND);
sleep(10);
}
else
break;
if (retries == 0) {
fprintf(stderr, “run_server: could not get port %d\n”,
ntohs(serviceport));
t_close(listen_fd);
exit(EX_TEMPFAIL);
}
if ((call = (struct t_call *)t_alloc(listen_fd, T_CALL, T_ALL)) ==

NULL) {
t_error(“run_server: t_alloc(T_CALL)”);
t_close(listen_fd);
exit(EX_OSERR);
}
/* For simplicity, we ignore SIGCLD, which allows the existing

* child processes to clean up after themselves, without
* requiring the parent (this process) to call wait().
*/
sigignore(SIGCLD);
/* We now have the desired TCP port open.

* Accept connections, and for each connection accepted,
* start a server process.
*/
while (1) {
/* Listen for incoming connections.

* This process will typically spend 99.9% of its time
* blocked in this t_listen() call.
*/

Appendix
if (t_listen(listen_fd, call) < 0) {

t_error(“run_server: t_listen”);
t_close(listen_fd);
exit(EX_OSERR);
}
/* Open a new endpoint and accept the connection

* on this new endpoint (freeing the listen_fd
* to accept further connections).
*/
if ((conn_fd = t_open(TCP_DEVICE_NAME, O_RDWR, NULL)) < 0) {

t_error(“run_server: t_open”);
t_close(listen_fd);
exit(EX_OSFILE);
}
if (t_bind(conn_fd, NULL, NULL) < 0) {

t_error(“run_server: t_bind”);
t_close(conn_fd);
t_close(listen_fd);
exit(EX_OSERR);
}
if (t_accept(listen_fd, conn_fd, call) < 0) {

if (t_errno == TLOOK) {
/* retrieve disconnect indication, if any, and
* continue
*/
t_rcvdis(listen_fd, NULL);
t_close(conn_fd);
}
else {
t_error(“run_server: t_accept”);
t_close(conn_fd);
t_close(listen_fd);
exit(EX_OSERR);
}
}
else {
/* Push the “tirdwr” module onto the connection,

* establishing the “read/write” interface. This is so the
* rest of this process does not have to understand
* the more complicated TLI scheme for pushing messages,
* and can treat this connection just like
* a tty. (Let the streams module do the work.)
*
* After this succeeds, no TLI calls can be made on conn_fd,
* only read(), write(), and close().
*/
26
Appendix
if(ioctl(conn_fd, I_PUSH, “tirdwr”) < 0) {

perror(“run_server: ioctl(I_PUSH, tirdwr)”);
t_close(conn_fd);
t_close(listen_fd);
exit(EX_OSERR);
}
/* Start a child process, which will use conn_fd.

* The parent will close conn_fd and return to
* listening. If the fork fails, we will discard
* this connection, but continue to listen,
* since the situation should clear up eventually.
*/
switch(fork()) {
case -1: /* error */

perror(“run_server: fork”);
close(conn_fd);
break;
default: /* parent */
close(conn_fd);
break;
case 0: /* child */
t_close(listen_fd);
transfer_pos_messages(conn_fd);
exit(EX_OK);
break;
}
}
}
}
#define SOH 1
#define STX 2
#define ETX 3
#define EOT 4
#define ACK 6
#define NAK 21
enum Link_State { msg_begin, msg_id, msg_data, msg_cksum };
static void transfer_pos_messages(int fd)

{
int i, n;
int msg_buf_len;
char *header, *body;
enum Link_State state;
char msg_buf[MAX_MSG + 1];
char recv_buf[MAX_MSG + 1];

Appendix
char reply_buf[MAX_MSG + 1];

char reply_body[MAX_MSG_BODY];
/* Handle input from POS system, implementing the network protocol:

* 1. Attempt to read bytes from POS connection, blocking.
* 2. If an invalid message is received, discard it.
* 3. When a complete message is available, call
* process_pos_request,
* passing the received header, the received body,
* and a buffer for the reply.
* 4. When process_pos_request returns, reply to the POS
* connection with a copy of the received header and
* the reply buffer returned from process_pos_request.
*/
state = msg_begin;
msg_buf_len = 0;
#define NEXT_STATE(prev,next) (state == (prev) \

? (state = (next), 1) \
: (state = msg_begin, 0))
#define STATE_ERROR { msg_buf_len = 0; state = msg_begin; }
while (1) {
n = read(fd, recv_buf, MAX_MSG);
if (n < 0 && errno == EINTR)

continue; /* ignore interrupts, read again */
if (n < 0) {
perror(“transfer_pos_messages: read”);
close(fd); /*this connection is finished */
return;
}
if (n == 0) {
fprintf(stderr, “transfer_pos_messages; connection closed\n”);
close(fd); /* this connection is finished */
return;
}
for(i = 0; i < n; i++) {
switch(recv_buff[i]) {
case SOH:
if(NEXT_STATE(msg_begin, msg_id)) {
/* Restart message, and, for clarity,
* remember the position of the (upcoming) first
* byte of the header.
28
Appendix
*/
msg_buf_len = 0;
header = &msg_buf[msg_buf_len];
}
else
STATE_ERROR
break;
case STX:
if(NEXT_STATE(msg_id, msg_data)) {
/* NUL-terminate header, and remember the position
* of the (upcoming) first byte of the body
*/
msg_buf[msg_buf_len++] = ‘\0’;
body = &msg_buf[msg_buf_len];
}
else
STATE_ERROR
break;
case ETX:
if (NEXT_STATE(msg_dta, msg_cksum)) {
/* NUL-terminate the body. */
msg_buf[msg_buf_len++] = ‘\0’;
}
else
STATE_ERROR
break;
case EOT:
if (NEXT_STATE(msg_cksum, msg_begin)) {
int_reply_len;
reply_body[0] = ‘\0’;
/* If body exists,
* send request to CA/PMS-specific code.
* header[0] through NUL is the header.
* body[0] through NUL is the request body.
* reply_body[0] through NUL will be the
* reply body.
* (If body is empty, return empty response to POS.)
*/
if body[0] != ‘\0’)
process_pos_request(header, body, reply_body);
/* Frame original header and reply body,

* and respond to the POS system.
*/

Appendix
sprintf(reply_buf, “%c%s%c%s%c%c”,
SOH, header, STX, reply_body, ETX, EOT);
reply_len = strlen(reply_buf);
if (write(fd, reply_buf, reply_len) != reply_len {
perror(“transfer_pos_messages: write”);
close(fd);
return;
}
}
else
STATE_ERROR
break;
case ACK:
case NAK:
/* Ignore ACKs and NAKs */
break;
default:
switch(state) {
case mag_begin:
case mag_cksum:
default:
break;
case mag_id:
case msg_data;
msg_buf[msg_buf_len++] = recv_buf[i];
break;
break;
}
break;
}
}
}
}
30

Capms MD

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Capms MD

Uploaded by

Copyright:

Available Formats

micros Systems, Inc.

Part Number: 150502-070

Edition Month Year Software Version

1st July 2000 1.00

3700 POS CA/EDC PMS Interface Specification iii

Why Read This Manual?

Who Should Use This Manual

3700 POS CA/EDC PMS Interface Specification v

How This Manual is Organized

Overview of CA/EDC PMS Interface

When an authorization is requested by a 3700 user, the system will format

3700 POS CA/EDC PMS Interface Specification 1

SOH <POS Source ID> STX <Application Sequence>

POS Source ID Segment

Field Length Format Remarks

Interface Name 16 Bytes 16 ASCII Characters Uses IBM PC character set.

Applications Sequence Segment

Field Length Format Remarks

Applications Sequence 2 Bytes 2 ASCII Digits May contain leading spaces or

Retransmission Flag 1 Byte Space or ‘R’ ‘R’ character (ASCII 52H) is

The applications sequence number is initially set to “00” when the

Applications Data Segment

<Message ID> FS <Msg Field 1> FS . . . . FS <Msg

3700 POS CA/EDC PMS Interface Specification 3

Field Length Format Remarks

Checksum 4 Bytes 4 ASCII-Hex characters Contains ASCII characters in the

Asynchronous Serial Interface

Asynchronous Serial Message Format

SOH <POS Source ID> STX <Application Sequence>

The POS application provides a configurable time-out. If this time-out

SOH <POS Source ID> STX ETX EOT

3700 POS CA/EDC PMS Interface Specification 5

SOH <POS Source ID> STX <Application Sequence>

The POS application provides a configurable time-out. If this time-out

TCP Interface Code Example

Field Types and Sizes

Alpha- Ax x bytes These fields may include any non-control char-

Hexa- Hx x bytes These fields are used for hexadecimal infor-

3700 POS CA/EDC PMS Interface Specification 7

The following message types supporting authorization and batch settlement

Message Message ID Sender Description

Credit Authorization CA_REQ 3700 Message requesting an authorization.

Credit Authorization CA_RSP PMS Message responding to a Credit Authorization

Batch Open BO_REQ 3700 Message requesting a new batch be started.

Batch Transfer BX_REQ 3700 Message requesting the transfer of a payment

Batch Transfer BX_RSP PMS Message responding to a batch transfer request.

Credit Authorization Process

3700 POS CA/EDC PMS Interface Specification 9

The authorization request message contains the following fields:

Field Name Field Type Description

Message ID A6 Contains the string “CA_REQ.”

Authorization Sequence N2 An arbitrary sequence number that is returned in the response

Amount $8 The amount to be authorized including an estimated tip (if con-

Revenue Center N3 The revenue center in which the CA was performed.

Authorization Date2 N4 Calendar date the transaction was authorized, formatted as

Authorization Time2 N4 Time of day the transaction was authorized, formatted as

The format of the Credit Authorization response is as follows:

Field Name Field Type Description

Message ID A6 Contains the string “CA_RSP.”

Authorization Sequence N2 Contains the Authorization Sequence Number from the

Authorization Status N1 Indicates the authorization status as follows:

Authorization Code A6 Ignored if the authorization status is 2 or 3 (decline or referral).

If the PMS System is in the process of settling a batch when an authorization