PayFacto API v1.3.9 (STP Installer) - STPI/STP - Main

STPI - POS Interface

Secure Table Pay Interface (STPI) is a middleware solution that communicates between payment devices running our software (SecureTable & SecurePay) and various POS systems. This document only contains information pertaining to the integration details that must be implemented on the POS side for STPI to be able to communicate with it.

Contents

📜 Document Revision History ⚠️ Legal Notice ❓ Overview 📋 Transactions Supported 📊 Field Reference (Appendix A)

📜

Document Revision History

Date	Description
2008-11-05	Version 1.0
2009-01-28	Refined the xml
2009-04-25	1) Added terminal serial no attribute in ident tag to identify the originating CAT terminal to POS. 2) Added 5-digit header length to request and responses to aid in receiving the whole message
2009-05-07	Update the response messages
2009-05-15	Corrected EDC info
2009-06-02	Corrected Apply payment information
2009-06-08	Fixed QA defects
2017-02-06	1) Removed Print Check 2) Updated the 'res' parameter definition to pass valid error codes
2020-05-20	1) TGI rebranded to STPI 2) Add new features
2021-07-29	Moved document to confluence
2021-10-12	Update optional POSVer attribute from POS

⚠️

Legal Notice

⚠️

This document and the information within are the property of PayFacto Payments Inc. (“PayFacto”) and may only be used for the purpose for which they are intended and supplied. Reproduction of this document or use of the information within, in whole or in part, is strictly prohibited without the express written consent of PayFacto. PayFacto reserves the right to revise this document and to periodically make changes to the content hereof, without obligation of PayFacto to notify any person or organization of such revision or changes.

❓

Overview

Security

All communications between STPI and the POS are sent over TCP/IP SSL connections.

Message Format

Messages sent to and from STPI are expected to be in XML. The messages must be padded with a 5-digit header indicating the length of the XML.

POS Implementation expectations

All requests and responses contain the <Ident> tag with attributes id and ttype where id refers to the unique identifier for this request and ttype refers to the transaction type of this request. The responses should echo back this tag with attribute values in the request so that STPI can map the response to the particular request.

All requests and responses contain the <POSDefaultInfo> tag with attributes server, table, check, track2, res and rtext. These should be present in all requests depending on transaction type except res and rtext which should be present in all responses.

The POS server should be a multi-threaded application as more than one request can come at the same time. The server is expected to respond to them within a reasonable time frame. In a typical busy restaurant, it is possible that more than 20 terminals could be sending requests at the same time.

Example Messages

More sample requests & responses will be shown further in the document. The following examples are just to showcase the 5-digit length header. The POS will receive a request message with an XML root element of POSRequest. The POS is expected to respond with a response message with an XML root element of POSResponse.

Sample Request

XML

00139<POSRequest><Ident id='1234' ttype='45' termserialno='2123'/><POSDefaultInfo server='200' table='0' track2='1191' check='0' /></POSRequest>

Sample Response

XML

00478<POSResponse><Ident id='345' ttype='45'/><POSDefaultInfo server='25' table='3' check='45' res='1' rtext='success'/><Checks><Check tableno='24' tablename='bar1' chkname='145' chkno='340' amt='450' tax='24'/><Check tableno='24' tablename='bar1' chkname='245' chkno='440' amt='550' tax='44'/><Check tableno='25' tablename='bar2' chkname='146' chkno='341' amt='450' tax='88'/><Check tableno='28' tablename='bar4' chkname='745' chkno='740' amt='750' tax='66'/></Checks></POSResponse>

📋

Transactions Supported

These are the available transactions:

Get tables
Apply payment
Get Check Info
Lock
Unlock

Get Tables

Getting tables is initiated when the server is trying to list the tables on their payment device. STPI client will communicate to the POS and request this information.

Request

The ttype for getting tables is 45.

If the request message contains the table number, the POS should return information for that table only.

If the request message contains the table number and check number, the POS should return information for that check only.

Response

The response contains a nested structure of table and check information.

Voidable Checks

When a Check xml element contains the refno attribute, this means that existing check has already been paid and that the POS has indicated that it can be voided.

Voided checks do not return a tax value, as the amt attribute is expected to be inclusive of that amount.

The check XML element has the following details

refno - The reference number needed to void the check from the payment application (Max length of 50 characters)
paymentnum - In the case of multiple payments on a given check number, subsequent payments will have a payment number of 2 and greater, with the first being 1.
termserialno - The serial number of the terminal which was originally used to pay. This can be important for some payment applications as a void might only be possible from the same device.

Sample Request XML

XML

<POSRequest>
<Ident id="1234" termserialno="45686968" ttype="45" ver="460" />
<POSDefaultInfo server="200" table="0" check="0" track2="" />
</POSRequest>

Sample Response XML

XML

<POSResponse>
<Ident id="345" termserialno="45686968" ttype="45" POSVer="7.08.000.380"/>
<POSDefaultInfo server="25" res="1" rtext="success" />
<Checks>
<Check tableno="24" tablename="bar1" chkname="145" chkno="350" amt="450" tax="24" />
<Check tableno="24" tablename="bar1" chkname="245" chkno="440" amt="250" tax="44" />
<Check tableno="25" tablename="bar2" chkname="146" chkno="341" amt="250" tax="88" />
<Check tableno="28" tablename="bar4" chkname="745" chkno="740" amt="450" tax="66" />
<Check tableno="24" tablename="bar1" chkname="147" chkno="340" amt="350" tax="24" />
<Check tableno="24" tablename="bar1" chkname="245" chkno="450" amt="450" tax="44" />
<Check tableno="10" tablename="bar5" chkname="123" chkno="234" amt="850" refno="12345" paymentnum="1" termserialno="45686968"/> <!-- VOIDABLE CHECK EXAMPLE-->
</Checks>
</POSResponse>

Apply Payment

Applying the payment is initiated when the payment device is ready to apply the payment for a check.

Request

The ttype for applying payments is 46.

If edc is greater than 0, the POS should authorize with information provided and return the receipt and other miscellaneous details as outlined.

If edc is equal to 0, the POS should not return a receipt as the payment receipt is already printed on the payment device. If the receipt is returned in the response it should be formatted as shown in the example below. An Auth xml element will also be provided in the request containing the authorization code.

If refno is provided within the Payment element, that is the reference number for a voided transaction.

Sample Request XML for EDC = 1

XML

<POSRequest>
<Ident id="1235" termserialno="45686968" ttype="46" />
<POSDefaultInfo server="200" table="60" check="11036" />
<Payment pamt="400" tamt="050" cback="100" schrg="100" cardType="2" acct="4008000123456781" exp="1009" track2="" edc="1"/>
</POSRequest>

Sample Request XML for EDC = 0

XML

<POSRequest>
<Ident id="1235" termserialno="45686968" ttype="46" />
<POSDefaultInfo server="200" table="60" check="11036" />
<Payment pamt="400" tamt="050" cback="100" schrg="100" cardType="2" acct="4008000123456781" exp="1009" track2="" edc="0" />
<Auth auth="243" />
</POSRequest>

Sample Request XML for void transaction

XML

<POSRequest>
<Ident id="1235" termserialno="45686968" ttype="46" />
<POSDefaultInfo server="200" table="60" check="11036" />
<Payment pamt="400" tamt="050" cback="100" schrg="100" cardType="2" acct="4008000123456781" exp="1009" track2="" edc="0" refno="50" />
</POSRequest>

Sample Response XML without receipt

XML

<POSResponse>
<Ident id="1235" termserialno="45686968" ttype="46" POSVer="7.08.000.380"/>
<POSDefaultInfo server="200" table="60" check="11036" res="1" rtext="success" />
<PrintText text=" Ingenico Canada " /> <PrintText text="Terminal Mgmt Concepts " />
</POSResponse>

Sample Response XML with receipt

XML

<POSResponse>
<Ident id="1235" termserialno="45686968" ttype="46" POSVer="7.08.000.380"/>
<POSDefaultInfo server="200" table="60" check="11036" res="1" rtext="success" />
<PrintText text=" Ingenico Canada " /> <PrintText text="Terminal Mgmt Concepts " />
<PrintText text="Concord Ontario L4K2M9 " />
<PrintText text="*******DEMO*************" />
<PrintText text="MER # TMC " />
<PrintText text="TERM # TMC51004" />
<PrintText text="SEQ # 000611 " />
<PrintText text="INVOICE # 000012" />
<PrintText text=" " />
<PrintText text="*******DEMO*************" />
<PrintText text="CARD ************5557" />
<PrintText text="CREDIT/MCRD " />
<PrintText text="ENTRYMODE/KEYED " />
<PrintText text=" " />
<PrintText text="PURCHASE " />
<PrintText text="AMOUNT $5.00" />
<PrintText text=" " />
<PrintText text="AUTH#: 385078 B:001" />
<PrintText text="*******DEMO*************" />
<PrintText text=" TRANSACTION " />
<PrintText text=" APPROVED - 00 " />
<PrintText text=" CUSTOMER COPY " />
<PrintText text=" THANK YOU " />
<PrintText text=" WELCOME " />
<PrintText text=" WWW.TGIFATCAT.COM " />
<PrintText text="*******DEMO*************" />
</POSResponse>

Get Check Info

Getting check info is initiated on the payment device to get miscellaneous details about the check and the associated table. For example, these details include items that the customers have ordered, and discounts applied to those items.

Request

The ttype for getting check info is 47.

Sample Request XML

XML

<POSRequest>
<Ident id="1234" termserialno="45686968" ttype="47" />
<POSDefaultInfo server="1" check="100400" track2="" />
</POSRequest>

Sample Response XML

XML

<POSResponse>
<Ident id="345" termserialno="45686968" ttype="47" POSVer="7.08.000.380"/>
<POSDefaultInfo server="1" check="100400" res="1" rtext="success" />
<ServerInfo id="1" name="Peter" />
<TableInfo id="10" name="" numcustomers="4" area="DINING ROOM 1" />
<InvoiceItems currency="USD" currencySymbol="$" discounttotal="50">
<InvoiceItem id="991" name="Medium Coke" amount="175" quantity="1" division="SOFT DRINK" plu="abcd1" totaltaxamount="100" taxpercentage="10" />
<InvoiceItem id="823" name="Shrimp Cocktail" amount="795" quantity="2" division="APPETIZER" plu="abcd2" totaltaxamount="100" taxpercentage="10">
<Discount id="1501" name="Some reason" amount="50" includedtax="true" />
</InvoiceItem>
</InvoiceItems>
</POSResponse>

Lock

The lock request is initiated when a check is opened on a pinpad. This should prevent the check from being opened again or pulled by the get tables until an appropriate timeout period is reached, or an unlock request is sent to the POS.

Request

The ttype for the lock request is 48

Sample POS Request

XML

<POSRequest>
<Ident id="1234" termserialno="45686968" ttype="48" />
<POSDefaultInfo server="1" check="100400" track2="" />
</POSRequest>

Sample POS Response

XML

<POSResponse>
<Ident id="345" termserialno="45686968" ttype="48" POSVer="7.08.000.380"/>
<POSDefaultInfo server="1" table="10" check="100400" res="1" rtext="success" />
<LockDetails time="1586373726514" maxduration="120000" />
</POSResponse>

Unlock

The unlock request is initiated when a check that is opened by the pinpad is no longer being used by that pinpad. This could be after the payment has been applied, or if the payment has been aborted. This should allow the check to be opened again or pulled by the get tables.

Request

The ttype for the lock request is 49

Sample POS Request

XML

<POSRequest>
<Ident id="1234" termserialno="45686968" ttype="49" />
<POSDefaultInfo server="1" check="100400" track2="" />
</POSRequest>

Sample POS Response

XML

<POSResponse>
<Ident id="345" termserialno="45686968" ttype="49" POSVer="7.08.000.380"/>
<POSDefaultInfo server="1" table="10" check="100400" res="1" rtext="success" />
</POSResponse>

📊

Field Reference (Appendix A)

Field	Format	Notes
POSDefaultInfo - server	Character 10	10 char maximum. Primarily numeric data
POSDefaultInfo - table	Long	Up to 10 digits
POSDefaultInfo - check	Long	Up to 10 digits
POSDefaultInfo - track2	Character 37	Up to 37 characters from swiped server card
Ident	XML TAG	This xml tag should be present in all requests and responses with id and ttype to identify the request and response
Checks, Check	XML TAG	Check tag should be present in a successful get table response
ServerInfo, TableInfo	XML TAG	These xml tags should be present in a successful get check info response
Discount	XML TAG	This XML tag can optionally be a child of an InvoiceItem if that item has a discount.
InvoiceItems, InvoiceItem	XML TAG	These XML tags are required in a successful get check info response. InvoiceItems is the container where there may be many InvoiceItem elements within.
LockDetails	XML TAG	This XML tag is present in a successful lock request.
ServerInfo – id	Long	The server id as defined on the POS. This is the server that we would provide in the PosDefaultInfo server attribute during a request.
ServerInfo – name	Character 40	Optional – The name of the server / waiter.
TableInfo – id	Long	The table id as defined on the POS. This is the table number that we would provide in the PosDefaultInfo table attribute during a request.
TableInfo – name	Character 40	Optional – The name of the table if any.
TableInfo – numcustomers	Int	Optional – The number of customers seated at this table.
TableInfo – area	Character 40	Optional – The area / section of the restaurant in which the table is located.
POSDefaultInfo	XML TAG	Should be present in all requests and responses
PrintText	XML TAG	Should be present in all successful print check responses and some specific apply payment responses
Auth	XML TAG	Can be preset in payment requests
Payment	XML TAG	Should be present in all payment requests
POSResponse	XML TAG	Should be present in all responses and it’s the parent tag
POSRequest	XML TAG	Should be present in all requests and it’s the parent tag
Ident - id	Long	Up to 10 Digits, present in all requests and responses uniquely identifies the request and responses.
Ident – ttype	Int	Present in all request and responses identifies the transaction type of request and response 45 – Get table 46 – Apply Payment 47 – Get check info 48 – lock request 49 – unlock request
Ident - POSVer	String	The POS version.
POSDefaultInfo – res	Character 6	For all responses this attribute should be present. A value of “1” indicates success.
POSDefaultInfo – rtext	Character 40	Contains short description for failure of this transaction.
Check – tableno	Long	Up to 10 digits, present in get table responses
Check – chkno	Long	Up to 10 digits, present in get table responses.
Check – tablename	Character 16	Up to 16 chars as name for the table
Check – chkname	Character 16	Up to 16 chars as name for the check
amt, tax, pamt, tamt, schrg	Long	Up to 10 digits and it can be negative (ex : - 1000) Cents are included without the decimal symbol. $10.01 passed as 1001
InvoiceItems – currency	String	The currency used. ex. CAD or USD.
InvoiceItems – currencySymbol	String	The currency symbol used. ex. $
InvoiceItems – discounttotal	Long	Optional – Please provide the total discount of InvoiceItems without decimal points. If not provided, assumed to be 0.
InvoiceItem – id	Int	Optional – a menu item id that the POS may or may not have internally
InvoiceItem – name	String	Optional – the name of the menu item
InvoiceItem – amount	Long	The price of this menu item in cents, or without decimal places.
InvoiceItem – quantity	Int	Optional – The number of this item that was ordered.
InvoiceItem – division	String	Optional – The category / division that this menu item belongs in.
InvoiceItem – plu	String	Optional – The price lookup code
InvoiceItem – totaltaxamount	Long	Optional – The tax amount applied for this invoice item. This has precedence over the taxpercentage field
InvoiceItem – taxpercentage	Int	Optional – The percentage of tax to be applied for this invoice item.
Discount – id	Long	Optional – an discount id that the POS may or may not have internally
Discount – name	String	Description of the discount / reason
Discount – amount	Long	The monetary value of this discount with no decimal points.
Discount – includedtax	String	Optional – Determines if this discount includes tax. If not provided, assumed to be false.
LockDetails - time	long	The time the lock was initiated in milliseconds since epoch
LockDetails - maxduration	long	The number of milliseconds representing the maximum duration of the lock.
cardType	Int	0 – DEBIT 1 - MCRD 2 - VISA 3 - DINER 4 - DSCVR 5 - AMEX 6 - JCB 7 - Private Label 8 - CASH 9 - GIFT
acct	Character 40	Account no from the card of manual entry of cardio
exp	Char 4	Expiry date in MMYY
auth	Char 10	AuthNo from the host
edc	Int	If >0 the POS will authorize the transaction.
text	Character 42	Contains the print information that will be printed on terminal. Should contain formatted text with no special characters.
Ident - termserialno	Character 32	This is used to identify the originating CAT (Card authorizing terminal).
refno	Int	This is the authorization code / reference number for a transaction.