Introduction

The TCP/IP interface allows a point of sale (POS) to connect to the Linkly system via a TCP/IP interface socket.

The interface works on the following basis:

• The POS opens a socket to Linkly
• The POS sends its request down the socket
  
• The POS listens for replies and handles as necessary
  
• The POS receives a final response to their initial request
  
• The POS can now close the socket and disconnect.
  

Start Developing

Initial Setup

Install required software

• Download the latest release candidate Linkly Software and install the "Offline Development" components
  • DevTools will be installed to C:\PC_EFT\DevTools
  • The VirtualPinpad.exe can be launched from the start menu

Enable Listen Socket in Client

• By default the EFT-Client will listen for TCP requests on port 2011
• You can edit the default port by changing the registry setting below:
  • HKEY_LOCAL_MACHINE\SOFTWARE\CullenSoftwareDesign\EFTCLIENT\CLIENT\IP_INTERFACE_PORT
    

IP Address Allowed List

• By default the EFT-Client will accept connections from any address
• You can configure a white-list by updating the registry setting:
  • HKEY_LOCAL_MACHINE\SOFTWARE\CullenSoftwareDesign\EFTCLIENT\CLIENT\IP_INTERFACE_ACCESS_LIST
    
• Format is:
  • IP address;Ipaddress;Ipaddress;
    
  • e.g. 10.2.2.2;10.2.2.3;10.2.2.4;
    
  • Every IP address must end in a ';'

SDK

Linkly supports C# and Java SDK's which wrap the TCP/IP interface.

• Java SDK
• C# SDK

Example Flow Request

• Open TCP/IP socket (if not already open)
  
• Construct a Transaction Request message
• Send the transaction request to the TCP/IP application.
  
• Listen on the TCP/IP socket for the following:
  
• Display Events. These messages will signal to the POS that the EFTPOS system is attempting to display some data on the screen. If the POS is using the standard EFT system, then the display will be shown on the POS. This event can be used to provide a display on an alternative customer display.
  
• Print Events: These messages indicate that the EFTPOS system requires a receipt to be printed on the POS printer. The POS must respond to this event to ensure that the receipt is printed.
  
• Transaction Response Event: This event signals that the transaction is complete. The POS can finalise the sale, and proceed to the next.
  

Core Payments

Overview

The Core Payments API offers a simple entry point for POS developers to send card payment transactions to Linkly supported PIN pads.

Minimum Requirements

Below are the minimum requirements for a POS system to be considered for accreditation with the Linkly Core Payments API

Transaction Types

• Purchase (P)
• Refund (R)

Management of merchant/bank functions

• Reprint Receipt
• Get Last Transaction

Transactional Scenarios

• Partial/Split Payments

Error Handling

• PowerFail Scenarios
• Timeout Scenarios

Purchase

The purchase transaction type allows the merchant to perform a sale, it uses the transaction request format.

All refunds in the Core Payments API need to be matched to an original purchase. The POS will achieve this by storing the contents of the 'RFN' PAD tag returned in the purchase response and, if a refund for this purchase is required, sending the contents of this field in the refund request.

The 'REF' tag represents the transaction reference from the payment host. It will be printed on the receipt. The POS should record the 'REF' tag against the sale in the POS database to allow a transaction to be looked up from the receipt contents.

Request

Field	Description
Command	'M'
App	Set to '00'
Merchant	Set to '00'. Instructs the Linkly components to perform a card payment
TxnType	Set to 'P' to indicate a purchase request
AmtPurchase	Amount of sale in cents
CurrencyCode	ISO Currency code (e.g. AUD, NZD). Default AUD
TxnRef	Unique POS reference number
CutReceipt	Indicates to cut or not cut the receipt
ReceiptAutoPrint	Indicates where to print the receipt
PurchaseAnalysisData	Extended fields. See PurchaseAnalysisData requirements below.

PurchaseAnalysisData(PAD)

Tag	Name	Type	Notes	Example
SKU	Basket ID	string(16)	See Basket API spec	SKU006005520
OPR	OperatorReference	string(128)	POS operator name and id. Format: ID|Name	OPR00766|test
AMT	TotalAmount	string(9)	Total amount of the entire sale in cents, not tender amount	AMT00520000 $200.00 total sale
UID	Globally unique value	UUID v4	UUID v4 used to uniquely identify this sale across all registers	UID0367f619126-5fa7-4351-8585-1d4f813019d2
NME	POS Name	string(64)	Name of POS. This should match accreditation POS name	NME007TestPOS
VER	POS Version	string(64)	Version of the POS. This should match accreditation	VER0041.00
VND	POS Vendor ID	UUID v4	A unique UUID v4 which identifies the POS POS product. This value can be hard coded into the build of the POS. e.g. All merchants using the same POS product should supply the same posVendorId value	VND036907b3267-c37d-49c1-a8a2-429f937748c6
PCM	POSCapabilitiesMatrix	string(32)	POS Capabilities Matrix. First byte = POS can scan Barcode	PCM00400000

Response

The purchase response is in the format of the transaction response object, see the Transaction section for a detailed breakdown. The below tags are part of the PurchaseAnalysisData object in the response and are of critical importance to the core payments transactions.

Field	Description
Success	'1' if successful, '0' if transaction failed
Response Code	2 character response code
Response Text	Short response message
AmtPurchase	(cond. success) Approved purchase amount
TxnRef	Echoed from request
CurrencyCode	Code to indicate the currency the sale was processed using. Default is AUD
TxnType	Echoed from request
CardName	This returns the Card Bin number, which identifies the payment processor
PurchaseAnalysisData	Extended fields. See PurchaseAnalysisData requirements below.

PurchaseAnalysisData

Tag	Name	Type	Notes	Example
RFN	Reference Number	string(128)	Transaction Reference Number to be used in a refund, can contain additional information	RFN017klujhadsc9ph87asd
REF	Host reference Number	string(32)	Reference number to the sale from the provider systems, printed on receipt	REF00512345
HRC	Host Response Code	string(64)	Response code from the payment processor	HRC004ERR1
HRT	Host Response Text	string(999)	Response text from the payment processor	HRT013INVALID CARD
UID	Globally unique value	UUID v4	Echoed from request	UID0367f619126-5fa7-4351-8585-1d4f813019d2

---

Refund

A refund transaction type allows the merchant to undo a sale, it uses the transaction request format. The POS must ensure that the correct 'RFN' Tag is sent when performing a refund.

Request

Field	Description
Command	'M'
App	Set to '00'
Merchant	Set to '00' to indicate a generic 'pay later' request
TxnType	Set to 'R' to indicate a Refund request
AmtPurchase	Amount to refund via selected provider
CurrencyCode	ISO Currency code (e.g. AUD, NZD). Default AUD
TxnRef	Unique POS reference number
CutReceipt	Indicates to cut or not cut the receipt
ReceiptAutoPrint	Indicates where to print the receipt
PurchaseAnalysisData	Extended fields. See PurchaseAnalysisData requirements below.

PurchaseAnalysisData(PAD)

Tag	Name	Type	Notes	Example
RFN	Reference Number	string(128)	Refund reference code as returned by original purchase	RFN017klujhadsc9ph87asd
OPR	OperatorReference	string(128)	POS operator name and id. Format: ID|Name	OPR00766|test
UID	Globally unique value	UUID v4	UUID v4 used to uniquely identify this sale across all registers	UID0367f619126-5fa7-4351-8585-1d4f813019d2
NME	POS Name	string(64)	Name of POS. This should match accreditation POS name	NME007TestPOS
VER	POS Version	string(64)	Version of the POS. This should match accreditation	VER0041.00
VND	POS Vendor ID	UUID v4	A unique UUID v4 which identifies the POS POS product. This value can be hard coded into the build of the POS. e.g. All merchants using the same POS product should supply the same posVendorId value	VND036907b3267-c37d-49c1-a8a2-429f937748c6
PCM	POSCapabilitiesMatrix	string(32)	POS Capabilities Matrix. First byte = POS can scan Barcode	PCM00400000

Response

The refund response is in the format of the transaction response object, see the Transaction section for a detailed breakdown. The below tags are part of the PurchaseAnalysisData object in the response and are of critical importance to the core payments transactions.

Field	Description
Success	'1' if successful, '0' if transaction failed
Response Code	2 character response code
Response Text	Short response message
AmtPurchase	(cond. success) Approved refund amount
TxnRef	Echoed from request
CurrencyCode	Code to indicate the currency the sale was processed using. Default is AUD
TxnType	Echoed from request
CardName	This returns the Card Bin number, which identifies the payment processor
PurchaseAnalysisData	Extended fields. See PurchaseAnalysisData requirements below.

PurchaseAnalysisData

Tag	Name	Type	Notes	Example
REF	Host reference Number	string(128)	Reference number to the sale from the provider systems, printed on receipt	REF00512345
HRC	Host Response Code	string(64)	Response code from the payment processor	HRC004ERR1
HRT	Host Response Text	string(999)	Response text from the payment processor	HRT013INVALID CARD
UID	Globally unique value	UUID v4	Echoed from request	UID0367f619126-5fa7-4351-8585-1d4f813019d2

Management Functions

The management functions allow the merchant to perform utility functions in addition to sales. The minimum requirements for these are; reprint receipt and Get Last Transaction.

Reprint Receipt

The reprint receipt function allows for the retrieval/reprint of a financial receipt. It uses the reprint request format.

The 'Merchant' field must be set to a unique 2-character code to specify the sale processor, this is returned in the purchase/refund response.

Reprint Receipt Request

Field Name	Length (characters)	Description	Example
SubCode	1	Indicates to reprint or retrieve (sent to POS)	'1' = reprint receipt '2' = get last receipt
Merchant	2	Unique ID of third-party sale to fetch. Set to '00' to indicate generic reprint	'00' = Last receipt
CutReceipt	1	Indicates to cut or not cut the receipt	'1' = Cut '0' = Don't Cut
ReceiptAutoPrint	1	Indicates where to print the receipt	'0' = POS printing, '1' = Windows Printer, '9' = Internal EFTPOS Terminal Printer

Reprint Receipt Response

Field Name	Length (characters)	Description	Example
Success	1	Indicates if the function was successful	'1' = Success '0' = Failed
Response Code	2	Response code indicating sale status	'00' = Approved 'X0' = No response
Response Text	20	Response message associated with the response code	'TRANSACTION APPROVED'
Receipt	Length = len(msg) - 30	The Actual Receipt Data

Get Last Transaction

This function returns the last transaction event processed by Linkly. It uses the get last txn format. This function can be called by a POS to determine whether a transaction was successful or not following a power failure whilst an EFTPOS transaction was in progress, this is part of the error handling scenarios.

Get Last Transaction Request

Field Name	Length (characters)	Description	Example
Merchant	2	Must be '00' for the Core Payments API	'00'

Get Last Transaction Response

The POS will receive a standard GetLastTxn Response

Tag Name	Length (characters)	Description
Start Flag	1	Always = '#'
Length	4	Length of the message including start and length field
CommandCode	1	'N' = Get Last Transaction
Sub Code	1	'0'
Success	1	'0' = Failed '1' = Success
LastTxnSuccess	1	'0' = Failed '1' = Success
Response Code	2	Response code from the bank
Response Text	20	Response text associated with the response code
Merchant	2	Identifier for the payment processor
TxnType	1	Type of transaction performed
AccountType	7	Account Used in the transaction
AmtCash	9	The amount of cash out for the transaction.
AmtPurchase	9	The purchase amount for the transaction.
AmtTip	9	Amount of tip given (if any).
AuthCode	6	Authorisation Code
TxnRef	16	Contains the cheque serial number if the Get Last request is directed at Cheque Auth
Stan	6	The Systems Trace Audit Number of the last transaction performed. (000000-999999).
Caid	15	Card Acceptor ID, also known as the MID
Catid	8	Card Acceptor Terminal ID.
DateExpiry	4	Set before calling Transaction if a customer's card details are manually entered by the operator.
DateSettlement	4	Contains the settlement date for the transaction in 'DDMMYYYY' format
Date	6	Contains the settlement date for the transaction in 'DDMMYYYY' format
Time	6	Transaction time returned by the acquirer. 'HHMMSS' format.
CardType	20	Indicates the card type used for the transaction as described by the bank.
Pan	20	Primary Account Number. Loaded with the customer card number for manually entered transactions
Track2	40	Contents of magnetic card track 2.
RRN	12
CardName	2	This property actually returns the Card Bin number.
TxnFlags	8	Zero's - not used for alternative payments
Balance received from host	1	'0' = false '1' = true
AvailableBalance	9
Cleared Funds Balance	9
PurchaseAnalysisData	3	Length of the following Purchase Analysis Data field. This field is optional and may not be present.
PurchaseAnalysisData	XXXX	Purchase Analysis Data

Transactional Scenarios

Partial/Split Payments

Partial and split payments must be handled by the POS, when sending a purchase request the POS must set the 'AMT' Tag with the total amount of the entire sale the 'AmtPurchase' field should be set to the actual tender amount, in most cases these fields will be equal. When receiving a response the POS will receive the 'AmtPurchase' field set to the amount the sale was processed for if the POS receives an amount less than what was sent in the response it must continue to make payments until the entire tender is payed for.

Example 1

• POS sets AMT PurchaseAnalysisData tag to 4000 - Total sale for $40.00
• POS sets AmtPurchase = 2000 – Tender amount set to $20.00
• Process sale
• POS receives AmtPurchase = 2000 – Payment completed for $20.00
• POS sets AmtPurchase = 2000 and AMT PurchaseAnalysisData tag to 4000 – Create another sale for $20.00
• Process Sale
• POS receives AmtPurchase = 2000 – Payment completed for $20.00
• Tender complete

Example 2

• POS sets AMT PurchaseAnalysisData tag to 2000 = Total Sale for $20.00
• POS sets AmtPurchase = 2000 = Tender amount set to $20.00
• Process sale
• POS receives AmtPurchase = 1000 - Payment completed for $10.00
• POS sets AmtPurchase = 1000 and AMT PurchaseAnalysisData tag to 2000 – Create another sale for $10.00
• Process Sale
• POS receives AmtPurchase = 1000 – payment completed for $10.00
• Tender complete

Error Handling

This section covers various error scenario where the POS must take specific actions in order to recover and re-sync with the Linkly client. The only mandatory scenarios are power fails and timeouts.

In this scenario the POS has lost power but the eftpos terminal has continued with a sale. Upon recovery the POS must use the Get last transaction function to ensure that; any sale performed while the POS was off is correctly recorded, match the POS' last known sale to Linkly ensure they are correct.

Timeout

All POS timeout values should be set at 180 seconds from the last message received from Linkly, this ensures that the POS receives a 'timeout' response from Linkly instead of dropping the reply and not finishing the sale correctly.

A timeout value of 180 seconds ensures Linkly has enough time to perform long operations requiring user input (such as scanning a QR code, confirming a sale on their phone) and meet any compliance the third party has regarding data capture.

In this scenario the POS has lost connectivity to the EFT-Client. Similar to a power fail upon restoring connectivity the POS must call Get Last Transaction to ensure that; any sale performed while the POS was off is correctly recorded, match the POS' last known sale to Linkly' ensure they are correct.

Optional Functionality

Custom Displays

The POS can hide the default Linkly dialog and implement it's own custom displays.

To do this the POS needs to capture the Display Request event and implement the following dialogs:

• 2-line, 20 character. No keys enabled. Input type 0. Graphics code 0 to 6.
• 2-line, 20 character. Cancel key enabled. Input type 0. Graphics code 0 to 6.
• 2-line, 20 character. OK key enabled. Input type 0. Graphics code 0 to 6.
• 2-line, 20 character. Accept + decline key enabled. Input type 0. Graphics code 0 to 6.
• 2-line, 20 character. Auth + cancel key enabled. Input type 1. Graphics code 0 to 6.

Input types:

• '1'= Normal ASCII input

Example displays

No keys enabled

Cancel key enabled

OK key enabled

Accept/decline keys enabled

Auth input enabled

---

Linkly Basket

The Linkly Basket is a API used for providing merchants value adds that contain informatation related to the items that made up the total value of the transaction. Many of the new payment types require some level of basket information to process their payments so Linkly has created a API to ensure that these can be met without bespoke effort for each payment type.

Overview
The EFT-Client handles basket commands like a database, exposing a CRUD interface to the POS. Each basket has a unique identifier "id", that the POS can use to:

• Create a new basket containing items
• Add items one at a time to the basket
• Update an existing item in the basket
• Remove an item from the basket.
  

When the POS calls transaction it needs to include the basket id for that transaction in the PAD tag named "SKU". The EFT-Client will then include the basket data as part of the transaction request, which is then passed to any appropriate third-party processors. It is anticipated that the POS will use the basket commands in one of two ways:

1. Call Linkly as each item is scanned (adding / updating / removing items as necessary)
   
2. Call the basket command once, with the full basket, before calling transaction
   

Message Format

Basket data uses the "Generic POS Command" message type.

Request:

#	Field	Length	Format	Description
1	Start flag	1	Alphanumeric	Content header. Set to '#'
2	Length	4	Numeric. Right aligned, zero padded.	Set to the length of the message, including this header
3	Command code	1	Alphanumeric	Generic POS command type. Set to 'X'
4	Sub code	1	Alphanumeric	Basket data command type. Set to '%'
5	Basket length	6	Numeric. Right aligned, zero padded.	The length of the basket data command to follow.
6	Content	*	Alphanumeric	Basket data command

Response:

#	Field	Length	Format	Description
1	Start flag	1	Alphanumeric	Content header. Set to '#'
2	Length	4	Numeric. Right aligned, zero padded.	Set to the length of the message, including this header
3	Command code	1	Alphanumeric	Generic POS command type. Set to 'X'
4	Sub code	1	Alphanumeric	Basket data command type. Set to '%'
5	Response Code	2	Alphanumeric	"00" indicates successful, all other response codes indicate a failure.
6	Response Text	20	Alphanumeric	Response text for the call

---

Basket Command Header Fields

{
 "id": "t39kq18134553",
 "amt": 17890,
 "tax": 1790,
 "dis": 1000,
 "sur": 358,
 "items": [...]
}

The basket header contains meta information about the basket,
along with the id for the basket which is needed when sending a transaction with basket data, or when changing the basket.

Name	Required	Description	Format
id	Y	A unique ID for the basket	String, max 32
amt	Y	Total price for the basket, in cents, including tax and discount, but excluding surcharge	Integer
tax		Total tax for the basket, in cents	Integer
dis		Total discount for the basket, in cents	Integer
sur		Surcharge (e.g. for Credit Card), in cents	Integer
items	Y	Array of basket items	JSON array

---

Basket Command Item Fields

//Example Basket Item Data
{  
    "id": "t39kq002",  
    "sku": "k24086723",  
    "qty": 2,  
    "amt": 2145,  
    "tax": 200,  
    "dis": 50,  
    "gtin": "831664397578",  
    "name": "XData USB Drive",  
    "desc": "24GB XData USB Drive, Red/Black",  
    "srl": "xd546467",  
    "img": "http://www.xdata.com/products/images/usb24_rb_1.jpg",  
    "link": "http://www.xdata.com/products.php&pid=usb24_rb",  
    "tag": "usb drive,storage"  
}

The basket items are required to have at least an id, sku, quantity, and price of the item included in the item data.
Other fields can be used as desired by vendors.

Name	Required	Description	Format
id	Y	A unique ID for the item	String, max 32
sku	Y	Merchant assigned SKU for the item	String
qty	Y	Quantity (number of units)	Integer
amt	Y	Individual unit price for the item, in cents, including tax and discount	Integer
tax		Individual unit tax for the item, in cents	Integer
dis		Individual unit discount for the item, in cents	Integer
ean		The EAN (European Article Number) for the item	String
upc		The UPC (Universal Product Code) for the item	String
gtin		The GTIN (Global Trade Item Number) for the item	String
name		A short name for the item	String, max 24
desc		A longer description for the item	String, max 255
srl		Serial code, or other identifying code, for the item	String
img		URL to an image for the item	String
link		URL to a product page for the item	String
tag		Comma separated category or type information for the item (e.g. "food, confectionery")	String, max 64

Basket Command Extended Item Fields

{  
    "id": "t39kq001",  
    "sku": "s63787452",  
    "qty": 1,  
    "amt": 1995,  
    "weight": "2kg"  
}

In additional to the required and optional fields, an item may also include one or more extended fields for use by specific third parties. Extended fields are simply included along with the standard fields for the item.
The example opposite includes "weight", with a value of "2kg", as an extended field.

See the appropriate Linkly Third Party Processor (TPP) specification for a list of supported extended fields.

Basket Command Full Example

// Full Basket Example
{  
    "id": "t39kq18134553",  
    "amt": 18700,  
    "tax": 1760,  
    "dis": 650,  
    "sur": 374,  
    "items": [{  
        "id": "t39kq002",  
        "sku": "k24086723",  
        "qty": 2,  
        "amt": 2145,  
        "tax": 200,  
        "dis": 50,  
        "name": "XData USB Drive"  
    }, {  
        "id": "t39kq003",  
        "sku": "s23475697",  
        "qty": 1,  
        "amt": 8910,  
        "tax": 810,  
        "name": "MSoft OSuite",  
        "srl": "ms7843k346j23"  
    }, {  
        "id": "t39kq004",  
        "sku": "m47060855",  
        "qty": 5,  
        "amt": 1100,  
        "tax": 110,  
        "dis": 110,  
        "name": "A4 Notepad"  
    }]  
} 

The example opposite basket contains 3 items:
2 XData USB Drives, at $21.45 each, which includes tax of $2.00 and a discount of $0.50
1 MSoft OSuite, with a serial number, at $89.10, which includes tax of $8.10 and no discount
5 A4 Notepads, at $11.00 each, which includes tax of $1.10 and a discount of $1.10
The total value of the basket is $187.00, with a total tax of $17.60 and total discount of $6.50. Paying by credit card also incurred a surcharge of $3.74 (2%).

Building a Basket Incrementally

// Adding an Item Example
{  
    "id": "t39kq18134553",  
    "amt": 22165,  
    "tax": 2075,  
    "dis": 650,  
    "items": [{  
        "id": t39kq005,  
        "sku": "t54043584",  
        "qty": 1,  
        "amt": 3465,  
        "tax": 315,  
        "name": "Ltech headset"  
    }]  
}

// Updating an Item Example
{  
    "id": "t39kq18134553",  
    "amt": 24310,  
    "tax": 2275,  
    "dis": 700,  
    "items": [{  
        "id": "t39kq002",  
        "sku": "k24086723",  
        "qty": 3,  
        "amt": 2145,  
        "tax": 200,  
        "dis": 50,  
        "name": "XData USB Drive"  
    }]  
}

// Deleting an Item Example
{  
    "id": "t39kq18134553",  
    "amt": 18810,  
    "tax": 1725,  
    "dis": 150,  
    "items": [{  
        "id": "t39kq004"  
        }]  
}  

To create or build a basket incrementally (for example, as each item is scanned in),
multiple requests can be sent using the same header "id" value, with updated total "amt", "tax", and "dis" values, and the "items" array,
which contains the item to add, update or remove.

Adding an Item

To add an item to an existing basket, simply give the additional item a unique item "id" value, see: Basket Command Item Fields
This will cause the item to be treated as unique, even if it has the same "sku", "ean", "gtin", etc. as another item.

Updating an Item

To update an existing item, pass the full item record, with updated values, using the same item "id" value as the existing item. This will cause all existing data for that item to be overwritten.
Note: Only one item can be updated per request
Note: The updated record needs to include all relevant fields and values for the item, even those that haven't changed.

Deleting an Item

To delete an item, simply pass an item record with only the "id" field and value for the item that you want to delete.
Note: Only one item can be deleted per request

Surcharging

The Linkly surcharging solution is driven by the Linkly components and the payment terminal, this removes any need for the POS application to perform any complex card inspection or store and managed surcharging rates. Merchants can us the Linkly EFT-Client GUI to set their desired surcharging rates.

If a surcharge is applied:

• the SUR PAD tag will be present in the transaction response, and will contain the value of the surcharge applied in cents.
• the AMT PAD tag will be present in the transaction response, and will contain the total value of the sale (e.g. purchase amount + surcharge + tip)

Merchants can enable and configure the surcharge rates from the "Surcharge" tab in the Linkly EFT-Client GUI.

Food & Beverage

Linkly has created a number of payment features that help merchants make the most of their payment solution, these help POS providers quickly add important features to their food and beverage solution.

Pay at Table

The Linkly Pay at Table solution groups a number of payment features together to deliver the capability to process payment transactions at a table, the capabilities include:

• Initiate the transaction from the payment terminal
• Split billing across multiple parties
• Collect tips as part of the transaction
• Print receipts at the table

As the Pay at Table flow creates an alternate transaction flow (commenced from the terminal), there are dedicated Linkly features to enable.

Overview

The Pay at Table API provides a common interface for the terminal to utilise the EFT-Client to retrieve available tables and orders so payment functions (e.g. tender, customer receipt etc.) can be performed by an operator on the terminal without using the POS.

The Pay at Table client requires the POS to act a data source so that it can retrieve information about available tables, orders, payment options etc.

The Pay at Table client supports two data source options for the POS; a REST server or directly through the existing Linkly interface.

POS Data Source - REST Server

When in REST server mode the Pay at Table extension will connect directly to a REST server hosted by the POS which implements the Linkly Pay at Table REST API.

Example Transaction Flow

1. The user initiates a Pay at Table transaction from the terminal
   
2. The Linkly Pay at Table client requests the settings from the server
3. The Linkly Pay at Table client requests a list of tables from the server
4. Tables are presented to the user, either as a list using the DisplayName property of a Table or by allowing the user to manually key a DisplayNumber.
5. Once the user selects a table, the Pay at Table client requests orders available on that table.
   
6. If no orders are available, the Pay at Table client presents a display to the user and allows them to select another table.
   
7. If orders are available the Pay at Table client presents available options for that order (e.g. print receipt, tender). If multiple orders are available, the Pay at Table client displays all available orders and asks the user to select which order to process.
8. If the user selects the "Print Receipt" option, the Pay at Table client will request the customer receipt from the server, print it and display the order options again. If multiple print options are available from the settings, the user is asked to select which mode to print before the request is sent to the server.
9. If the user selects the "Tender" option, the Pay at Table client starts a payment on the terminal. If multiple tender options are available from the settings, the Pay at Table client displays these options and asks the user to select the tender type before proceeding with the payment.
10. The transaction request, display events and transaction event are sent to the server as EFTPOS commands
11. Once the payment is complete, the Pay at Table client updates the tender with a completed state. It is assumed at this point the POS server would also update the order state.
12. The Pay at Table client request the selected order again. If the order is complete a message is displayed on the terminal, otherwise the user is presented with the order options again.

POS Data Source - Linkly Interface

Linkly recommend the POS implements REST server mode. If the REST server mode doesn't suit your integration needs, please contact Linkly to discuss alternatives.

The POS must manage the order/tender states in case of disconnection from the Pay at Table client or the terminal. If the POS loses connection from the service at any time while a tender/order is being processed, it's recommended to inquire of the last transaction's status using the GetLastTransaction call to the EFT-Client.

Start Developing

Install required software

• Download the latest release candidate Linkly Software and install the "Offline Development" components
  • DevTools will be installed to C:\PC_EFT\DevTools
  • The VirtualPinpad.exe can be launched from the start menu
• Download and install the latest release candidate Linkly Pay at Table Software
• Set up a Pay at Table demo using either the REST or local Linkly API demo application
• Start a Pay at Table sale from the PINpad

REST Demo Application

To configure the REST Demo Application

1. Download the REST demo source from GitHub
2. Run Visual Studio 2019 as Administrator
3. Open and build the project "PayAtTable.ServerCore" in Visual Studio
4. Open the Project Properties, and under Debug, take note of the App URL
5. When you run the Linkly Pay at Table installer, enable the REST API option and enter the App URL as the server address
6. Run the project using IIS Express. The browser should open showing the Settings launch page. When you click on Swagger, it will show the available APIs.

Local Linkly API Demo Application

To configure the Local Linkly API Demo Application

1. When you run the Linkly Pay at Table installer. Disable the REST API option. The server address can be left blank.
2. Run C:\PC_EFT\DevTools\PayAtTable.TestPos\PayAtTable.TestPos.exe
3. Source for the test POS is available on GitHub
4. Tender Options (TenderTypes) can be configured for the demo POS in %localappdata%\Linkly\PAT-settings.json. Please refer to the POS specs for description of each field.

Start a Pay at Table Sale

1. Configure REST or ActiveX demo application
2. On the Virtual PINpad, press FUNC + 8787 + OK
3. Follow PINpad prompts

Pay at Table REST API

Linkly has created a lightweight solution for driving Pay at Table transactions which the POS needs to implement so the transactions can be commenced from the terminal.

HTTP Response codes

HTTP Response code	Description
200 OK	The request was successful
201 Created	The request was successful, and a resource has been created
204 No Content	The request was successful, there is no content in the response
400 Bad Request	The client request is invalid
401 Unauthorised	The client needs to authenticate before it can continue
403 Forbidden	The client doesn't have access to the resource
404 Not found	The requested resource wasn't found
500 Server Error	The server encountered an internal error processing the request

Methods

Name	HTTP Method	Description
Get Settings	GET /api/settings	Get settings for the Pay at Table client
Get Tables	GET /api/tables	Get a lookup list of tables used to find an order
Get Orders By Table	GET /api/tables/{table-id}/orders	Get a list of orders associated with a table
Get Order	GET /api/orders/{order-id}	Get an order based on an order id.
Get Customer Receipt From Order	GET /api/orders/{order-id}/receipt?receiptOptionId=[string]	Get a customer receipt for a given order. Can accept an optional receipt option id.
Update Order	PUT /api/orders/{order-id}	Update an order
Create Tender	POST /api/tenders	Create a tender
Update Tender	PUT /api/tenders/{tender-id}	Update a tender
Create EFTPOS Command	POST /api/eftpos/commands	Create an EFTPOS command

Get Settings

GET /api/settings 

HTTP/1.1 200 OK 
Content-type: application/json 
{ 
    "Settings": { 
        "TenderOptions": [{ 
            "Id": "0", 
            "TenderType": 0, 
            "Merchant": "0", 
            "DisplayName": "EFTPOS", 
            "EnableSplitTender": false, 
            "EnableTipping": true, 
            "CsdReservedString2": "EFTPOS", 
            "TxnType": "P", 
            "PurchaseAnalysisData": "" 
        }], 

        "ReceiptOptions": [{ 
            "Id": "0", 
            "ReceiptType": 0, 
            "DisplayName": "Customer" 
        }], 

        "PrinterOption": { 
            "PrintMode": 0, 
            "Location": -1, 
            "StaticReceipt": ["line1", "line2", "line3", "line4"] 
        } 
    } 
} 

Description

Get the settings for the pay at table client

Request

Do not supply a request body for this method.

Response

If successful, the body contains a PATResponse object with the Settings property populated a Settings object.

Supported response codes: 200, 400, 401, 403 and 500.

Properties

Name	Type	Description
TenderOptions	TenderOption[]	Lists the tender options available to the Pay at Table client. If left null or empty the option to tender will not be available on Pay at Table client when the user selects an order. If only one option is available, the Pay at Table client will automatically select that option when the user chooses to tender.
ReceiptOptions	ReceiptOption[]	Lists the tender options available to the Pay at Table client. If left null or empty the option to print will not be available on Pay at Table client when the user selects an order. If only one option is available, the Pay at Table client will automatically select that option when the user chooses an order.
PrinterOption	PrinterOption	Allows for custom receipt information, appended to the header/footer of the eftpos receipt, if left null no custom receipt will be printed. You can allow Linkly to print a custom header/footer with some information about the current Transaction

TenderOption Properties

Name	Type	Description
Id	String	Unique identifier.
TenderType	int	The type of this tender option
Merchant	int	The merchant code to use (see Appendix A - Merchant Codes). Default is 0.
DisplayName	String	The text displayed in the terminal.
EnableSplitTender	Boolean	If true, the split-billing workflow is enabled.
EnableTipping	Boolean	If true, the tipping workflow is enabled.
CsdReservedString2	String	A Reserved String for additional functionality (see CsdReservedString2). Default is EFTPOS.
TxnType	String	The type of transaction this tender applies to. Only Purchase and Refund types are allowed.
PurchaseAnalysisData	String	any additional PAD value

ReceiptOption Properties

Name	Type	Description
Id	String	Unique identifier.
ReceiptType	int	The type of receipt for this tender option. Only 0 is supported for now.
DisplayName	String	The text displayed in the terminal.

PrinterOption Properties

Name	Type	Description
PrintMode	int	Determines who will handle the header/footer receipt printing, default PCEFTPOS: PCEFTPOS = 0, POS = 1, STATIC = 2.
Location	int	Determines where the custom receipt will print as a header prior to eftpos receipt or after as a footer, default is None: Header = 0, Footer = 1, None = -1.
StaticReceipt	String[]	The receipt to display if you set PrintMode to STATIC.

Get Tables

GET /api/tables 

HTTP/1.1 200 OK 
Content-type: application/json 
{ 
    "Tables": [{ 
            "Id": "50", 
            "DisplayName": "TABLE 1", 
            "DisplayNumber": 1, 
            "ServerName": "Steve" 
        }, 
        { 
            "Id": "51", 
            "DisplayName": "TABLE 2", 
            "DisplayNumber": 2, 
            "ServerName": "Steve" 
        }, 
        { 
            "Id": "52", 
            "DisplayName": "TABLE 3", 
            "DisplayNumber": 3, 
            "ServerName": "Jake" 
        } 
    ] 
} 

Description

Get a lookup list of tables used to find an order. The Pay at Table client will either present a list of selectable items to the user using the "DisplayName" property, or request the user enter a number which will be used to find a table based on the "DisplayNumber" property. The Id property is a unique identifier for the table used in subsequent requests and is not presented to the user.

Request

Do not supply a request body for this method.

Response

If successful, the body contains a PATResponse object with the Tables property populated by an array of Table.

Supported response codes: 200, 400, 401, 403 and 500.

Properties

Name	Type	Description
Id	String	Unique identifier.
DisplayName	String	Max 14 characters. A name which represents this table that could be displayed to a user.
DisplayNumber	Integer	A number which represents this table that could be displayed to a user.
ServerName	String	Max 8 characters. A string that represents either the servers name or employee ID.

Get Orders by Table

GET /api/tables/{table-id}/orders 

HTTP/1.1 200 OK 
Content-type: application/json 
{ 
    "Orders": [{ 
        "Id": "101", 
        "DisplayName": "Elsa", 
        "OrderState": 0, 
        "AmountOwing": 100.00, 
        "TableId": "50" 
    }] 
} 

Description

Get a list of orders associated with a table.

The Pay at Table client will send this request after a user has selected one of the tables returned from a previous call to Get Tables.

Request

GET /api/tables/{table-id}/orders

Do not supply a request body for this method

Parameter	Type	Description
table-id	String	Required. The id of an table orders are being requested from.

Response

If successful, the body contains a PATResponse object with the Orders property populated by an array of Order.

Supported response codes: 200, 400, 401, 403 and 500.

Properties

Name	Type	Description
Id	String	Unique identifier. Read only.
DisplayName	String	Max 14 characters. A name which represents this table that could be displayed to a user.
OrderState	Integer	The state of the order. This is used by the Pay at Table client to determine if an order is available for tender. Possible values: (0) Pending – The order exists, but isn't yet available for tender. (10) Active – The order exists and is available for tender. (20) Tendering – A tender is currently in progress. The result is not known. The order is not available for tender. (30) Complete – The order is complete and is not available for tender.
AmountOwing	Decimal	The outstanding amount on this order. This is used by the Pay at Table client to determine the maximum tender amount.
TableId	String	The id of the Table attached to this order.

Get Order

GET /api/orders/{order-id} 

HTTP/1.1 200 OK 
Content-type: application/json 
{ 
    "Order": { 
        "Id": "101", 
        "DisplayName": "Elsa", 
        "OrderState": 0, 
        "AmountOwing": 100.00, 
        "TableId": "50" 
    } 
} 

Description

Get an order based on an order id. 

The Pay at Table client will send this request after a user has selected one of the orders returned from a previous call to Get Orders by Table.

Request

Do not supply a request body for this method.

Parameter	Type	Description
order-id	String	Required. The id of the order being requested.

Response

If successful, the body contains a PATResponse object with the Order property populated by an Order.

Supported response codes: 200, 400, 401, 403, 404 and 500.

Properties

Name	Type	Description
Id	String	Unique identifier. Read only.
DisplayName	String	Max 14 characters. A name which represents this table that could be displayed to a user.
OrderState	Integer	The state of the order. This is used by the Pay at Table client to determine if an order is available for tender. Possible values: (0) Pending – The order exists, but isn't yet available for tender. (10) Active – The order exists and is available for tender. (20) Tendering – A tender is currently in progress. The result is not known. The order is not available for tender. (30) Complete – The order is complete and is not available for tender.
AmountOwing	Decimal	The outstanding amount on this order. This is used by the Pay at Table client to determine the maximum tender amount.
TableId	String	The id of the Table attached to this order.

Get Customer Receipt from Order

GET /api/orders/{order-id}/receipt?receiptOptionId=[string]

HTTP/1.1 200 OK 
{ 
    "Receipt": { 
        "Lines": ["Line 1","Line 2","Line 3"] 
    } 
} 

Description

Get a customer receipt based on an order id. 

Request

Do not supply a request body for this method

Parameter	Type	Description
order-id	String	Required. The id of the order the receipt is being requested from.
receiptOptionId	String	Optional. The id of the ReceiptOption used to generate this receipt request. Note: id '99' is reserved for custom header/footer receipt from POS

Response

If successful, the body contains a PATResponse object with the Receipt property populated by a Receipt.

Supported response codes: 200, 400, 401, 403, 404 and 500.

Update Order

PUT /api/orders/{order-id} 
Content-type: application/json 
{ 
    "Order": { 
        "Id": "200",
        "DisplayName": "Order 99",
        "OrderState": 30,
        "AmountOwing": 0.00,
        "TableId": "50"
    } 
} 

HTTP/1.1 200 OK 
Content-type: application/json 
{ 
    "Order": { 
        "Id": "200",
        "DisplayName": "Order 99",
        "OrderState": 30,
        "AmountOwing": 0.00,
        "TableId": "50"
    } 
} 

Description

Updates an order. This is called before the Create Tender to mark the order as Tendering. If the update is successful, the Create Tender is called next. It is called again after a payment has been processed to mark the status of the order. The AmountOwing and OrderState will be updated according to the result of the payment. For example, if the payment was fully paid, the order will be updated as Completed and the AmountOwing is set as zero. If the payment is partial, it will be set again to Active and the AmountOwing will reflect the remaining balance. If the payment was canceled, the status will be set to Active and the AmountOwing will remain the same.

The Id property must point to a valid order and match the {order-id} in the request URL.

Request

The request body contains a PATRequest with the Tender property populated by a Tender.

Parameter	Type	Description
order-id	String	Required. The id of the order being updated.

Response

If successful, this method returns a PATResponse object with the Order property populated by a Order. In most cases the Order in the response will mirror the request.

Properties

Name	Type	Description
Id	String	Unique identifier. Read only.
DisplayName	String	Max 14 characters. A name which represents this order that could be displayed to a user.
OrderState	Integer	The state of the order. This is used by the Pay at Table client to determine if an order is available for tender. Possible values: (0) Pending – The order exists, but isn't yet available for tender. (10) Active – The order exists and is available for tender. (20) Tendering – A tender is currently in progress. The result is not known. The order is not available for tender. (30) Complete – The order is complete and is not available for tender.
AmountOwing	Decimal	The outstanding amount on this order. This is used by the Pay at Table client to determine the maximum tender amount.
TableId	String	The id of the Table attached to this order.

Create Tender

POST /api/tenders 
{ 
    "Tender": { 
        "Id" : null, 
        "OrderId": "101", 
        "TenderOptionId": "0", 
        "TenderState": 0, 
        "AmountPurchase": 100.00, 
        "OriginalAmountPurchase ": 100.00 
    } 
} 

HTTP/1.1 201 OK 
Content-type: application/json 
{ 
    "Tender": { 
        "Id": "1042", 
        "OrderId": "101", 
        "TenderOptionId": "0", 
        "TenderState": 0, 
        "AmountPurchase": 100.00, 
        "OriginalAmountPurchase": 100.00 
    } 
} 

Description

Creates a tender. A tender is an object which contains information about a payment.

Request

The request body contains a PATRequest with the Tender property populated by a Tender.

The OrderId property must reference a valid order.

The TenderOptionId property references the tender option selected by the user.

Response

If successful, the body will contain a PATResponse object with the Tender property populated by a Tender. The Tender in the response will have the Id property populated by a unique Id.

Supported response codes: 201, 400, 401, 403, 404 and 500.

Properties

Name	Type	Description
Id	String	Unique identifier. Read only.
TenderOptionId	String	The id of the tender option the operator selected to create this tender
TenderState	Integer	The state of a tender is defined by the TenderState property. The initial state is set to Pending (0). When the payment is complete the Tender object will be updated and the TenderState changed to CompletedSuccessful (1) or CompletedUnsuccessful (2).
AmountPurchase	Decimal	The amount of this tender (see notes)
Original AmountPurchase	Decimal	If the tender amount is changed (e.g. A $100 purchase on a gift card is completed for the remaining amount on the card - $80.50) this value will reflect the original tender amount before it was changed.
OrderId	String	The id of the order this tender is attached to.

Update Tender

PUT /api/tenders/{tender-id} 
Content-type: application/json 
{ 
    "Tender": { 
        "Id": "1042", 
        "TenderOptionId": "0", 
        "OrderId": "101", 
        "TenderState": 2, 
        "AmountPurchase": 80.50, 
        "OriginalAmountPurchase": 100.00 
    } 
} 

HTTP/1.1 200 OK 
Content-type: application/json 
{ 
    "Tender": { 
        "Id": "1042", 
        "TenderOptionId": "0", 
        "OrderId": "101", 
        "TenderState": 2, 
        "AmountPurchase": 80.50, 
        "OriginalAmountPurchase": 100.00 
    } 
} 

Description

Updates a tender. It is possible that the AmountPurchase in an updated tender will not be the same as the AmountPurchase in the original tender. E.g. A $100 purchase on a giftcard is completed for the remaining amount on the card ($80.50).

The Id property must point to a valid tender and match the {tender-id} in the request URL. The OrderID property must point to a valid order.

Request

The request body contains a PATRequest with the Tender property populated by a Tender.

Parameter	Type	Description
tender-id	String	Required. The id of the tender being updated.

Response

If successful, this method returns a PATResponse object with the Tender property populated by a Tender. In most cases the Tender in the response will mirror the request.

Properties

Name	Type	Description
Id	String	Unique identifier. Read only.
TenderOptionId	String	The id of the tender option the operator selected to create this tender
TenderState	Integer	The state of a tender is defined by the TenderState property. The initial state is set to Pending (0). When the payment is complete the Tender object will be updated and the TenderState changed to CompletedSuccessful (1) or CompletedUnsuccessful (2).
AmountPurchase	Decimal	The amount of this tender (see notes)
Original AmountPurchase	Decimal	If the tender amount is changed (e.g. A $100 purchase on a gift card is completed for the remaining amount on the card - $80.50) this value will reflect the original tender amount before it was changed.
OrderId	String	The id of the order this tender is attached to.

Create EFTPOS Command

POST /api/eftpos/commands 
{ 
    "EFTPOSCommand": { 
        "TenderId": "0",  
        "OriginalEFTPOSCommandId": "0",  
        "EFTPOSCommandType": 0,  
        "EFTPOSCommandState": 20 
        "AccountType": "", 
        "AmtCash": 0.0, 
        "AmtPurchase": 100.0, 
        "AmtTip": 0.0, 
        "AmtTotal": 0.0, 
        "Application": "", 
        "AuthCode": "", 
        "Caid": "", 
        "Catid": "", 
        "CardName": "", 
        "CardType": "", 
        "CsdReservedString1": "", 
        "CsdReservedString2": "", 
        "CsdReservedString3": "", 
        "CsdReservedString4": "", 
        "CsdReservedString5": "", 
        "CsdReservedBool1": false, 
        "CutReceipt": false, 
        "CurrencyCode": "", 
        "DataField": "", 
        "Date": "", 
        "DateExpiry": "", 
        "DateSettlement": "", 
        "DialogPosition": "", 
        "DialogTitle": "", 
        "DialogType": "", 
        "DialogX": 0, 
        "DialogY": 0, 
        "EnableTip": false, 
        "EnableTopmost": false, 
        "Merchant": "", 
        "MessageType": "", 
        "PanSource": " ", 
        "Pan": "", 
        "PosProductId": "", 
        "PurchaseAnalysisData": "", 
        "ReceiptAutoPrint": false, 
        "ResponseCode": "", 
        "ResponseText": "", 
        "Rrn": "", 
        "Success": false, 
        "Stan": "", 
        "Time": "", 
        "TxnRef": "", 
        "TxnType": "", 
        "Track1": "", 
        "Track2": "" 
    } 
} 

POST /api/eftpos/commands 
{
   "EFTPOSCommand":{
      "CsdReservedString1":"000000002",
      "CsdReservedString5":"0",
      "DataField":"PROCESSING          PLEASE WAIT         ",
      "EFTPOSCommandType":400,
      "TenderId":"5"
    }
}

POST /api/eftpos/commands 
{
   "EFTPOSCommand":{
      "CsdReservedString5":"C",
      "EFTPOSCommandType":401,
      "Receipt":"------------------------\r\n *** TRAINING MODE ***  \r\n  TEST MERCHANT TITLE   \r\n   TEST MERCHANT NAME   \r\n         LINE2          \r\n                        \r\n15:18:09 04/11/20       \r\n                        \r\nCREDIT ACCOUNT          \r\n                        \r\nPURCHASE   AUD     $1.00\r\nSURCHARGE  AUD     $0.22\r\n                --------\r\nTOTAL      AUD     $1.22\r\n                        \r\nAPPROVED -  00          \r\n                        \r\nPLEASE RETAIN AS RECORD \r\n      OF PURCHASE       \r\n------------------------\r\n",
      "TenderId":"5"
   }
}

HTTP/1.1 200 OK 
Content-type: application/json 
{ 
    "EFTPOSCommand": { 
        "TenderId": "0",  
        "OriginalEFTPOSCommandId": "0",  
        "EFTPOSCommandType": 0,  
        "EFTPOSCommandState": 20 
        "AccountType": "", 
        "AmtCash": 0.0, 
        "AmtPurchase": 100.0, 
        "AmtTip": 0.0, 
        "AmtTotal": 0.0, 
        "Application": "", 
        "AuthCode": "", 
        "Caid": "", 
        "Catid": "", 
        "CardName": "", 
        "CardType": "", 
        "CsdReservedString1": "", 
        "CsdReservedString2": "", 
        "CsdReservedString3": "", 
        "CsdReservedString4": "", 
        "CsdReservedString5": "", 
        "CsdReservedBool1": false, 
        "CutReceipt": false, 
        "CurrencyCode": "", 
        "DataField": "", 
        "Date": "", 
        "DateExpiry": "", 
        "DateSettlement": "", 
        "DialogPosition": "", 
        "DialogTitle": "", 
        "DialogType": "", 
        "DialogX": 0, 
        "DialogY": 0, 
        "EnableTip": false, 
        "EnableTopmost": false, 
        "Merchant": "", 
        "MessageType": "", 
        "PanSource": " ", 
        "Pan": "", 
        "PosProductId": "", 
        "PurchaseAnalysisData": "", 
        "ReceiptAutoPrint": false, 
        "ResponseCode": "", 
        "ResponseText": "", 
        "Rrn": "", 
        "Success": false, 
        "Stan": "", 
        "Time": "", 
        "TxnRef": "", 
        "TxnType": "", 
        "Track1": "", 
        "Track2": "" 
    } 
} 

Description

Create an EFTPOS command. The fields defined will vary based on the EFTPOSCommandType as described in the Properties section below. EFTPOSCommandType are 200 for TransactionEvent, 400 for DisplayEvent, and 401 for PrintEvent.

Request

The request body contains a PATRequest with the EFTPOSCommand property populated by an EFTPOSCommand

Response

If successful, this method returns a PATResponse object with the EFTPOSCommand property populated by an EFTPOSCommand. In most cases the EFTPOSCommand in the response will mirror the request.

Properties

Note: All message handling should be case-insensitive.

TransactionEvent

Name	Type	Description
Id	String	Unique identifier. Read only.
TenderId	String	Id of the tender that this EFTPOS command is associated with
OriginalEFTPOS CommandId	String	The id of the original EFTPOS request if this is an event.
EFTPOSCommand Type	Integer	200
EFTPOSCommand State	Integer	AwaitingDeviceAck = 0, AwaitingDeviceResponse = 10, CompletedSuccessful = 20, CompletedUnsuccessful = 30
AccountType	String	The account type used
AmtCash	Decimal	The cash amount
AmtPurchase	Decimal	The purchase amount
AmtTip	Decimal	The tip amount
AmtTotal	Decimal	The total amount
Application	String	The card application used
AuthCode	String	The transaction authorisation code
Caid	String	The CAID of the terminal used
Catid	String	The CATID of the terminal used
CardName	String	N/A
CardType	String	N/A
CsdReservedString1	String	N/A
CsdReservedString2	String	N/A
CsdReservedString3	String	N/A
CsdReservedString4	String	N/A
CsdReservedString5	String	N/A
CsdReservedBool1	Boolean	N/A
CutReceipt	Boolean	N/A
CurrencyCode	String	The transactions currency code
DataField	String
Date	String	The date
DateExpiry	String	N/A
DateSettlement	String	The settlement date of the transaction
DialogPosition	String
DialogTitle	String
DialogType	String
DialogX	Integer
DialogY	Integer
EnableTip	Boolean	N/A
EnableTopmost	Boolean
Merchant	String
MessageType	String
PanSource	String	N/A
Pan	String	N/A
PosProductId	String
PurchaseAnalysisData	String	Purchase Analysis Data, contains any transaction specific tag data
ReceiptAutoPrint	Boolean
ResponseCode	String	The response code from the acquiring bank
ResponseText	String	The response text associated with the response code
Rrn	String	Retrieval reference number
Success	Boolean	Status of the transaction
Stan	String	System Trace Audit Number
Time	String	The time
TxnRef	String	Transaction reference number
TxnType	String	Transaction type, eg. Purchase
Track1	String	N/A
Track2	String	N/A

DisplayEvent

Name	Type	Description
EFTPOSCommand Type	Integer	400
TenderId	String	Id of the tender that this EFTPOS command is associated with
DataField	String	The text displayed in the terminal.
CsdReservedString1	String	N/A
CsdReservedString5	String	N/A

PrintEvent

Name	Type	Description
EFTPOSCommand Type	Integer	401
TenderId	String	Id of the tender that this EFTPOS command is associated with
Receipt	String	The id of the original EFTPOS request if this is an event.
CsdReservedString5	String	N/A

Custom Deployment

Linkly recommends using the Linkly Pay at Table installer to install and configure the Linkly Pay at Table extension.

However, if a custom deployment is required follow these steps:

1. Ensure the latest production Linkly software is installed
2. Copy TPP2_PayAtTable.bcx from the latest production installer to the Linkly install directory (by default %PROGRAMFILES(x86)%\PC_EFT)
3. Configure registry settings as required
4. Restart the Linkly EFT-Client service

REST Server Authorization

The following options are available to secure the communication between the POS and the Pay-at-table component:

Authorisation Header

The POS server developer needs to provide the authorization header type (Basic or Bearer) and token for the Pay-at-table component to use when sending the API requests. For testing, this value can be set in the AUTH_HEADER_VALUE as described in Registry Settings. For production deployment, this value must be configured per lane or for cloud setup be given to Linkly Cloud Portal admin.

Server-side validation

The Pay-at-table component can also be configured to validate the server certificates by setting VERIFY_SERVER_CERT to 1 and the CA_CERT_FILE to the server CA certificate file path in the registry (see Registry Settings). For production deployment, this value and the actual server CA certificate file must be configured per lane or for cloud setup be given to Linkly Cloud Portal admin.

Client-side validation

The Pay-at-table component can also be configured to send client certificates for each API request to the POS server. The POS server can then validate the certificate it receives based on whichever criteria agreed with Linkly. For testing, SEND_CLIENT_CERT must be set to 1. The CLIENT_CERT_FILE and CLIENT_PRIVKEY_FILE must also be set as described in Registry Settings. For production deployment, this value and the actual certificate files must be configured per lane or for cloud setup must be requested to Linkly Cloud Portal admin.

Error Codes

The following error codes will be displayed in the terminal if any of the described scenarios occur:

Code	Description
ZA	Failed to retrieve table
ZB	Failed to create tender
ZC	Failed to update tender
ZD	Failed to retrieve order
ZE	Failed to retrieve settings
ZF	Failed to update order before tendering
ZG	Failed to update order after tendering

Registry Settings

The following values are all STRING types, and set in the registry under HKEY_LOCAL_MACHINE\SOFTWARE\CullenSoftwareDesign\EFTCLIENT\DLLS\TPP-PAT for x86 and HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\CullenSoftwareDesign\EFTCLIENT\DLLS\TPP-PAT for 64-bit

Field	Description	Default	Example
PAT_FUNC	Defines the function code to initiate Pay-at-table workflow. FUNC+X.	8787	8787
USE_LOCAL_POS	1 for local POS, 0 for REST server. Determines which POS type to connect to.	0
PRE_TXN_DELAY	The amount of time to wait (in milliseconds) after exiting slave mode and before sending the transaction request to the EFTClient. Some pinpads take some time to switch slave mode. Max is 5 seconds. Format is X0000 where X is the acquirer and 0000 is the delay in milliseconds.	C2000 (CBA terminal requires 2s)	C2000X0010
POST_TXN_DELAY	The amount of time to wait (in milliseconds) after receiving the TransactionEvent from the pinpad, before entering back to slave mode. Some pinpads take some time to switch slave mode. Max is 5 seconds. Format is X0000 where X is the acquirer and 0000 is the delay in milliseconds.	C0060	C0060X0010
INPUT_TIMEOUT	The amount of time (in seconds) to wait for user input.	60	60
EXIT_ON_CANCEL	If 1, exits Pay-at-table when user presses cancel on the pinpad. Otherwise, it will the show previous page.	0	0
SERVER_BASE_URI	POS REST server url. Required if USE_LOCAL_POS is 0. If port is not given, defaults to 443 for https, 80 for http.	empty	https://localhost:44301/payattable
AUTH_HEADER_VALUE	The Authorisation header value used for validating itself to the server.	empty	Basic abY5D3YyYUtTQkN4YVU5QW53XVd7dCt4YTk2RUtyM4JDWkt1RkRkUGZYTT06NTAyOQ==
REQUEST_PARAMS	Any additional tags to append to every HTTP request to the server.	empty
VERIFY_SERVER_CERT	If 1, enables server certificates verification against the Windows Trusted Root store and the given CA_CERT_FILE.	0
CA_CERT_FILE	The path to the CA certificate file to verify the server certificate against. You must specify this if you're using self-signed certificate (for testing or development) either using your CA file or your certificate file.	empty	pat-ca.crt
SEND_CLIENT_CERT	If 1, sends the given client certificates (CLIENT_CERT_FILE,CLIENT_PRIVKEY_FILE) to the server.	0
CLIENT_CERT_FILE	Certificate used to verify itself to the server. CLIENT_PRIVKEY_FILE must also be set.	empty	pat.crt
CLIENT_PRIVKEY_FILE	The CLIENT_CERT_FILE private key file; used to verify itself to the server. CLIENT_CERT_FILE must also be set.	empty	pat.key
RESTORE_LAST_TXN	If 1, it will attempt to process the last transaction which was not sent to the POS. This is triggered from the start of the workflow via PAT_FUNC or payment menu.	0
PAT_MODE	Determines the PAT mode tag value. 0 - disabled, 1 - customer input is enabled on the pinpad with dialogs, 2 - customer input is enabled on the pinpad without displays.	1	1

Tipping

The Linkly tipping feature supports the ability for customers to collect a tip on the terminal as part of the payment transaction.

Linkly's components will manage the configuration and the terminal is used to interact with the cardholder to streamline the process of tipping.

To enable tipping, configure the tipping values in the Linkly EFT-Client UI and set EnableTip to '1' in the transaction request.

If a tip is applied:

• the AmtTip field will be populated in the TransactionEvent, and will contain the value of the tip applied in cents
• the AMT PAD tag will be present in the TransactionEvent, and will contain the total value of the sale (e.g. purchase amount + surcharge + tip)

This feature supports the following tip entry methods:

• Manual amount entry where the cardholder selects the amount to tip
• Configurable percentages for automatic tip addition, eg. 5%, 10%, 15%

To provide POS partners with the flexibility to use their own tipping solutions Linkly supports the following requests as part of the DoTransaction method.

The TIP tag can be used by the POS to send the TIP value to the terminal for inclusion on the customer copy of the eftpos receipt, this is only required if the POS wants to implement it's own tipping solution, for all other instances nothing is needed from the POS to enable tipping for a merchant.

TIP tag definition

API Specification

Methods

Display Control Panel

This command will instruct the EFTCLIENT to display the EFTPOS control Panel which will allow the user to initiate EFTPOS operations and perform EFTPOS configurations (a password is required).
While the control panel is active all further calls will fail.
The operator can dismiss the control panel that will cause the EFTCLIENT to fire a response back to the POS.

Request:

Byte Position	Tag Name	Length	Description
0	Start Flag	1	Start Flag always '#'
1	Length	4	Length of message including start and length fields
5	Command Code	1	'5' = displaycontrolpanel
6	Sub Code	1	0' = Display Full Control Panel '1' = Display Settlement Control Panel only '2' = Display Journal Viewer Control Panel only '3' = Display Pinpad Setup Control Panel only '4' = Display Status Control Panel only
7	ReceiptAutoPrint	1	'0' = POS printing '1' = Windows Printer '9' = Internal EFTPOS Terminal Printer
8	CutReceipt	1	Flag to allow the EFT-Client to cut the receipt.
9	ReturnType	1	'0' = return response immediately (default) '1' = return response when control panel is closed. '2' = return response immediately and when the control panel is closed. V3 and CE client onward only

Response:

Byte Position	Tag Name	Length	Description
0	Start Flag	1	Always = '#'
1	Length	4	Length of message including start and length fields
5	CommandCode	1	'5' = displaycontrolpanel
6	SubCode	1	' ' (space)
7	Success	1	'0' = Fail '1' = Success
8	Response Code	2	Response Code For the Call
10	Response Text	20	Response text associated with the response code

---

Set Dialog

This command will instruct the EFTCLIENT to use the parameters sent as the dialog positions for all screen displays. This will be remembered until the TCP/IP Interface restarts.
The Response will return immediately.

Request:

Byte Position	Tag Name	Length	Description
0	Start Flag	1	Always = '#'
1	Length	4	Length of message including start and length fields
5	CommandCode	1	Always '2'
6	SubCode	1	' ' (space) '5' - See Note 1
7	Type	1	'0' = standard, '1' = Touch, '2' = Hidden
8	DialogX	4	X position of the Linkly Dialog Window
12	DialogY	4	Y Position of the Linkly Dialog Window
16	DialogPosition	12	'Center' 'TopLeft' 'TopRight' BottomLeft BottomRight
28	TopMost	1	'1' = True '0' = False
29	Title	32	Title of the dialog window

Response

Byte Position	Tag Name	Length	Description
0	StartFlag	1	Always = '#'
1	Length	4	Length of message including start and length fields
5	CommandCode	1	Always '2'
6	SubCode	1	' ' (Space)
7	SuccessFlag	1	'0' = Failed '1' = Success

Note 1: If the subcode is set to '5', the POS will not receive any display events from the client. This can be re enabled by re-sending the SetDialog with subcode as a space.
The registry setting:
CLIENT\IP_INTERFACE_NO_POS_DISPLAY_MSG (DWORD default to 0)
- 0 = Let POS decide whether to get displayevents via SetDialog.
- 100 = Never send dialogs to POS.

---

Settlement

Forces a settlement with the acquirer (bank) and retrieves the totals since the last acquirer settlement. With certain settlement types (shift Totals) the ResetTotals property should also be set to indicate if the stored totals should be cleared (reset to zeros).

Note: Not all acquirers support all TxnTypes for this function.

Request

Byte Position	Tag Name	Length	Description
0	Start Flag	1	Always = '#'
1	Length	4	Length of message including start and length fields
5	CommandCode	1	'P' = Settlement
6	SubCode	1	'S' = Settlement 'P' = Pre-settlement 'L' = Last Settlement 'U' = Summary Totals 'H' = Sub Totals or Shift Totals 'I' = Transaction Listing
7	Merchant	2	"00" Merchant Acquirer Code (00 for EFTPOS) See Appendix A - Merchant codes
9	ReceiptAutoPrint	1	'0' = POS printing '1' = Windows Printer '9' = Internal EFTPOS Terminal Printer
10	CutReceipt	1	'1' = Cut '0' = Don't Cut
11	ResetTotals	1	'1' = Reset '0' = Don't Reset
12	App	2	'00' = EFTPOS See Appendix D for other options
14	PurchaseAnalysisData	3	Length of the following Purchase Analysis Data field. If the field is blank set this to "0000"
17	PurchaseAnalysisData	XXXX	Purchase Analysis Data Property. Leave this blank by default. Please see Appendix B for the format of this field.

Response

Byte Position	Tag Name	Length	Description
0	StartFlag	1	Always = '#'
1	Length	4	Length of message including start and length fields
5	CommandCode	1	'P' = Settlement
6	SubCode	1	' ' (Space)
7	Success lag	1	'0' = Failed '1' = Success
9	Response Code	2	Response Code from the bank for the settlement
11	Response Text	20	Response text associated with the response code
31	SettleCardCount	9	The number of card settlement records contained within the property Settlement Card Data.
34	SettleCardData Length	3	Length of the following Card Data Field
37	SettleCardData	*	Breakdown of totals by cards showing purchase, cashout and refund
*	TotalsData Length	3	Length of the following Totals Data Field
*	TotalsData	*	A totals record containing the locally stored terminal totals.
*	PurchaseAnalysisData	3	Length of the following Purchase Analysis Data field. This field is optional and may not be present. If the field is blank set this to "0000"
*	PurchaseAnalysisData	XXXX	Purchase Analysis Data property. Leave this blank by default. Please see Appendix B for the format of this field.

---

Logon

This command will instruct the EFTCLIENT to logon the EFT device that is attached.

Request

Byte Position	Tag Name	Length	Description
0	Start Flag	1	Always = '#'
1	Length	4	Length of message including start and length fields
5	CommandCode	1	'G' = Logon
6	SubCode	1	' ' (Space) = standard logon '4' = "RSA_LOGON" '5' = "TMS_FULL" '6' = "TMS_PARAMS" '7' = "TMS_SW" '8' = Logoff
7	Merchant	2	"00" = EFTPOS See Appendix A - Merchant codes
9	ReceiptAutoPrint	1	'0' = POS printing, '1' = Windows Printer, '9' = Internal EFTPOS Terminal Printer
10	CutReceipt	1	'1' = Cut '0' = Don't Cut
11	App	2	'00' = EFTPOS See Appendix D for other options
13	PurchaseAnalysisData	3	Length of the following Purchase Analysis Data field. If the field is blank set this to "000"
16	PurchaseAnalysisData	XXXX	Purchase Analysis Data property. Leave this blank by default. Please see Appendix B for the format of this field.

Response

Byte Position	Tag Name	Length	Description
0	StartFlag	1	Always = '#'
1	Length	4	Length of message including start and length fields
5	CommandCode	1	'G' = Logon
6	SubCode	1	' ' (Space)
7	SuccessFlag	1	'0' = Fail '1' = Success
8	Response Code	2	Response Code from the bank regarding the logon
10	Response Text	20	Response text associated with the response code
30	Caid	8	ID of the eftpos terminal
38	Caid	15	ID of the Merchant performing the sale
53	BankDate	6	DDMMYY
59	BankTime	6	HHMMSS
65	Stan	6	The Systems Trace Audit Number of the last transaction performed. (0-999999).
71	PinpadVersion	16	Software Version running on the eftpos terminal.
87	PurchaseAnalysisData	3	Length of the following Purchase Analysis Data field. If the field is blank set this to "000"
90	PurchaseAnalysisData	XXXX	Purchase Analysis Data property. Leave this blank by default. Please see Appendix B for the format of this field.

---

Transaction

This command will instruct the EFTCLIENT to perform an EFTPOS transaction.

Request

Byte Position	Tag Name	Length	Description
0	Start Flag	1	Always = '#'
1	Length	4	Length of message including start and length fields
5	CommandCode	1	'M'
6	SubCode	1	'0'
7	Merchant	2	Default to '00' See Appendix A - Merchant codes
9	TxnType	1	Always uppercase. See Appendix F - Txn Type
10	TrainingMode	1	'1' = Training Mode on '0' = Training Mode off
11	EnableTip	1	'0' = no tipping '1' = tipping default 0
12	AmtCash	9	Left zero filled. Eg $1.00 = 000000100
21	AmtPurchase	9	Left zero filled. Eg $1.00 = 000000100
30	AuthCode	6	default to 6 spaces (not used for most cases)
36	TxnRef	16	Unique Reference Number for this transaction
52	ReceiptAutoPrint	1	'0' = POS printing, '1' = Windows Printer, '9' = Internal EFTPOS Terminal Printer
53	CutReceipt	1	'1' = Cut '0' = Don't Cut
54	PanSource	1	See PanSource property in ActiveX specification ' ' (Space) PINpad will read card using internal card reader, 'K' Manual Entry of card details using DateExpiry and Pan properties, 'S' Track2 property contains application supplied card details read directly form a magnetic stripe reader (MSR)
55	Pan	20	Pan if manually entered
75	DateExpiry	4	MMYY of Manually entered Card Expiry Date
79	Track2	40	Track 2 details if card was swiped by POS
119	AccountType	1	Leave as ' ' by default
120	App	2	'00' = EFTPOS See Appendix D for other options
122	RRN	12	Retrieval Reference Number for the transaction
134	CurrencyCode	3	Option code to indicate requested currency. Leave as spaces unless required.
137	OriginalTxnType	1	Type of original transaction. Only used in a voucher transaction
138	Date	6	DDMMYY for voucher or completion only
144	Time	6	HHMMSS for voucher or completion only
150	Reserved	8	Reserved for the future.
158	PurchaseAnalysisData	3	Length of the following Purchase Analysis Data field. If the field is blank set this to "000"
161	PurchaseAnalysisData	XXXX	Purchase Analysis Data property. Leave this blank by default. Please see Appendix B for the format of this field.

Response

Byte Position	Tag Name	Length	Description
0	Start Flag	1	Always = '#'
1	Length	4	Length of message including start and length fields
5	CommandCode	1	'M'
6	Sub Code	1	'0'
7	Success	1	'0' = Failed '1' = Success
8	Response Code	2	Response code from the bank
10	Response Text	20	Response text associated with the response code
30	Merchant	2	See Appendix A - Merchant codes
32	TxnType	1	See Appendix F - Txn Type
33	AccountType	7
40	AmtCash	9	Left zero filled. Eg $1.00 = 000000100
49	AmtPurchase	9	Left zero filled. Eg $1.00 = 000000100
58	AmtTip	9	Left zero filled. Eg $1.00 = 000000100
67	AuthCode	6	Authorisation code.
73	TxnRef	16	Application supplied reference number 16 characters in length.
89	Stan	6	The Systems Trace Audit Number of the last transaction performed. (000000-999999).
95	Caid	15	Card Acceptor ID, also known as the "Merchant" ID.
110	Caid	8	Card Acceptor Terminal ID.
118	DateExpiry	4	Set before calling Transaction if a customer's card details are manually entered by the operator.
122	DateSettlement	4	Contains the settlement date for the transaction in 'DDMMYYYY' format
126	Date	6	Date of transaction
132	Time	6	Transaction time returned by the acquirer. 'HHMMSS' format.
138	CardType	20	Indicates the card type used for the transaction as described by the bank.
158	Pan	20	Primary Account Number. Loaded with the customer card number for manually entered transactions
178	Track2	40	Contents of magnetic card track 2.
218	RRN	12
230	CardName	2	This property actually returns the Card Bin number.
232	TxnFlags	8	See Note 1
240	Balance Received from Host	1	'0' = FALSE '1' = TRUE
241	AvailableBalance	9
250	ClearedFundsBalance	9
259	PurchaseAnalysisData	3	Length of the following Purchase Analysis Data field. If the field is blank set this to "000"
262	PurchaseAnalysisData	XXXX	Purchase Analysis Data property. Leave this blank by default. Please see Appendix B for the format of this field.

Note 1: Txn Flags

Index	Contents
0	Offline Transaction. '1' = true '2' = false
1	Receipt Printer '1' = true '2' = False
2	Manual Card Entry. '0'=unknown, 'S'=swiped, 'K'=Keyed, 'E' for contact chip card 'C' for contactless chip card
3	Communication method. '0' = unknown, '1'=P66, '2'=Argent, '3'=X25
4	Currency: '0' = AUD '1' = Currency Converted
5	Paypass. '0' = non-paypass '1' = PayPass
6	Undefined
7	Undefined

---

Query Card

This command will allow the POS to use the EFT device to read track 1 and 2 of a magnetic card.

Request

Byte Position	Tag Name	Length	Description
0	Start Flag	1	Always '#'
1	Length	4	Length of the message including the start and length fields
5	CommandCode	1	'J' = Query Card
6	SubCode	1	Defines if the user selects their account as part of the query card process. '0' =Don't select account '1' =Select account plus Read card Added in v1.06 '5' = Get Account only
7	App	2	'00' = EFTPOS See Appendix D
9	Merchant	2	'00' See Appendix A - Merchant codes
11	PurchaseAnalysisData	3	Length of the following Purchase Analysis Data field. If the field is blank set this to "000"
14	PurchaseAnalysisData	XXXX	Purchase Analysis Data Property

Response

Byte Position	Tag Name	Length	Description
0	Start Flag	1	Always = '#'
1	Length	4	Length of the message including start and length field
5	CommandCode	1	'J' = Query Card
6	SubCode	1	If "Sub Code" was set to 0 in the request this will be blank, otherwise it will contain the account selected. Added in v1.06
7	SuccessFlag	1	'0' = Failed '1' = Success
8	Response Code	2	Response Code for the call.
10	Response Text	20
30	Track2	40
70	Track1 or Track3	80
150	TracksRead	1	'1' = track1 only '2' = Track2 only '4' = track3 only Byte Combinations to indicate others Eg '3' = tracks 1 and 2.
151	Bin Number of card	2	Bin number of the car that was just read ( 00 = unknown)
153	PurchaseAnalysisData	3	Length of the following Purchase Analysis Data field. If the field is blank set this to "000"
156	PurchaseAnalysisData	XXXX	Purchase Analysis Data property. Leave this blank by default. Please see Appendix B for the format of this field.

---

Configure Merchant

This command configures the EFTPOS pinpad Merchant parameters. Only Merchant 0 is available in the current release.

Request

Byte Position	Tag Name	Length	Description
1	Start Flag	1	Always = '#'
2	Length	4	Length of the message including start and length field
6	CommandCode	1	'1' = Configure Merchant
7	SubCode	1	'0'
8	Merchant	2	"00" See Appendix A - Merchant codes
10	AIIC	11	Acquiring Institution Identification Code.
21	Nii	3	EFTPOS Network International Identifier.
24	Caid	15
39	Caid	8
47	Timeout	3	timeout for screens (can be overridden, in seconds)
50	App	2	'00' = EFTPOS See Appendix D

Response

Byte Position	Tag Name	Length	Description
1	Start Flag	1	Always = '#'
2	Length	4	Length of the message including start and length field
6	CommandCode	1	'1'
7	SubCode	1	' ' (Space)
8	Success	1	'0' = Failed '1' = Success
9	Response Code	2	Response code from the bank
11	Response Text	20	Response text associated with the response code

---

Reprint Receipt

This command requests the EFTCLIENT to reprint the last financial receipt. The receipt will be a "duplicate copy" which will be identical to the original with the addition of text indicating that it is a duplicate.
This command will invoke a Receipt Print request from the EFTCLIENT. When this event has been answered, the response will be sent back.
When the subcode is set to '2', the receipt data will be sent back in the response.

Request

Byte Position	Tag Name	Length	Description
0	Start Flag	1	Always = '#'
1	Length	4	Length of the message including start and length field
5	CommandCode	1	'C' = Reprint Receipt
6	SubCode	1	'1' = Reprint Receipt '2' = Get Last Receipt
7	Merchant	2	Default to '00' See Appendix A - Merchant codes
9	CutReceipt	1	'1' = Cut '0' = Don't Cut
10	ReceiptAutoPrint	1	'0' = POS printing, '1' = Windows Printer, '9' = Internal EFTPOS Terminal Printer
11	App	2	'00' = EFTPOS See Appendix D for other options
13	OriginalTxnRef	16	Optional. If this is present and is not spaces, then the client will lookup the txn ref# from the system storage and return the data from there. Otherwise this call will get the last receipt form the pinpad. Only available in client greater than 3.1.15.311

Response

Byte Position	Tag Name	Length	Description
0	Start Flag	1	Always = '#'
1	Length	4	Length of the message including start and length field
5	CommandCode	1	'C' = Reprint Receipt
6	SubCode	1	' ' (Space)
7	Success	1	'0' = Failed '1' = Success
8	Response Code	2	Response code from the bank
10	Response Text	20	Response text associated with the response code
30	Receipt		The Actual Receipt. Length = len(msg) - 30

---

Get Last Transaction

This command requests the details of the last transaction processed by the pinpad.
This method could be called by a POS to determine whether a transaction was successful or not following a power failure whilst an EFTPOS transaction was in progress.

Note that the Success property refers to the outcome of the call to Get Last Transaction, not to the result of the transaction retrieved by the call.
If a transaction was recovered, the Success property will be set to True and all other properties will be set to the values they had when the last transaction completed.

Note that the Receipt property is not retrieved by Get Last Transaction - use the method Reprint Receipt to retrieve receipt data for a specified Merchant.

Request

Byte Position	Tag Name	Length	Description
0	Start Flag	1	Always = '#'
1	Length	4	Length of the message including start and length field
5	CommandCode	1	'N' = Get Last Transaction
6	SubCode	1	'0'
7	App	2	'00' = EFTPOS See Appendix D for other options
9	Merchant	2	'00' = EFTPOS See Appendix A - Merchant codes
11	OriginalTxnRef	16	Optional. If this is present and is not spaces, then the client will lookup the txn ref# from the system storage and return the data from there. Otherwise this call will get the last transaction from the pinpad. Only available in clients greater than 3.1.15.311

Response

Byte Position	Tag Name	Length	Description
0	Start Flag	1	Always = '#'
1	Length	4	Length of the message including start and length field
5	CommandCode	1	'N' = Get Last Transaction
6	Sub Code	1	'0'
7	Success	1	'0' = Failed '1' = Success
8	LastTxnSuccess	1	'0' = Failed '1' = Success
9	Response Code	2	Response code from the bank
11	Response Text	20	Response text associated with the response code
31	Merchant	2	See Appendix A - Merchant codes
33	TxnType	1	See Appendix F - Txn Type
34	AccountType	7	Account Used in the transaction
41	AmtCash	9	The amount of cash out for the transaction.
50	AmtPurchase	9	The purchase amount for the transaction.
59	AmtTip	9	Amount of tip given (if any).
68	AuthCode	6	Authorisation Code
74	TxnRef	16	Contains the cheque serial number if the Get Last request is directed at Cheque Auth
90	Stan	6	The Systems Trace Audit Number of the last transaction performed. (000000-999999).
96	Caid	15	Card Acceptor ID, also known as the "Merchant" ID.
111	Caid	8	Card Acceptor Terminal ID.
119	DateExpiry	4	Set before calling Transaction if a customer's card details are manually entered by the operator.
123	DateSettlement	4	Contains the settlement date for the transaction in 'DDMMYYYY' format
127	Date	6	Contains the settlement date for the transaction in 'DDMMYYYY' format
133	Time	6	Transaction time returned by the acquirer. 'HHMMSS' format.
139	CardType	20	Indicates the card type used for the transaction as described by the bank.
159	Pan	20	Primary Account Number. Loaded with the customer card number for manually entered transactions
179	Track2	40	Contents of magnetic card track 2.
219	RRN	12
231	CardName	2	This property actually returns the Card Bin number.
233	TxnFlags	8	See Note 1.
241	Balance received from host	1	'0' = false '1' = true
242	Amount Balance	9
251	Cleared Funds Balance	9
260	PurchaseAnalysisData	3	Length of the following Purchase Analysis Data field. This field is optional and may not be present.
263	PurchaseAnalysisData	XXXX	Purchase Analysis Data property. Leave this blank by default. Please see Appendix B for the format of this field.

Note 1: Txn Flags

Index	Contents
0	Offline Transaction. '1' = true '2' = false
1	Receipt Printer '1' = true '2' = False
2	Manual Card Entry. '0'=unknown, 'S'=swiped, 'K'=Keyed, 'E' for contact chip card 'C' for contactless chip card
3	Communication method. '0' = unknown, '1'=P66, '2'=Argent, '3'=X25
4	Currency: '0' = AUD '1' = Currency Converted
5	Paypass. '0' = non-paypass '1' = PayPass
6	Undefined
7	Undefined

---

Status Inquiry

Queries the EFTPOS pinpad to return it's status and software version.

Request:

Byte Position	Tag Name	Length	Description
0	Start Flag	1	'#'
1	Length	4	Length of message including start and length tags
5	CommandCode	1	'K'
6	SubCode	1	Type of Status to request '0' by default. '0'= Normal Status '1'= Terminal App Info '2'= App CPAT '3'= App Name Table '4'= Undefined
7	Merchant	2	'00' See Appendix A - Merchant codes
9	App	2	'00'= EFTPOS See Appendix D for other options

Response For Sub Code '0':

Byte Position	Tag Name	Length	Description
0	Start Flag	1	'#'
1	Length	4	Length of message including start and length tags
5	CommandCode	1	'K'
6	SubCode	1	' ' Space Character
7	Success	1	'0'= Fail '1'= Success
8	Response Code	2	Response code for the call
10	Response Text	20
30	Merchant	2
32	AIIC	11
43	NII	3
46	Caid	15
61	Caid	8
69	Timeout	3	000 - 255 (Seconds)
72	LoggedOn	1	'1' = LoggedOn '0' = Logon Required
73	PinpadSerialNumber	16
89	PinPadVersion	16
105	EFTPOSNetwork	32	Bank network currently connected to
137	DataField Length	3	Length of the data field to follow
140	DataField	XXX

---

ReceiptEvent

This event is fired from the EFTCLIENT to the POS. The POS MUST respond to this event before the EFTCLIENT will continue.

Request:

Byte Position	Tag Name	Length	Contents
0	Start Flag	1	'#'
1	Length	4	Length of message including start and length fields
5	CommandCode	1	'3'
6	SubCode	1	See Note 1
7	Receipt	X	Length = Len(msg) -7 This field will only be present if the sub-code is of type 'R'

Response:

Byte Position	Tag Name	Length	Contents
0	Start Flag	1	'#'
1	Length	4	Length of message including start and length fields
5	CommandCode	1	'3'
6	SubCode	1	' ' Space Character

Note 1:

Receipt Type	Description
R	Receipt present for POS to print
C	Customer receipt about to be printed
M	Merchant receipt about to be printed
S	Settlement receipt about to be printed
L	Logon receipt about to be printed
A	Audit receipt about to be printed
U	Duplicate receipt about to be printed
B,D,E,F,G,H,I,J,K,N,O,P,Q,T,V,W,X,Y,Z	Unknown receipt about to be printed

---

Display Request

Enables the POS to request custom dialog displays.

Request

Byte Position	Tag Name	Length	Contents
0	Start Flag	1	'#'
1	Length	4	Length of message including start and length fields
5	CommandCode	1	'S'
6	SubCode	1	'0'
7	NumberofLines	2	Number of lines of text that will follow (normally 02)
9	LineLength	2	Length of each line of text that will follow (normally 20)
11	DisplayText	40	The text to display. Length is number of lines * line length
51	Cancel Key Flag	1	Indicates whether the CANCEL key can be pressed. '0' = Disabled '1' = Enabled
52	Accept/Yes Key Flag	1	Indicates whether the ACCEPT/YES key can be pressed. '0' = Disabled '1' = Enabled
53	Decline/No Key Flag	1	Indicates whether the DECLINE/NO key can be pressed. '0' = Disabled '1' = Enabled
54	Authorise Key Flag	1	Indicates whether the AUTHORISE key can be pressed. '0' = Disabled '1' = Enabled
55	InputData Field Key	1	Input Data Field Enabled Key. See Note 1
56	OK Key Flag	1	Indicates whether the OK key can be pressed. '0' = Disabled '1' = Enabled
57	Reserved (Not Defined)	1	Reserved (Not Defined)
58	Reserved (Not Defined)	1	Reserved (Not Defined)
59	Graphic Code	1	See Graphics Code table below.
60	PurchaseAnalysisData Length	3	Length of the following PAD tag. This tag is optional and may not be present. If the tag is blank set this to '000'
63	PurchaseAnalysisData	XXX	Purchase Analysis Data property. See Appendix B for the format for this tag

Graphics Code

Graphic Code	Description
'0'	Processing.avi
'1'	Verify.avi
'2'	Question.avi
'3'	Card.avi
'4'	Account.avi
'5'	Pin.avi
'6'	Finished.avi

Note 1:
This tag is set if the Authorise Key Flag is set.
the Input Field Key values can be:
'1'= Normal ASCII input
'2'= Formatted Amount entry ($0.cc)
'3'= 2 decimal place formatted entry without dollar sign
'4'= Masked Password entry
'5'= Supervisor Request from pinpad
'6'= One key input from POS. As soon as one key is pressed on the POS, the key is sent to the pinpad
'7'= Barcode + Manual entry
'8'= Barcode only entry
It is mandatory that a POS support option '1' for this key type

---

Send Key Request

This method sends a keystroke from the POS to the pinpad to simulate a transaction dialog button press.
This method is primarily used when aPOS receives a key press via the OnKeyDown() event that is to be used by Linkly as one of the key presses.

Request:

Byte Position	Tag Name	Length	Contents
0	Start Flag	1	'#'
1	Length	4	Length of message including start and length fields
5	CommandCode	1	'Y'
6	SubCode	1	'0'
7	KeyToPress	1	Indicates the key to be pressed. '0' for the CANCEL key or OK key (see Note 1) '1' for the YES key '2' for the NO key '3' for the AUTH key
8	Auth or InputData	60	Entry data collected by POS (see Note 2)

Note 1:
The OK and CANCEL key are actually the same button. The pinpad can only set one or the other at a single time.

Note 2:
The Input Data that is returned if the POS is implementing a custom display with Input using the Display Request

---

Generic POS Command - Display Data

Used to display text on the pinpad screen. Please note this is not supported by all pinpads.

Request:

Byte Position	Tag Name	Length	Contents
0	Start Flag	1	'#'
1	Length	4	Length of message including start and length fields
5	Command Code	1	'X'
6	Sub Code	1	'0'
7	Number of lines of text to display	2
9	Timeout	3	000 - 255 (seconds)
12	Display Map options: Byte 0 = '1' to indicate that the pinpad will display Byte 1 = '1' to indicate that the POS will display	2
14	Pinpad Keymap: Byte 0 = '1' indicates ENTER key allowed Byte 1 = '1' indicates CLEAR key allowed Byte 2-7 = not used	8
22	POS Keymap: Byte 0 = '1' indicates OK button on POS display Byte 1 = '1' indicates CANCEL button on POS display Byte 2-7 = not used	8
30	Pinpad Line length	3	How many chars can fit on one line on the pinpad? standard is 020
33	POS Display Data (2 lines at 20 char each line)	40	First 20 bytes will be on the top line, second 20 bytes will be on the bottom line on the POS dialog box
73	Pinpad Line Data	Number Of Lines * Line Length	Similar to the above, if you have 8 lines at 20 chars each then each block of 20 chars will go on a line.

Response:

Byte Position	Tag Name	Length	Contents
0	Start Flag	1	'#'
1	Length	4	Length of message including start and length fields
5	Command Code	1	'X'
6	Sub Code	1	'1'
7	Response Code	2	Response code for the call
9	Response Text	20
29	Data	X

---

Generic POS Command - Print Data

Used to print data on the pinpads internal printer. Please note this is not supported by all pinpads.

Request:

Byte Position	Tag Name	Length	Contents
0	Start Flag	1	'#'
1	Length	4	Length of message
5	Command Code	1	'X'
6	Sub Code	1	'1'
7	Number of lines to print	2
9	Printer bytemap: Byte 0 = '1' to print on NPT printer Byte 1 = Not supported	2
11	Line length of each print line	3
14	Print data. This is number of lines * line length	number of lines * line length	Everything you wanted to print.

Response:

Byte Position	Tag Name	Length	Contents
0	Start Flag	1	'#'
1	Length	4	Length of message including start and length fields
5	Command Code	1	'X'
6	Sub Code	1	'1'
7	Response Code	2	Response code for the call
9	Response Text	20
29	Data	X

---

Generic Slave Command

This is used to access the pinpad via the Linkly Slave application.

• The slave application is an application in the EFTPOS terminal that can be controlled by the EFT-client and POS.
  This command provides a way for the POS to direct a command to the EFTPOS terminal's slave application.
  
• Depending upon the command issued to the system, there may or may not be a response immediately.
  Also, there may be more that one response to a command. Until the slave application is disabled, it is possible to receive a response at any time.
  
• This request is not recommended to be used unless you have worked directly with Linkly and understand what you are doing.

Request:

Byte Position	Tag Name	Length	Contents
0	Start Flag	1	'#'
1	Length	4	Length of message
5	Command Code	1	'X'
6	Sub Code	1	'Z'
7	Slave Request	n	*@S1004300

Response:

Byte Position	Tag Name	Length	Contents
0	Start Flag	1	'#'
1	Length	4	Length of message
5	Command Code	1	'X'
6	Sub Code	1	'Z'
7	Response Code	2	00 = valid reply 01 = FUNCTION Event The following will be FUNCTION=XXXX (where XXXX is the 1-8 digit function entered on the pinpad (see Note 1))
9	Slave Response	n	Response from Slave application. Only present if response code was '00'. Other response codes may have the response text in this place

Note 1:
The Function Event occurs when a user presses FUNCTION and a number and then enter on the pinpad.
e.g. FUNC 99 [ENTER] on the pinpad will cause this event to occur.
The default client setting is to not allow this event. To enable it, set the following to 1.
\EFTCLIENT\CLIENT\ALLOW_FUNCTION_EVENT_TO_POS (DWORD)

---

Properties

---

AccountType

This property is used in both events and methods, and because of this, there needs to be careful control over the setting of this property.
Response results for this property:

Returned Property	Description
From a 'TransactionReponse'	The Customer account type that was selected in a transaction will be returned as: 'Cheque','Savings', 'Credit', "Account 1", "Account 2", "Account 3", "Account 4" or "Account 5".
From a 'QueryCardResponse'	It will be "0" = Savings, "2" = Cheque, "3" = Credit

---

Aiic

Acquiring Institution Identification Code.
Returned by Status Inquiry.
Applies to Configure Merchant. Note: Not supported by all acquirers.

---

AmtCash

The amount of cash out for the transaction.
The STG Agency Deposit function uses this property to hold the total cash amount to deposit.
Applies to Transaction.

---

AmtCreditLimit

Credit limit amount.
Not used - Reserved for future use.

---

AmtPurchase

The purchase amount for the transaction.
Returned by transaction.

---

AmtTip

The tip amount for the transaction. Contains 0 if no tip was added. Returned by transaction.

---

AuthCode

Authorisation code. Returned by Transaction if the EFTPOS Acquirer returned the AuthCode field. Also required as input to transaction when a Completion is being performed.
Applies to transaction.

---

Caid

Card Acceptor ID, also known as the "Merchant" ID.
Returned by transaction, Logon, Status.
Applies to Configure Merchant.

---

CardType

Indicates the card type used for the transaction as described by the bank. Examples may include: 'AMEX', 'VISA', 'DEBIT'. The possible values of this field may change between acquirers and pinpad versions. To identify the payment type used, reference the CardName field. Returned by TransactionEvent.

---

CardName

This property returns the Card BIN which can be used to identify the type of card payment used.

Card BIN	Description
0	Unknown
1	Debit Card
2	China Union Pay
3	MasterCard
4	Visa
5	American Express
6	Diners Club
7	JCB
8	Private Label Card
9	JCB
10	Maestro
11	JCB
12	Other
13	Cabcharge
14	Bartercard
15	Fuel Card
16	Loyalty
17	Gift Card
18	Return Card
19	Shop Card
20	GE Card
21	Non-FI Card
22	Myer Black Card
23	Fleet Card
24	Motopass
25	Motorcharge
26	Logo 1
27	Logo 2
28	Visa Debit
29	Mastercard Debit
30	Unionpay credit
31	Unionpay debit
51	Wishlist
52	GiveX
53	Blackhawk
54	PayPal
55	Reserved
56	Reserved
57	FDI
58	Reserved
59	WrightExpress
60	Reserved
61	Reserved
63	ePay Universal
64	Incomm
65	AfterPay
66	AliPay
67	Humm
68	First Data Gift Card
69	WeChat
70	Klarna
89	Zip Money
90	TruRating
98	Reserved
99	Reserved

---

Catid

Card Acceptor Terminal ID.
Returned by transaction, logon, status inquiry.
Applies to Configure Merchant.

---

ChqAccount

Cheque Account Number.
NOT Used

---

ChqBranch

Cheque Branch Number.
NOT Used

---

ChqSerialNumber

Cheque Serial Number.
NOT Used

---

ConfigLocked

Set to True if the PINpad configuration parameters are locked.
(If the terminal has stored transactions or there is a reversal pending the terminal details cannot be altered).
NOT Used

---

CutReceipt

Set to True if the receipt should be cut by the printer after the receipt is printed.
Applies to transaction, ReprintReceipt, displaycontrolpanel and Settlement.

---

DataField

A private Data Field.
- For the DisplayEvent this field contains multiple lines of text to display (usually 2 lines of 20 characters each).

*For the QueryCardResponse *
It will contain the following if it was available in the pinpad CPAT:

Description	Length
Card Bin number	1 byte(non ascii)
Account Grouping Code	1 byte
Extended Service Code	1 byte
Processing Code	1 byte
AIIC	6 byte

For the transaction, this field contains the TO/FROM data when a Funds Transfer is performed.

For the logon, this property contains a byte array of values: Currently assigned bytes are byte 0 = EFTPOS txns allowed, byte 1 = Agency txns allowed.
The array will be in the following order:

Index	Content
0	Settlement
1	Pre-Settlement
2	Last-Settlement
3	Sub-Totals
4	Terminal Shift Totals
5	Reserved
6	Transaction Listing
7	SAF Totals
8	Mini-Statement
9	Detailed Cash Statement (STG Agency)
10-15	Reserved

For the status-inquiry, this field will contain the Extra Status information which is used in PX328 Linkly systems and onward.
For a transaction Request, if the TxnType is set to "K", this property will contain data for the pinpad to use in processing the Enhanced PIN command.
This data is in the following format when the MessageType = "0" (status):

Name	Length	Description
SAF Count	4	SAF Count (if pinpad has a SAF)
Network Type	1	'1' = Leased, '2' = Dial-up
Hardware Serial #	16	Actual Serial Number that is unique to the h/w
Retailer Name	40	AS2805 Field 43 (if supported by host)
Options Flags	32	These flags denote the support of various options within the terminal.
Stand in Credit card Limit	9	Max limit allowed for stand-in on credit cards
Stand in Debit card limit	9	Max Limit allowed for stand-in on debit cards
Max number of stand-in transactions	3
Key-handling scheme	1	'0' = Single DES '1' = Triple DES
Maximum Cash Out Limit	9	$$$$$$$cc
Maximum Refund Limit	9	$$$$$$$cc
Current CPAT version	6
Current Name table version	6
Terminal Comms Type	1	'0' = Cable, '1' = Infra-red
Card Misread Count	6
Total # memory pages	4
# free memory pages	4
EFT Terminal Type	4
# applications in terminal	2
# lines on terminal display	2
Hardware inception Date	6	DDMMYY - Date that the hardware serial number was entered into this device.

Supported Functionality Index:

Byte	Description
0	Tipping
1	Pre-Auth
2	Completions
3	Cash-Out
4	Refund
5	Balance Enquiries
6	Deposits
7	Voucher Entry
8	MOTO Transactions
9	Auto Completions
10	Electronic Fallback
11	EMV
12	Training Mode
13	Withdrawal
14	Funds Transfer
15	Start Cash

The Data in the following format is for MessageType = '1' (Terminal Info)

Name	Byte	Description
Eprom Type	1	'Y' = 1Mb, 'X' = 2Mb
Terminal Type	2
OS Version	2
OS CRC	4
BIOS Version	2
BIOS CRC	4
# Free Pages	3
# Applications	2

For each application in the terminal the following will be present:

Name	Byte
Application Number	2
Application Version	2
Active Flag	1
Corrupted Flag	1
Number of code pages	2
CRC for each code page	#pages * 2
Number of data pages

The Data in the following format is for MessageType = '2' (CPAT)

Name	Byte
CPAT Version #	6
# Offline Transactions allowed	3
#card prefix entries	3

For each CPAT entry, the following will be sent:

Name	Byte	Description
Prefix	10
Card Index	2
Card Bin#	2
Account Grouping Code	1
AIIC	11
Processing Code	2
DB card limit	6
CR card limit	6
ESC flag	1	Indicated if the Extended Service code table is to be used for this card.

• The data is in the following format for MessageType = '3' (card name table)

Name	Byte
Card Table version #	6
# card prefix entries	3

For each card name entry, the following will be sent:

Name	Byte
Card Name	20
Bin #	2
Index	2

• The Data is in the following format for MessageType = "4" (Offline Txns)

Name	Byte
Reversal Present	1	True if the reversal is present in the SAF. The first entry will be the reversal. The remainder will be the SAF transactions.
Number of entries	3

For each entry in the SAF, the following will be present:

Name	Byte
Processing Code	6
Transaction Amount	12
Transmission Date/Time	2	MMDDhhmmss
POS entry mode	3
Card Seq #	3
Track2 Details	40	"card data", '=', "expiry date", "pad with end sentinels (?)"
RRN	12
Auth #	6
Cash Out Amount	12

---

Date

Date of transaction
Returned by transaction, logon.

---

DateExpiry

Set before calling transaction if a customer's card details are manually entered by the operator.
Used in conjunction with the Pan property.
Returned by transaction.
Applies to transaction.

---

DateSettlement

Contains the settlement date for the transaction in 'DDMMYYYY' format.
Used as input to settlement with certain EFTPOS acquirers to specify the date for which the settlement details are to be retrieved.
In this case DateSettlement should be blank if the current days totals are to be retrieved.
Returned by transaction Applies to settlement.

---

DialogPosition

Positions the EFTPOS operator panel. For DialogPosition to be recognised, ensure that DialogX and DialogY properties are both set to zero. The operator panel is positioned with a 20 pixel gap between dialog frame and the screen edge. To position the dialog panel at an arbitrary X-Y screen co-ordinate, use the DialogX and DialogY properties instead. The following relative screen positions are valid for DialogPosition:
'TopLeft' 'TopCenter' 'TopRight'
'MidLeft' 'Center' 'MidRight'
'BottomLeft' 'BottomCenter' 'BottomRight'
Applies to transaction, logon, settlement

---

DialogTitle

The title that is to appear on the EFTPOS Dialog. (Up to 32 characters)
Applies to transaction, logon, settlement

---

DialogType

The type of dialog that you want to appear. Valid values are 'normal' and 'touchscreen'. Defaults to 'normal'.

---

DialogX

Positions the EFTPOS operator panel at a precise screen location. Used in conjunction with DialogY property to specify the absolute screen co-ordinates for the top-left corner of the selected operator dialog panel. Set DialogX to a non-zero value less than the screen width minus the width of the selected dialog.
DialogX value of 1 represents the leftmost edge of the screen.
This property can be used to place the Dialog partially offscreen.
Use this property with care.
Applies to transaction, logon, settlement

---

DialogY

Positions the EFTPOS operator panel at a precise screen location. Used in conjunction with DialogX property to specify the absolute screen co-ordinates for the top-left corner of the selected operator dialog panel. Set DialogX to a non-zero value less than the screen width minus the width of the selected dialog.
This property can be used to place the Dialog partially offscreen.
Use this property with care.
DialogY value of 1 represents the topmost edge of the screen.
Applies to transaction, logon, settlement

---

EftPosNetwork

Indicates the network to which the PINpad is connected.
Returned by status-inquiry.

---

EnableErrorDialog

If enabled, the errors "PINpad busy", "PINpad Offline" and other EFTPOS system errors result in an operator dialog being displayed before the active method returns with the error status. If disabled, no dialog is displayed and the active method is failed. The default is for error reporting to be enabled.
When the POS is performing power-fail recovery it is recommended that EnableErrorDialog be set to False during this phase.
Applies to all methods.

---

EnableTip

Set before calling transaction. If EnableTip is True before calling transaction, the customer receipt will have an area for a TIP to be entered. The POS should store all details related to Tip Adjustments, so that the POS can send the tip adjustment to the Linkly system with the transaction method (with TxnType = "T").
Applies to transaction.
Note: Not supported by all acquirers.

---

EnableManualPan

If set to True, the operator can manually enter a card number and expiry date through the EFTPOS Dialog.
Applies to transaction.
Not Used

---

EnableTopmost

If set to True, the EFTPOS Dialog will always be at the top of the window order. The Default is True, and will revert to the default after each method if not reset by caller.
Applies totransaction, logon, settlement
Note: It is not advisable to use this property, as the POS may require bank certification.

---

FileName

The name of the file to download.
Not used - Reserved for future use.

---

Installed

Indicates if the EFTPOS subsystem has been successfully installed. The Installed property will be set to True if the Linkly client product has been successfully installed on the workstation. Installed does not indicate the status of the EFTPOS subsystem and may be used to determine if EFTPOS functionality should be offered to the user.
Property is updated at initialization by the ActiveX control.

---

KVC

This property is used to hold the CVV (card verification value ) of the magnetic card stripe. This field is not mandatory.

---

LastTxnSuccess

Set to True if the last transaction was successful.
Returned by GetLasttransaction.

---

LicenseId

The unique license identification string for the PINpad.
Returned by status-inquiry.
Not Used

---

LoggedOn

Set to True if the PINpad is in a logged on state, False if a logon is required. It is never necessary for an application to use logon to explicitly logon a PINpad as auto-logons are performed.
Returned by status-inquiry.

---

Merchant

Indicates the active Merchant. (Reserved for future use) - Currently only Merchant 0 is supported and setting this property to any other value will result in an error.
Applies to transaction, logon, settlement, and status-inquiry.
Note: Not used - Reserved for future use.

---

MessageType

A property to represent:
- The Message type returned by transaction.
- The Subcode to select in a status-inquiry request.
- The resulting subcode in a status-inquiry

---

Nii

EFTPOS Network International Identifier.
Returned by status-inquiry.
Applies to configMerchant.
Note: Not supported by all acquirers.

---

Pan

Primary Account Number. Loaded with the customer card number for manually entered transactions.
Only credit card details may be entered manually. Refer also to the properties DateExpiry, and PanSource.
Returned by transaction (return format is acquirer dependent any may be in short 6...3 format).
Applies to transaction.

---

PanSource

Indicates the source of the customer card details. The following values are valid for PanSource:

Value	Description
' ' (Space)	PINpad will read card using internal card reader
'K'	Manual Entry of card details using DateExpiry and Pan properties
'S'	Track2 property contains application supplied card details read directly form a magnetic stripe reader (MSR)

The following additional options are only used in MOTO (mail order/telephone order systems) where the Pan source is a manually entered card. Use the above 'K' option for all other manual card options.

Value	Description
'0'	Internet originated transaction
'1'	Telephone originated transaction
'2'	Mail order originated transaction
'3'	Customer present
'4'	Recurring transaction
'5'	Installment

Applies to transaction

---

PinPadPort

The port to which the PINpad is attached. On input, this property may be used to set the specific PINpad port to use. On output, it indicates the PINpad port actually used for the transaction.
Applies to transaction, logon, settlement
Note: Not supported by all acquirers.

---

PinPadSerialNumber

The hardware ID or Serial Number of the attached PINpad.
Returned by status-inquiry.

---

PinPadVersion

The PINpad software name and version (Up to 16 characters).
Returned by status-inquiry, logon.

---

PosProductId

The name of the POS application that is using the ActiveX control. This property should be initialised by the application before using any methods. It is only necessary to set this property once throughout the life of the application (Up to 10 characters).

---

PosVendor

The name of the vendor of the POS application that is using the ActiveX control. This property should be initialised by the application before using any methods. It is only necessary to set this property once throughout the life of the application (Up to 32 characters).

---

PosVersion

The version of the POS application that is using the ActiveX control. (eg v1.23 -> "0123") This property should be initialised by the application before using any methods. It is only necessary to set this property once throughout the life of the application. (4 characters). Suggested format is xxyy where xx is major and yy is minor version numbers.

---

Receipt

Formatted EFTPOS receipt information (Up to 2048 characters).

---

ReceiptAutoPrint

ReceiptAutoPrint	Description
"0"	Return all receipts to the POS in a receipt event. Only supported when async=true
"1"	Print receipts using EFT-Client Windows printer
"7"	Print all merchant/signature receipts from the PINpad printer, return all other receipts to the POS in the transaction/logon/settlement response
"9"	Print all receipts from the PINpad printer

Applies to transaction, logon, settlement displaycontrolpanel

Note: Setting the ReceiptAutoPrint flag to '0' is strongly encouraged.

---

ResetTotals

This property should be set to True if the current totals should be reset when calling settlement
with TxnType of shift Totals.
Applies to settlement.

---

ResponseCode

A 2 character code returned by the bank indicating the result of the transaction.
Returned by all events.

---

ResponseText

A textual description of the bank response code (up to 20 characters).
Returned by all events.

---

ResponseType

The message type of the last transaction.
Returned by GetLasttransaction.

---

SettleCardCount

The number of card settlement records contained within the property SettleCardData.

---

SettleCardData

Not Supported

---

SettleCardTotals

Ascii records containing settlement data for each card type settled. The ascii card records are defined as follows:

Length	Description
20	Card Name
9	Purchase Amount
3	Purchase Count
9	Cash-Out Amount
3	Cash-Out Count
9	Refund Amount
3	Refund Count
1	Totals sign (+ or -)
9	Totals Amount
3	Totals Count

---

Stan

The Systems Trace Audit Number of the last transaction performed. (0-999999).
Returned by transaction, GetLasttransaction, logon.

---

Success

Indicates success or failure of relevant event/method call.
Returned by all events.

---

Time

Transaction time returned by the acquirer. 'HHMMSS' format.
Returned by transaction, logon.

---

Timeout

EFTPOS transaction timeout. Determines the maximum amount of time that the PINpad will wait for a reply from the EFTPOS network. Value is from 10-255 seconds.
Returned by status-inquiry.
Applies to configMerchant.
Note: Not all acquirers support modification of this value.

---

TotalsData

A totals record containing the locally stored terminal totals.

Length	Description
20	Totals Description
9	Purchase Amount
3	Purchase Count
9	Cash-out amount
3	Cash-out count
9	Refund Amount
3	Refund Count
1	Total Sign
9	Total Amount
3	Total Count

For a Mini Statement or a Store and Forward totals message, this field will contain the data sent back in those responses as defined by the bank.
For a settlement with a txntype of "A" (Daily Cash Statement), this field will contain data to be sent to the terminal. The format of this data is up to the terminal application that needs the data.

For each charge card:

Length	Description
11	Card Name
02	Totals bin
03	Credit count
09	Credit amount
03	Debit count
09	Debit amount
09	Net amount

Note: there is only one base record, but the number of charge cards is variable.

---

Track1

Contents of magnetic card track 1 or 3, if either is read by the PINpad.

---

TotalPurchaseCount

The total number of cheques that are to be processed by a STG Agency terminal Deposit function.
Applies to: transaction.

---

Track2

Contents of magnetic card track 2. This property should be loaded by the application prior to calling transaction if the customer card is read by an application Magnetic Stripe Reader.
Query Card returns the contents of track 2 for any card. The format of this field is acquirer dependent any may be in shorted format.
Returned by transaction Applies to transaction.

---

TxnRef

Application supplied reference number up to 16 characters in length. TxnRef can contain any ascii characters between 32 and 127 (decimal).
Important! TxnRef is associated with the EFTPOS transaction and must be unique for each call to transaction.
Returned by transaction, GetLasttransaction.
Applies to transaction.

---

TxnType

Description:
This property should be set to indicate the type of transaction to be performed when calling Transaction or Settlement.
See Appendix F - TxnType.

Settlement Types

• 'S' Settlement
  
• 'P' Pre-Settlement
  
• 'L' Last Settlement
  
• 'U' Sub Totals or Summary Totals for ANZ
  
• 'H' Shift Totals or Subtotals for ANZ
  
• 'I' Txn Listing
  
• 'M' Start Cash
  
• 'F' Store and Forward (SAF) Totals report
  
• 'D' Daily Cash Statement (STG Agency)
  

Returned by transaction Applies to transaction and settlement.
Note: Not all TxnTypes are supported by all acquirers.

---

Value Added Applications

One Button

Overview

The Linkly One button offers a simple entry point for POS developers to send transactions to Linkly supported third party payment applications.

Customers will still need to support each payment type, and have it enabled within the Linkly environment for One button to work.

Instead of needing to implement different transaction types for different applications, the POS need only implement this one. This API requires knowledge of the Linkly Basket.

When a purchase is sent to Merchant 99, the PIN pad will display a menu asking the customer to select which payment type they would like to use for the transaction.

For example, if the merchant has Afterpay, Alipay, and Humm enabled will have the following menu options:

Payment Type

1. Afterpay
2. Alipay
3. Humm

The customer is then able to select which payment option to use.

Payment supported by the One Button API:

• Afterpay
• Alipay
• ePay Wallet (Alipay, WeChat Pay)
• Humm
• Zip
• Klarna

Prerequisites

The One Button API is based on the Core Payments API and requires the POS to implement the same minimum requirements.

Onboarding

Each AppHub product requires a set of credentials to identify and authorise the merchant on the third party's platform. These credentials range from username/password to one-time activation keys and are normally entered manually into the local registry or via a Linkly provided installer. The process for onboarding via Connect is as follows:

1. Merchant gets credentials from the third party
2. Linkly register merchant in Cloud Portal as instore or cloud customer
3. Merchant enters ActivationCode into their lane
4. Linkly perform activation process on customer's AppHub products
5. Linkly deploy and configure selected AppHub products to customer's lane
6. Merchant can now perform AppHub sales.

Transaction Types

Supported Transaction Types

The One Button API provides the following transactional types across AppHub products:

Transaction Types

• Purchase (P)
• Refund (R)

Management of merchant/bank functions

• Reprint Receipt
• Get Last Transaction

Transactional Scenarios

• Partial/Split Payments

Error Handling

• PowerFail Scenarios
• Timeout Scenarios

Purchase

Purchase Request

To call the One Button purchase request, make a Core Payments purchase request with:

• Merchant "99"
• Application "02"

Purchase Response

The CardName and Merchant properties in the response will indicate the payment type selected.

Refund

Refund Request

To call the One Button refund request, make a Core Payments refund request with:

• Merchant "99"
• Application "02".

Refund Response

The refund response is in the format of the transaction response object, see the Transaction section for a detailed breakdown.

The CardName and Merchant properties in the response will indicate the payment type used for the refund.

Management Functions

The POS should implement Linkly Core Payments management functions with:

• Merchant "99"
• Application "02"

Error Handling

The POS should implement error handling as outlined by the Error recovery section.

Third Party payment barcode/QR code timeout

The table below lists how long the bar code or QR code from the payment provider is valid for once it's generated by the customer.

Third Party	Payment Method	Timeout
ZipMoney	Barcode	5 minutes
AfterPay	Barcode	10 minutes
Alipay	QR Code	Unknown
WeChat	QR Code	Unknown
Humm	Barcode	5 minutes

Optional Functionality

Custom Displays

The POS can implement custom display handling using the Core Payments Optional Functionality.

Query Card Functionality

This function can be used by the POS display the app selection screen on the PIN pad to obtain a two digit "merchant id" which can be used in subsequent purchase or refund requests.

The primary use of this function is to allow the POS to perform actions based on the payment type selected by the customer before the payment continues, such as validating if any items exist in the basket which are prohibited for the selected payment type.

If the POS is using this function it must follow the payment flow detailed below:

1. POS sends QueryCard to Linkly
2. Linkly prompts customer to select payment type
3. Customer selects payment
4. Linkly return selected payment to POS
5. POS processes based on returned value
6. POS blocks transaction and ends sale OR POS initiates transaction using Merchant Code in QueryCard response
7. Transaction initiates automatically without additional customer input

Query Card Request

Perform a standard QueryCard with the following property set:

Field Name	Length (characters)	Description	Example
Merchant	2	Must be '99' Identifies this sale as One Button	'99'
App	2	Must be '02' to indicate a

Query Card Response

Field Name	Length (characters)	Description	Example
Merchant	2	Must be '99' Identifies this sale as One Button	'99'
Success	1	Indicates if the transaction was successful	'1' = Success '0' = Failed
Response Code	2	Response code indicating sale status	'00' = Approved 'X0' = No response
Response Text	20	Response message associated with the response code	'TRANSACTION APPROVED'
[Bin Number]	2	2-digit Merchant identifier of payment method selected	'89' = Zip '66' = Alipay '65' = Afterpay

POS Barcode Scanning

This function allows the POS to scan a barcode instead of the PIN pad. The POS will receive a DisplayEvent and must answer with a SendKey; populating the DataEntry field this will be the Barcode for the sale. POS must set the PCM PAD tag's first byte to '1' to indicate it can support this functionality and wants to use it for the transactions.

Transaction Request

Perform a sale with the following Purchase Analysis Data Tag:

Tag Name	Tag Value	Description	Example
PCM	Flag array of functionality supported by POS	POS Capabilities Matrix. First byte = POS can scan Barcode	PCM0011

This will cause the EFT-Client to send a DisplayEvent to the POS with the following properties:

Display Event

Field Name	Length (characters)	Description	Example
NumberOfLines	2	Number of lines of text	'02' – two lines
LineLength	2	Length of each line of text	'20' line is 20 char long
DisplayText	40	Text to display	'SCAN BARCODE'
Cancel Key Flag	1	Indicates whether the CANCEL key can be pressed	'0' = Disabled '1' = Enabled
InputData Field Key	1	See 'Custom Displays' Section	'7'
OK Key Flag	1	Indicates whether the OK key can be pressed	'0' = Disabled '1' = Enabled

The POS must reply to the above display event with a SendKey Request as detailed below:

Send Key Request

The POS must reply to the above display event with a Send Key Request as detailed below:

Field Name	Length (characters)	Description	Example
KeyPressed	1	Indicated which key is to be pressed '0' for the CANCEL key '1' for the YES key '2' for the NO key '3' for the AUTH key	'0' = CANCEL
InputData	60	Entry data collected by POS (the barcode)	209849083

Purchase online, refund in-store

When completing a refund in-store for an online purchase: * The REF pad tag indicates the unique identifier returned from the online purchase * The RFN pad tag does not need to be set * The Merchant field indicates the payment provider to perform the refund

Refund

To call the One Button refund request, make a Core Payments refund request with Application "02", Merchant, and REF pad tag set.

Example refund request object

Field	Description
Command	'M'
App	Set to '02'
Merchant	Indicates the payment provider to perform the refund
TxnType	Set to 'R' to indicate a Refund request
AmtPurchase	Amount to refund via selected provider
CurrencyCode	ISO Currency code (e.g. AUD, NZD). Default AUD
TxnRef	Unique POS reference number
CutReceipt	Indicates to cut or not cut the receipt
ReceiptAutoPrint	Indicates where to print the receipt
PurchaseAnalysisData	Extended fields. See PurchaseAnalysisData requirements below.

PurchaseAnalysisData(PAD)

Tag	Name	Type	Notes	Example
[REF]	Reference Number	string(128)	Indicates the unique identifier returned from the online purchase	REF0360b072c9f-7e96-4de3-a367-d7da6231a919
OPR	OperatorReference	string(128)	POS operator name and id. Format: ID|Name	OPR00766|test
UID	Globally unique value	UUID v4	UUID v4 used to uniquely identify this sale across all registers	UID0367f619126-5fa7-4351-8585-1d4f813019d2
NME	POS Name	string(64)	Name of POS. This should match accreditation POS name	NME007TestPOS
VER	POS Version	string(64)	Version of the POS. This should match accreditation	VER0041.00
VND	POS Vendor ID	UUID v4	A unique UUID v4 which identifies the POS POS product. This value can be hard coded into the build of the POS. e.g. All merchants using the same POS product should supply the same posVendorId value	VND036907b3267-c37d-49c1-a8a2-429f937748c6
PCM	POSCapabilitiesMatrix	string(32)	POS Capabilities Matrix. First byte = POS can scan Barcode	PCM00400000

Third Party	Merchant	REF
Klarna	70	Set to Order Id returned from Klarna API

Refund Response

The refund response is in the format of the transaction response object, see the Transaction section for a detailed breakdown.

The CardName and Merchant properties in the response will indicate the payment type used for the refund.

AppHub Payment specific details:

For response codes related to One button transactions please see the response code section.

ZipMoney:

Receipts:

Below is a Zipmoney Purchase Receipt

Below is a ZipMoney Refund Receipt

Field Mapping

References:

Zip Transaction Receipt

This Reference is generated by ZipMoney and sent to Linkly after a transaction request. Linkly will send this field in the 'REF' PAD Tag. This field is also printed on the receipt under the heading 'ZipMoney Reference:'

Merchant Transaction Reference

This reference is the POS transaction Reference passed to ZipMoney via Linkly. The POS generates this field and passes it in a Transaction Request in the 'TxnRef' field. This field is returned to the POS in a TransactionResponse in the 'TxnRef' field.

AfterPay:

Receipts:

Below is an Afterpay purchase Receipt

Below is an AfterPay Refund Receipt

Field Mapping:

References:

merchantReference

This reference is the POS transaction Reference passed to Afterpay via Linkly. The POS generates this field and passes it in a Transaction Request in the 'TxnRef' field. This field is returned to the POS in a TransactionResponse in the 'TxnRef' field.

orderId

This reference is the AfterPay reference for the sale, this is returned to the POS in the 'REF' PAD Tag. This reference is printed on the receipt under the heading 'AfterPay Order ID:'. This reference is required to perform a refund.

refundId

This reference is only sent for Refunds; it is the AfterPay reference for the refund, this is returned to the POS in the 'REF' PAD Tag. This reference is printed on the receipt under the heading 'AfterPay Refund ID:'

AfterPay

This extension adds to the core EFTPOS payment API that is provided to the POS by the Linkly EFT Client and allows the POS to perform the proprietary AfterPay transactions outlined in this document. This document assumes an existing understanding of the Linkly solution and core API's as covered by the ActiveX interface documentation. This document also assumes an existing understanding and implementation of the Linkly Basket API as cover by the Basket API section

Installation

The AfterPay extension file (TPP_AfterPay.bcx) must be installed to the same folder as the EFT-Client executable (EftClnt.exe) on the POS (by default this is the "C:\PC_EFT" folder). In addition to the basic TPP lane configuration, the AfterPay extension requires various identifiers provided by AfterPay to be configured. This is covered by the installation executable provided by Linkly.

Methods

Note: Optional Fields will ONLY return if the POS is responsible for Token management. Some methods and fields also are only used if the POS is responsible for Token management.

Activation

This logon call is a onetime Activation used to get the AfterPay Device Id and Key for the lane.
Note: Activation via this API call is optional and only needs to be implemented if the POS is to assume responsiblity for Token Management.

Request:

• Set Merchant to '65' for afterpay logon
  
• Set TxnType to 'A' to indicate an Activation.
  
• Set App to '02'
  
• Set PurchaseAnalysisData tags:
  
  • DID - Device name as assigned by AfterPay.
    
  • KEY - Onetime secret as generated by AfterPay
    

• Set Command Code to 'G' to indicate Logon

  Response:

Field	Description
Success	'1' if successful
Response Code	'00' if it was approved
Response Text	response message associated with the response code
PurchaseAnalysisData
HRC	response code from AfterPay
DID	Device Id from AfterPay
KEY	Token creation key from afterpay

Create Token
This logon call can be used to create a token independently of a transaction.
Note: This API Call is optional and only needs to be implemented if the POS wishes to create tokens independently of doing transactions.

Request:
- Set Merchant to '65' for afterpay logon
- Set TxnType to 'X' to indicate Create Token.
- Set App to '02'
- Set PurchaseAnalysisData ONLY if the POS is responsible for token management: - DID - Device Id as returned in Activation
- KEY - Token creation key as returned in Activation
- Set Command Code to 'G' to indicate Logon

Response:

Field	Description
Success	'1' if successful
Response Code	'00' if it was approved
Response Text	response message associated with the response code
PurchaseAnalysisData
HRC	response code from AfterPay
TKN - Optional	Token From AfterPay
TEX - Optional	Token expiry time (in seconds) from AfterPay

Pre-Approval Enquiry(Balance)

This transaction can be used to perform a Pre-Approval Enquiry (Balance Check) using AfterPay.

Request:

Field	Description
Command Code	Set to 'M'
Merchant	Set to '65' to indicate a AfterPay transaction
TxnType	Set to 'B' to indicate a Balance
Pan	AfterPay barcode, or blank if provided in PAD
PanSource	Barcode capture method
App	Set to '02'
PurchaseAnalysisData
Pan - Optional	AfterPay barcode if Card Number is blank, otherwise don't send this
TKN - Optional	Current Valid Token
DID - Optional	Device Id from Activation
KEY - Optional	Key from Activation
OPR	Current POS operator id or name

Response:

Field	Description
Success	'1' if successful
Response Code	'00' if it was approved
Response Text	response message associated with the response code
PurchaseAnalysisData
HRC	response code from AfterPay
AMT	Pre-approved amount from AfterPay
MIN	Minimum allowable purchase amount
EXP	Expiry DateTime of pre-approved barcode Format: YYYYMMDDHHMMSS
TKN - Optional	Token from afterpay
TEX - Optional	Token expiry time (in seconds) from AfterPay

Order(Purchase)

This transaction can be used to perform an Order (Purchase) using AfterPay. Please Note: AfterPay does not support automatic reversals, and as such the POS must implement and initiate idempotent retires in the case that a response is not received for Order (Puchase) transactions; the Response Code to indicate this is 'X0'.

Request:

Field	Description
Merchant	Set to '65' to indicate a AfterPay transaction
TxnType	Set to 'P' to indicate a Purchase
AmtPurchase	Set to the amount to pay with AfterPay
Pan	AfterPay barcode, or blank if provided in PAD
PanSource	Barcode capture method
CurrencyCode	(Optional) ISO Currency code (e.g. AUD)
TxnRef	Unique transaction reference number
Command Code	Set to 'M'
App	Set to '02'
PurchaseAnalysisData
Pan - Optional	AfterPay barcode if Card Number is blank, otherwise don't send this
TKN - Optional	Current Valid Token
DID - Optional	Device Id from Activation
KEY - Optional	Key from Activation
UID	Globally unique request id used for idempotent retries
OPR	Current POS operator id or name

Response:

Field	Description
Success	'1' if successful
Response Code	'00' if it was approved
Response Text	response message associated with the response code
PurchaseAnalysisData
HRC	response code from AfterPay
REF	Order Id from AfterPay
AMT	Approved purchase amount from AfterPay
TKN - Optional	Token from afterpay
TEX - Optional	Token expiry time (in seconds) from AfterPay

Refund

This transaction can be used to perform a Refund using AfterPay. Please Note: AfterPay does not support automatic reversals, and as such the POS must implement and initiate idempotent retires in the case that a valid response is not received for Refund transactions; the Response Code to indicate this is 'X0'.

Request

Field	Description
Merchant	Set to '65' to indicate a AfterPay transaction
TxnType	Set to 'R' to indicate a Purchase
AmtPurchase	Set to the amount to refund with AfterPay
CurrencyCode	(Optional) ISO Currency code (e.g. AUD)
TxnRef	Unique transaction reference number
App	Set to '02'
CommandCode	Set to 'M'
PurchaseAnalysisData
REF	Order id of the order to refund against
TKN - Optional	Current Valid Token
DID - Optional	Device Id from Activation
KEY - Optional	Key from Activation
UID	Globally unique request id used for idempotent retries
OPR	Current POS operator id or name

Response:

Field	Description
Success	'1' if successful
Response Code	'00' if it was approved
Response Text	response message associated with the response code
PurchaseAnalysisData
HRC	response code from AfterPay
REF	Order Id from AfterPay
AMT	Approved purchase amount from AfterPay
TKN - Optional	Token from afterpay
TEX - Optional	Token expiry time (in seconds) from AfterPay

Invite

This transaction can be used to invite a customer to use AfterPay

Request:

Field	Description
Merchant	Set to '65' to indicate a AfterPay transaction
TxnType	Set to 'K' to indicate a Invite
AmtPurchase	Set to the amount to invite for
CurrencyCode	(Optional) ISO Currency code (e.g. AUD)
App	Set to '02'
CommandCode	Set to 'M'
PurchaseAnalysisData
PHN	The customer's phone number
TKN - Optional	Current Valid Token
DID - Optional	Device Id from Activation
KEY - Optional	Key from Activation
OPR	Current POS operator id or name

Response:

Field	Description
Success	'1' if successful
Response Code	'00' if was approved
Response Text	response message associated with the response code
PurchaseAnalysisData
HRC	response code from AfterPay
TKN - Optional	Token from afterpay
TEX - Optional	Token expiry time (in seconds) from AfterPay

Registry Settings

The TPP AfterPay extension can be configured by pushing values directly to the registry. The installer exe should be used unless specific configuration is required. The following table summarises the registry values that should be set for the TPP AfterPay extension.

Registry Key Or Value	Type	Description
..\CullenSoftwareDesign\EFTCLIENT\DLLS\AFTERPAY	Key	AfterPay Registry Key
ACTIVATION_KEY	String	Onetime activation secret generated by AfterPay
DEVICE_NAME	String	Device Name assigned by AfterPay
MERCHANT_ID	String	Merchant Number assigned by AfterPay

In addition to these settings, every lane that is using any TPP extension must also configure the following registry locations. These are shared by all TPP extensions.

Registry Key Or Value	Type	Description
..\PC-EFTPOS\LaneInfo	Key	Lane Information Registry Key
MerchantId	String	A unique 5-7 character label that is unique per Merchant/Brand (contact Linkly for this)
StoreId	String	A five-digit store identify of your choosing. It is recommended this be padded to 5 digits. Eg. 01234
LaneId	string	A thre digit lane number (pad to three digits) Eg."005"
StoreAddress	string	Optional store address information.

---

Alipay

This extension adds to the core EFTPOS payment API that is provided to the POS by the Linkly EFT Client and allows the POS to perform the proprietary Alipay transactions outlined in this section.
Use of this extension assumes an existing understanding and implementation of the Linkly Basket API.

The Alipay extension file (TPP2_Alipay.bcx) must be installed to the same folder as the EFT-Client executable (EftClnt.exe) on the POS (by default this is the "C:\PC_EFT" folder). The Alipay extension is also dependant on the TPP_MasterGUI.bcx for basket and certain standalone functionality.
In addition to the basic TPP2 lane configuration, the Alipay extension requires various identifiers provided by Alipay to be configured in the Registry. Please refer to Registry for further details.

Methods

Status Query

This transaction can be used to perform a Status Query for a specific Alipay Purchase Transaction.
Note: The result of the status query does not always fully reflect the status of the transaction. For example, partial refunds are not reflected in the returned Purchase Amount / AMT.

Request:

Field	Description
Command Code	Set to 'M' for a transaction request
App	Set to '02' to indicate an extension request
Merchant	Set to '66' to indicate an Alipay request
Txn Type	Set to 'B' to indicate a Status Query
PurchaseAnalysisData
RFN	Retrieval Reference of Purchase

Response:

Field	Description
Success	'1' if transaction was successful
Response Code	'00' if the transaction was approved
Response Text	Response message
AmtPurchase	(cond. success) Original transaction amount
PurchaseAnalysisData
HRC	Response code from Alipay
REF	Reference (Trade No) from Alipay
RFN	Retrieval Reference
STS	Transaction Status from Alipay

---

Purchase

This transaction can be used to perform a Purchase (QR code / Barcode) using Alipay.
Note: QR code only works on compatible terminals. Depending on registry settings and PAD fields a direct Barcode purchase can be done instead of a QR code purchase.
Note: Pressing the function key (on the pinpad) at the QR code display will cancel the QR code transaction and fall back to a manually entered barcode transaction.
Note: This transaction can be cancelled while the QR Code is displayed (using the Cancel button on the POS dialog), but only before the customer completes the purchase.

Request:

Field	Description
Command Code	Set to 'M' for a transaction request
App	Set to '02' to indicate an extension request
Merchant	Set to '66' to indicate an Alipay request
Txn Type	Set to 'P' to indicate a Purchase
AmtPurchase	Amount to pay with Alipay
Pan	(optional) Alipay barcode value
PanSource	(optional) Barcode capture method
Currency Code	(optional) ISO Currency Code (e.g. AUD)
Txn Ref Number	POS transaction reference number
PurchaseAnalysisData
TNM	(optional) Transaction Name (displayed to customer)
PMD	(optional) Set to BARCODE to force a direct barcode purchase
SKU	Basket Id

Response:

Field	Description
Success	'1' if transaction was successful
Response Code	'00' if the transaction was approved
Response Text	Response message
AmtPurchase	(cond. success) Approved purchase amount
Txn Ref Number	POS transaction reference number
PurchaseAnalysisData
HRC	Response code from Alipay
REF	Reference (Trade No) from Alipay
RFN	Retrieval Reference (used for Refund, Query, Cancel)

---

Refund

This transaction can be used to perform a full or partial Refund using Alipay.
Please Note: Alipay does not support the cancellation (or reversal) of refunds.

Request:

Field	Description
Command Code	Set to 'M' for a transaction request
App	Set to '02' to indicate an extension request
Merchant	Set to '66' to indicate an Alipay request
Txn Type	Set to 'R' to indicate a Refund
AmtPurchase	Amount to refund with Alipay
Currency Code	(optional) ISO Currency Code (e.g. AUD)
Txn Ref Number	POS transaction reference number
PurchaseAnalysisData
RFN	Retrieval Reference of Purchase

Response:

Field	Description
Success	'1' if transaction was successful
Response Code	'00' if the transaction was approved
Response Text	Response message
AmtPurchase	(cond. success) Approved refund amount
Txn Ref Number	POS transaction reference number
PurchaseAnalysisData
HRC	Response code from Alipay
REF	Reference (Trade No) from Alipay

---

Cancel

This transaction can be used to cancel a Purchase.

Request:

Field	Description
Command Code	Set to 'M' for a transaction request
App	Set to '02' to indicate an extension request
Merchant	Set to '66' to indicate an Alipay request
Txn Type	Set to 'I' to indicate a Cancel
PurchaseAnalysisData
RFN	Retrieval Reference of Purchase

Response:

Field	Description
Success	'1' if transaction was successful
Response Code	'00' if the transaction was approved
Response Text	Response message
PurchaseAnalysisData
HRC	Response code from Alipay
REF	Reference (Trade No) from Alipay

---

Basket Data

For reference, please see Basket API

Alipay uses the standard basket header fields.

Alipay uses the following extended basket header fields:
name

Alipay uses the following standard basket item fields:
id, qty, amt, name, link, desc

Alipay does not use any extended basket item fields.

---

Registry

The Alipay extension can be configured by pushing values directly to the registry.
The following table summarises the registry values that should be set for the TPP2 Alipay extension.

Name	Default	Description
## \CullenSoftwareDesign\EFTCLIENT\DLLS\Alipay
ALIPAY_PARTNER_ID		ID of Alipay partner (acquirer)
ALIPAY_Merchant_ID		Merchant Id as registered with Alipay partner
ALIPAY_Merchant_NAME		Merchant Name as registered with Alipay partner
ALIPAY_Merchant_INDUSTRY		Merchant Industry as registered with Alipay partner
ALIPAY_STORE_ID		Store ID as registered with Alipay partner
ALIPAY_STORE_NAME		Store Name as registered with Alipay partner
ALIPAY_TERMINAL_ID		(optional) Terminal ID as registered with Alipay partner
ALIPAY_SELLER_ID		(optional) Seller ID as registered with Alipay
ALIPAY_SELLER_EMAIL		(optional) Seller Email as registered with Alipay

In addition to these settings, every lane that is using any TPP2 extension must also configure the following registry locations. These are shared by all TPP2 extensions.

Registry Key Or Value	Type	Description
..\CullenSoftwareDesign\EFTCLIENT\LANEINFO
MerchantId	String	A unique 5-7 character label that is unique per Merchant/Brand (contact Linkly for this)
StoreId	String	A five-digit store identify of your choosing. It is recommended this be padded to 5 digits. Eg. 01234
LaneId	string	A thre digit lane number (pad to three digits) Eg."005"
StoreAddress	string	Optional store address information.

Note: ## refers to the "SOFTWARE" registry key. On pre-Win7 or 32-bit Windows this location is "HKEY_LOCAL_MACHINE\SOFTWARE". On Win7 64-bit and later it is usually mapped to the location "HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node". Please ensure values are stored at the appropriate location for your POS.

---

Blackhawk

This extension adds to the core EFTPOS payment API that is provided to the POS by the Linkly EFT Client and allows the POS to perform Blackhawk gift card transactions to the Blackhawk host via the Linkly Data Centre. This document is primarily intended for POS software developers who are integrating the Blackhawk features into the POS. It assumes readers are familiar with the standard Linkly client API which is covered by the Linkly EFTClient TCP Specification.

The Blackhawk extension file (TPP_BLACKHAWK.BCX) must be installed to the same folder as the EFT-Client executable (EftClnt.exe) on the POS (by default this is the "C:\PC_EFT" folder). The POS must also have the TPPS_GENERIC.BCX extension installed (or an alternative TPPS extension provided by Linkly). The Generic extension provides the TPP Control Panel that can be used for viewing and setting the lane configuration for the TPP extensions. In addition to the basic TPP lane configuration, the Blakhawk extension requires the AID values that are provided by Blackhawk to be configured via the TPP Control Panel. Refer to the Linkly TPP Setup Guide for further information about installation and setup of TPP extensions. Use the PCEFTPOS-Blackhawk-TPP-Installer. Depending on the choice for deployment, all TPP settings may also be pushed directly to the registry.

Activation

This transaction can be used to perform a card activation for a Blackhawk gift card. The POS may send the card number and UPC in the request if this information is known to the POS. If the card number is not sent by the POS the Blackhawk extension will prompt for the card to be swiped on the EFTPOS terminal prior to sending the request to the Blackhawk host for processing.

Request:

Field	Description
Command Code	Set to 'M' to indicate transaction request
Merchant	Set to '53' to indicate a Blackhawk transaction
TxnType	Set to 'D' to indicate a Purchase
AmtPurchase	Set to the transaction amount
Pan	Card Number if provided by the POS otherwise blank
PanSource	Card capture method if captured by the POS
Track2	Card Track 2 Data if captured by the POS, otherwise blank
TxnRef	Unique transaction reference number
App	Set to '02'
PurchaseAnalysisData
UPC	Card UPC. Required if card information is being sent by the POS.
PAN	Card Number (Optional)
CNB	Card Bin (Optional)

Response:

Field	Description
Success	'1' if successful
Response Code	'00' if it was approved
Response Text	response message associated with the response code
PurchaseAnalysisData
BAL	Card Balance (Optional)
HRC	Blackhawk Host Response Code (Optional)

Void

This transaction can be used to void, or cancelation of an activation for a Blackhawk gift card. The POS may send the card number and UPC in the request if this information is known to the POS. If the card number is not sent by the POS the Blackhawk extension will prompt for the card to be swiped on the EFTPOS terminal prior to sending the void request to the Blackhawk host for processing.

Request:

Field	Description
Command Code	Set to 'M' to indicate transaction request
Merchant	Set to '53' to indicate a Blackhawk transaction
TxnType	Set to 'I' to indicate a Purchase
AmtPurchase	Set to the transaction amount
Pan	Card Number if provided by the POS otherwise blank
PanSource	Card capture method if captured by the POS
Track2	Card Track 2 Data if captured by the POS, otherwise blank
TxnRef	Unique transaction reference number
App	Set to '02'
PurchaseAnalysisData
UPC	Card UPC. Required if card information is being sent by the POS.

Response:

Field	Description
Success	'1' if successful
Response Code	'00' if it was approved
Response Text	response message associated with the response code
PurchaseAnalysisData
HRC	Blackhawk Host Response Code (Optional)

Registry

The TPP Blackhawk extension can also be configured by pushing values directly to the registry. The following table summarises the registry values that should be set for the TPP Blackhawk extension.

Registry Key Or Value	Type	Description
..\CullenSoftwareDesign\PCEFFTPOS_BRIDGE\TPP-BLACKHAWK	Key	Blackhawk Registry Key
AIIC	String	Blackhawk AID Value provided by blackhawk

In addition to these settings, every lane that is using any TPP extension must also configure the following registry locations. These are shared by all TPP extensions.

Registry Key Or Value	Type	Description
..\PC-EFTPOS\LaneInfo	Key	Lane Information Registry Key
MerchantId	String	A unique 5-7 character label that is unique per Merchant/Brand (contact Linkly for this)
StoreId	String	A five-digit store identify of your choosing. It is recommended this be padded to 5 digits. Eg. 01234
LaneId	string	A thre digit lane number (pad to three digits) Eg."005"
StoreAddress	string	Optional store address information.

---

EPay Prepaid

Installation

This extension adds to the core EFTPOS payment API that is provided to the POS by the Linkly EFT Client and allows the POS to perform the proprietary epay transactions outlined in the following sections This document assumes an existing understanding of the Linkly solution and core API's as covered by the ActiveX interface documentation.

The epay extension file (TPP_EPAY.bcx) must be installed to the same folder as the EFT-Client executable (EftClnt.exe) on the POS (by default this is the "C:\PC_EFT" folder). Depending on the choice for deployment, all TPP settings may also be pushed directly to the registry. Aditionally the TPP installer can be used for automatic installation.

Methods
The POS can use the following methods to perform various epay transactions for the sale of e vouchers, e top-up, and POSA products as well as the sale and redemption of gift cards. The POS must pass the epay Product Id to the TPP. In the case of certain card based products the UPC (aka EAN) can be given instead of the Product Id.

Card Status

This transaction can be used to perform a status inquiry on an epay card.

Request:

Field	Description
Command Code	Set to 'M'
Merchant	Set to '63' to indicate a Epay transaction
TxnType	Set to 'B' to indicate a Status
Pan	Card number if provided by the POS otherwise blank
PanSource	Card capture method if captured by the POS
Track2	Card track 2 data if captured by the POS otherwise blank
TxnRef	Unique transaction reference number
App	Set to '02'
PurchaseAnalysisData
PPD	Set to 'EPY' for epay processing
PID	Epay Product Id
UPC	Card UPC (aka EAN) (Optional)
PHN	Phone Number (optional)

Response:

Field	Description
Success	1 if successful
Response Code	'00' if it was approved
Response Text	response message associated with the response code
PurchaseAnalysisData
HRC	Response code from epay
REF	Epay Transaction reference
BAL	Card Balance (optional)
RSV	Reserved Value on the card (optional)
STS	Card Status (optional)

Card Load/Sale

This transaction can be used to load value on to, or sell, an epay card.

Request:

Field	Description
Command Code	Set to 'M'
Merchant	Set to '63' to indicate a Epay transaction
TxnType	Set to 'D' to indicate a Load/Sale
AmtPurchase	Set to the transaction amount
Pan	Card number if provided by the POS otherwise blank
PanSource	Card capture method if captured by the POS
Track2	Card track 2 data if captured by the POS otherwise blank
TxnRef	Unique transaction reference number
App	Set to '02'
PurchaseAnalysisData
PPD	Set to 'EPY' for epay processing
PID	Epay Product Id
UPC	Card UPC (aka EAN) (Optional)

Response:

Field	Description
Success	1 if successful
Response Code	'00' if it was approved
Response Text	response message associated with the response code
PurchaseAnalysisData
HRC	Response code from epay
REF	Epay Transaction reference
BAL	Card Balance (optional)
EXP	Expiry Date As DDMMYY (optional)
RSV	Reserved Value on card (optional)

Refund to Card

This transaction can be used to load value to an epay gift card in the case of a refund.

Request:

Field	Description
Command Code	Set to 'M'
Merchant	Set to '63' to indicate a Epay transaction
TxnType	Set to 'R' to indicate a Refund
AmtPurchase	Set to the transaction amount
Pan	Card number if provided by the POS otherwise blank
PanSource	Card capture method if captured by the POS
Track2	Card track 2 data if captured by the POS otherwise blank
TxnRef	Unique transaction reference number
App	Set to '02'
PurchaseAnalysisData
PPD	Set to 'EPY' for epay processing
PID	Epay Product Id
UPC	Card UPC (aka EAN) (Optional)

Response:

Field	Description
Success	1 if successful
Response Code	'00' if it was approved
Response Text	response message associated with the response code
PurchaseAnalysisData
HRC	Response code from epay
REF	Epay Transaction reference
BAL	Card Balance (optional)
RSV	Reserved Value on card (optional)

Redeem Card

This transaction can be used to perform a redemption / purchase with an epay gift card.

Request:

Field	Description
Command Code	Set to 'M'
Merchant	Set to '63' to indicate a Epay gift card transaction
TxnType	Set to 'P' to indicate a Redeem / Purchase
AmtPurchase	Set to the transaction amount
Pan	Card number if provided by the POS otherwise blank
PanSource	Card capture method if captured by the POS
Track2	Card track 2 data if captured by the POS otherwise blank
TxnRef	Unique transaction reference number
App	Set to '02'
PurchaseAnalysisData
PPD	Set to 'EPY' for epay processing
PID	Epay Product Id
UPC	Card UPC (aka EAN) (Optional)

Response:

Field	Description
Success	1 if successful
Response Code	'00' if it was approved
Response Text	response message associated with the response code
PurchaseAnalysisData
HRC	Response code from epay
REF	Epay Transaction reference
BAL	Card Balance (optional)
RSV	Reserved Value on card (optional)

Voucher Sale

This transaction can be used for the sale of an e-voucher

Request:

Field	Description
Command Code	Set to 'M'
Merchant	Set to '63' to indicate a Epay gift card transaction
TxnType	Set to 'V' to indicate a Voucher Sale
AmtPurchase	Set to the transaction amount
TxnRef	Unique transaction reference number
App	Set to '02'
PurchaseAnalysisData
PPD	Set to 'EPY' for epay processing
PID	Epay Product Id
PHN	Phone Number

Response:

Field	Description
Success	1 if successful
Response Code	'00' if it was approved
Response Text	response message associated with the response code
PurchaseAnalysisData
HRC	Response code from epay
REF	Epay Transaction reference
EXP	Expiry Date as DDMMYY ( Optional)
SRN	Product Serial Number (optional)
SEC	Product Security Code (optional)
VFD	Valid from the date as DDMMYY (optional)

Reprint Voucher

This transaction can be used to request the reprint of a voucher using either the epay transaction reference (REF), or the Txn Ref Number (RRN) of the original transaction.

Note: RRN should only be used if the original transaction was done recently and on the same lane, otherwise REF is the preferred option.

Request:

Field	Description
Command Code	Set to 'M'
Merchant	Set to '63' to indicate a Epay gift card transaction
TxnType	Set to 'X' to indicate a Reprint
TxnRef	Unique transaction reference number
App	Set to '02'
PurchaseAnalysisData
PPD	Set to 'EPY' for epay processing
REF	Epay transaction reference (optional)
RRN	Original transaction Txn Ref Number (optional)

Response:

Field	Description
Success	1 if successful
Response Code	'00' if it was approved
Response Text	response message associated with the response code
PurchaseAnalysisData
HRC	Response code from epay
REF	Epay Transaction reference

Void

This transaction can be used to void a previous epay transaction using either the epay transaction reference (REF), or the Txn Ref Number (RRN) of the original transaction. Note: RRN should only be used if the original transaction was done recently and on the same lane, otherwise REF is the preferred option. For card based products the card number (Pan) must be swiped or scanned again, it cannot be manually entered. For non-card based products (i.e. those that do not require a Pan) the card number source '0' (zero) can be used to indicate that no Pan is required.

Request:

Field	Description
Command Code	Set to 'M'
Merchant	Set to '63' to indicate a Epay gift card transaction
TxnType	Set to 'I' to indicate a Void
AmtPurchase	Set to the transaction amount
Pan	Card number if provided by the POS otherwise blank
PanSource	Card capture method if captured by the POS
Track2	Card track 2 data if captured by the POS otherwise blank
TxnRef	Unique transaction reference number
App	Set to '02'
PurchaseAnalysisData
PPD	Set to 'EPY' for epay processing
REF	Epay transaction reference (optional)
RRN	Original transaction Txn Ref Number (optional)

Response:

Field	Description
Success	1 if successful
Response Code	'00' if it was approved
Response Text	response message associated with the response code
PurchaseAnalysisData
HRC	Response code from epay
REF	Epay Transaction reference
BAL	Card Balance (optional)
RSV	Reserved value on card (optional)

Registry

The TPP Epay extension can also be configured by pushing values directly to the registry. The following table summarises the registry values that should be set for the TPP Epay extension.

Registry Key Or Value	Type	Description
..\CullenSoftwareDesign\PCEFFTPOS_BRIDGE\TPP-EPAY	Key	Epay Registry Key
TID	String	Epay Terminal Id
SHOPID	string	A 7-digit store identifier. It is recommended this be padded to 7 digits. Eg. 0001234
RETAILERID	String	Epay retailer id (optional)
TILLID	String	Epay till id (optional)
RECEIPT_WIDTH	dword	Receipt Width (optional) (default 32, min 24)

In addition to these settings, every lane that is using any TPP extension must also configure the following registry locations. These are shared by all TPP extensions.

Registry Key Or Value	Type	Description
..\PC-EFTPOS\LaneInfo	Key	Lane Information Registry Key
MerchantId	String	A unique 5-7 character label that is unique per Merchant/Brand (contact Linkly for this)
StoreId	String	A five-digit store identify of your choosing. It is recommended this be padded to 5 digits. Eg. 01234
LaneId	string	A thre digit lane number (pad to three digits) Eg."005"
StoreAddress	string	Optional store address information.

---

EpayWallet

This extension adds to the core EFTPOS payment API that is provided to the POS by the Linkly EFT Client and allows the POS to perform Third-party payment options via the Epay acquirer outlined in this section.
This document assumes an existing understanding of the Linkly solution and core API's.

The EpayWallet extension file (TPP2_EpayWallet.bcx) must be installed to the same folder as the EFT-Client executable (EftClnt.exe) on the POS (by default this is the "C:\PC_EFT" folder). The EpayWallet extension is also dependant on the TPP_MasterGUI.bcx for standalone functionality.
In addition to the basic TPP2 lane configuration, the EpayWallet extension requires various identifiers provided by EpayWallet to be configured in the Registry. Please refer to the Registry section for further details.

Purchase

This transaction can be used to purchase using a EpayWallet payment. Depending on the processing host please see the purchase section of:

• Alipay
• WeChat

In addition to the required fields listed in the processing host spec the following are required for processing via Epay:

Field	Description
PurchaseAnalysisData
OPR	Operator ID who performed the sale

In addition to the standard response fields covered by the processing host, Epay returns the following:

Field	Description
PurchaseAnalysisData
HRC	EpayWallet response Code
REF	EpayWallet Purchase Reference Number
RFN	EpayWallet Refund Code
ORD	EpayWallet OrderId
HRF	Host processing reference number (Alipay or WeChat)

Refund

This transaction can be used to refund using a EpayWallet payment. Depending on the processing host please see the refund section of:

• Alipay
• WeChat

In addition to the required fields listed in the processing host spec the following are required for processing via Epay:

Field	Description
PurchaseAnalysisData
OPR	Current POS operator id or name

In addition to the standard response fields covered by the processing host, Epay returns the following:

Field	Description
PurchaseAnalysisData
HRC	EpayWallet response Code
REF	EpayWallet Purchase Reference Number
RFN	EpayWallet Refund Code
ORD	EpayWallet OrderId
HRF	Host processing reference number (Alipay or WeChat)

Registry

The EpayWallet extension can be configured by pushing values directly to the registry.
The following table summarises the registry values that should be set for the TPP2 EpayWallet extension.

Registry Key Or Value	Type	Description
## \CullenSoftwareDesign\EFTCLIENT\DLLS\TppEpayWallet	Key	EpayWallet Registry Key
USERNAME	Epay Username
PASSWORD	Epay Password
TERMINALID	Epay TerminalId

In addition to these settings, every lane that is using any TPP2 extension must also configure the following registry locations. These are shared by all TPP2 extensions.

Registry Key Or Value	Type	Description
..\CullenSoftwareDesign\EFTCLIENT\LANEINFO	Key	Lane Information Registry Key
MerchantId	String	A unique 5-7 character label that is unique per Merchant/Brand (contact Linkly for this)
StoreId	String	A five-digit store identify of your choosing. It is recommended this be padded to 5 digits. Eg. 01234
LaneId	string	A three digit lane number (pad to three digits) Eg."005"
StoreAddress	string	Optional store address information.

Note: ## refers to the "SOFTWARE" registry key. On pre-Win7 or 32-bit Windows this location is "HKEY_LOCAL_MACHINE\SOFTWARE". On Win7 64-bit and later it is usually mapped to the location "HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node". Please ensure values are stored at the appropriate location for your POS.

---

FDI-GiftCard

This extension adds to the core EFTPOS payment API that is provided to the POS by the Linkly EFT Client and allows the POS to perform the proprietary FDI GiftCard transactions outlined in this section.
This document assumes an existing understanding of the Linkly solution and core API's.

The FDI-GiftCard extension file (TPP2_FirstDataGiftCard.bcx) must be installed to the same folder as the EFT-Client executable (EftClnt.exe) on the POS (by default this is the "C:\PC_EFT" folder). The FDI-GiftCard extension is also dependant on the TPP_MasterGUI.bcx for standalone functionality.
In addition to the basic TPP2 lane configuration, the FDI-GiftCard extension requires various identifiers provided by FDI-GiftCard to be configured in the Registry. Please refer to the Registry section for further details.

Balance

This transaction can be used to perform a Balance Check on a card.

Field	Description
Command Code	Set to 'M' to start transaction
Merchant	Set to '68' to indicate a FDI-GiftCard transaction
TxnType	Set to 'B' to indicate Balance
TxnRef	Unique Transaction reference number
App	Set to '02' to indicate an extension request
PurchaseAnalysisData
CPC	(Optional) Customer Post Code
OPR	Operator ID who performed the sale

Field	Description
Success	'1' if successful
Response Code	'00' if it was approved
Response Text	response message associated with the response code
PurchaseAnalysisData
HRC	FDI-GiftCard response Code
BAL	Card Balance from FDI
PRV	Previous Card Balance from FDI
EXP	Card Expiry Date (DDMMYYYY) from FDI

Activation

This transaction can be used to activate a card using First Data.

Field	Description
Command Code	Set to 'M' to start transaction
Merchant	Set to '68' to indicate a FDI-GiftCard transaction
TxnType	Set to 'D' to indicate Activation
AmtPurchase	Set to the amount to activate the card with
Pan	FDI-GiftCard card number
PanSource	Card capture method
Track2	Card track2 data (only provide if pan is blank)
CurrencyCode	ISO Currency Code
TxnRef	Unique Transaction reference number
App	Set to '02' to indicate an extension request
PurchaseAnalysisData
OPR	Operator ID who performed the sale
CPC	(Optional) Customer Post Code
PMC	(Optional) Promotion Code
GRP	(Optional Transaction Group Id
MFD	(Optional) Mark transaction as Merchant funded

Field	Description
Success	'1' if successful
Response Code	'00' if it was approved
Response Text	response message associated with the response code
(On Success) AmtPurchase Approved Activation Amount
(On Success) AuthCode	Auth Code from FDI
PurchaseAnalysisData
HRC	FDI-GiftCard response Code
BAL	Card Balance from FDI
PRV	Previous Card Balance from FDI
EXP	Card Expiry Date (DDMMYYYY) from FDI
REF	Reference from First Data
RFN	Retrieval Reference values (used for Void)

Reload

This transaction ca be used to Reload a FDI-GiftCard

Field	Description
Command Code	Set to 'M' to start transaction
Merchant	Set to '68' to indicate a FDI-GiftCard transaction
TxnType	Set to 'T' to indicate Reload
AmtPurchase	Set to the amount to reload the card with
Pan	FDI-GiftCard card number
PanSource	Card capture method
Track2	Card track2 data (only provide if pan is blank)
CurrencyCode	ISO Currency Code
TxnRef	Unique Transaction reference number
App	Set to '02' to indicate an extension request
PurchaseAnalysisData
OPR	Operator ID who performed the sale
CPC	(Optional) Customer Post Code
GRP	(Optional Transaction Group Id

Field	Description
Success	'1' if successful
Response Code	'00' if it was approved
Response Text	response message associated with the response code
(On Success) AuthCode	Auth Code from FDI
PurchaseAnalysisData
HRC	FDI-GiftCard response Code
BAL	Card Balance from FDI
PRV	Previous Card Balance from FDI
EXP	Card Expiry Date (DDMMYYYY) from FDI
REF	Reference from First Data
RFN	Retrieval Reference values (used for Void)

Redeem

This transaction can be used to purchase using a FDI-GiftCard

Field	Description
Command Code	Set to 'M' to start transaction
Merchant	Set to '68' to indicate a FDI-GiftCard transaction
TxnType	Set to 'P' to indicate Purchase
AmtPurchase	Set the sale amount
Pan	FDI-GiftCard card number
PanSource	Card capture method
Track2	Card track2 data (only provide if pan is blank)
CurrencyCode	ISO Currency Code
TxnRef	Unique Transaction reference number
App	Set to '02' to indicate an extension request
PurchaseAnalysisData
OPR	Operator ID who performed the sale
CPC	(Optional) Customer Post Code

Field	Description
Success	'1' if successful
Response Code	'00' if it was approved
Response Text	response message associated with the response code
(On Success) AuthCode	Auth Code from FDI
PurchaseAnalysisData
HRC	FDI-GiftCard response Code
BAL	Card Balance from FDI
PRV	Previous Card Balance from FDI
EXP	Card Expiry Date (DDMMYYYY) from FDI
REF	Reference from First Data
RFN	Retrieval Reference values (used for Void)
RCP	(Optional) ReceiptCode

Void

Field	Description
Command Code	Set to 'M' to start transaction
Merchant	Set to '68' to indicate a FDI-GiftCard transaction
TxnType	Set to 'I' to indicate Void
TxnRef	Unique Transaction reference number
App	Set to '02' to indicate an extension request
PurchaseAnalysisData
OPR	Operator ID who performed the sale
CPC	(Optional) Customer Post Code
RFN	Retrieval Reference of the sale to Void

Field	Description
Success	'1' if successful
Response Code	'00' if it was approved
Response Text	response message associated with the response code
(On Success) AuthCode	Auth Code from FDI
PurchaseAnalysisData
HRC	FDI-GiftCard response Code
BAL	Card Balance from FDI
PRV	Previous Card Balance from FDI
EXP	Card Expiry Date (DDMMYYYY) from FDI
REF	Reference from First Data

Registry

The FDI-GiftCard extension can be configured by pushing values directly to the registry.
The following table summarises the registry values that should be set for the TPP2 FDI-GiftCard extension.

Registry Key Or Value	Type	Description
## \CullenSoftwareDesign\EFTCLIENT\DLLS\FDGiftCard	Key	FDI-GiftCard Registry Key
MERCHANT_ID	String	FDI Defined Merchant ID
TERMINAL_ID	String	FDI Defined Terminal ID
ALT_MERCHANT_ID	String	FDI Defined Alternative Merchant ID
(Optional) COUNTRY_CODE	String	FDI CountryCode
(Optional) MERCHANT_FUND_ID	String	FDI Merchant-Funded ID
(Optional) ALT_MERCHANT_FUND_ID	String	Alternative FDI Merchant-Funded ID
(Optional) RECEIPT_CODE	String	FDI Receipt Code
(Optional) ALT_TERMINAL_ID	String	Alternative Terminal ID

In addition to these settings, every lane that is using any TPP2 extension must also configure the following registry locations. These are shared by all TPP2 extensions.

Registry Key Or Value	Type	Description
..\CullenSoftwareDesign\EFTCLIENT\LANEINFO	Key	Lane Information Registry Key
MerchantId	String	A unique 5-7 character label that is unique per Merchant/Brand (contact Linkly for this)
StoreId	String	A five-digit store identify of your choosing. It is recommended this be padded to 5 digits. Eg. 01234
LaneId	string	A three digit lane number (pad to three digits) Eg."005"
StoreAddress	string	Optional store address information.

Note: ## refers to the "SOFTWARE" registry key. On pre-Win7 or 32-bit Windows this location is "HKEY_LOCAL_MACHINE\SOFTWARE". On Win7 64-bit and later it is usually mapped to the location "HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node". Please ensure values are stored at the appropriate location for your POS.

---

GiveX

This extension adds to the core EFTPOS payment API that is provided to the POS by the Linkly EFT Client and allows the POS to perform GiveX gift card transactions to the GiveX host via the PC EFTPOS Data Centre. This document is primarily intended for POS software developers who are integrating the GiveX features into the POS. It assumes readers are familiar with the standard Linkly client API which is covered by the "PC-EFTPOS EFTClient TCP Specification".

The GiveX extension file (TPP_GIVEX.BCX) must be installed to the same folder as the EFT-Client executable (EftClnt.exe) on the POS (by default this is the "C:\PC_EFT" folder). The POS must also have the TPPS_GENERIC.BCX extension installed (or an alternative TPPS extension provided by Linkly). The Generic extension provides the TPP Control Panel that can be used for viewing and setting the lane configuration for the TPP extensions. In addition to the basic TPP lane configuration, the GiveX extension requires the Username and Password values that are provided by GiveX to be configured via the TPP Control Panel. Depending on the choice for deployment, all TPP settings may also be pushed directly to the registry.

Redeem

This transaction can be used to perform a redemption from a gift card.
The POS may send the card number in the request if this information is known to the POS. If the card number is not sent by the POS the GiveX extension will prompt for the card to be swiped on the EFTPOS terminal prior to sending the request to the GiveX host for processing.

Request:

Field	Description
Command Code	Set to 'M' to indicate transaction request
Merchant	Set to '52' to indicate a GiveX transaction
TxnType	Set to 'P' to indicate a Redeem/Purchase
AmtPurchase	Set to the transaction amount
Pan	Card Number if provided by the POS otherwise blank
PanSource	Card capture method if captured by the POS
Track2	Card Track 2 Data if captured by the POS, otherwise blank
TxnRef	Unique transaction reference number
App	Set to '02'
PurchaseAnalysisData
Pan	Alternative location for Card Pan (allows Pan length > 20)
PIN	Card PIN can be sent by the POS here (optional)

Response:

Field	Description
Success	'1' if successful
Response Code	'00' if it was approved
Response Text	response message associated with the response code
PurchaseAnalysisData
BAL	Card Balance (optional)
EXP	Card Expiry Date (optional)
Pan	Card Pan (allows Pan length > 20)
HRC	GiveX Host response Code (optional)

Balance

This transaction can be used to perform a balance enquiry on a gift card. The POS may send the card number in the request if this information is known to the POS. If the card number is not sent by the POS the GiveX extension will prompt for the card to be swiped on the EFTPOS terminal prior to sending the request to the GiveX host for processing.

Request:

Field	Description
Command Code	Set to 'M' to indicate transaction request
Merchant	Set to '52' to indicate a GiveX transaction
TxnType	Set to 'B' to indicate a Balance Enquiry
Pan	Card Number if provided by the POS otherwise blank
PanSource	Card capture method if captured by the POS
Track2	Card Track 2 Data if captured by the POS, otherwise blank
TxnRef	Unique transaction reference number
App	Set to '02'
PurchaseAnalysisData
Pan	Alternative location for Card Pan (allows Pan length > 20)

Response:

Field	Description
Success	'1' if successful
Response Code	'00' if it was approved
Response Text	response message associated with the response code
PurchaseAnalysisData
BAL	Card Balance (optional)
EXP	Card Expiry Date (optional)
Pan	Card Pan (allows Pan length > 20)
HRC	GiveX Host response Code (optional)

Load

This transaction can be used to load value onto a gift card.
The POS may send the card number in the request if this information is known to the POS. If the card number is not sent by the POS the GiveX extension will prompt for the card to be swiped on the EFTPOS terminal prior to sending the request to the GiveX host for processing.

Request:

Field	Description
Command Code	Set to 'M' to indicate transaction request
Merchant	Set to '52' to indicate a GiveX transaction
TxnType	Set to 'D' to indicate a Load Transaction
AmtPurchase	Set to the transaction amount
Pan	Card Number if provided by the POS otherwise blank
PanSource	Card capture method if captured by the POS
Track2	Card Track 2 Data if captured by the POS, otherwise blank
TxnRef	Unique transaction reference number
App	Set to '02'
PurchaseAnalysisData
Pan	Alternative location for Card Pan (allows Pan length > 20)

Response:

Field	Description
Success	'1' if successful
Response Code	'00' if it was approved
Response Text	response message associated with the response code
PurchaseAnalysisData
BAL	Card Balance (optional)
EXP	Card Expiry Date (optional)
Pan	Card Pan (allows Pan length > 20)
HRC	GiveX Host response Code (optional)

Cancel

This transaction can be used to cancel (or void) a gift card transaction.
The POS may send the card number in the request if this information is known to the POS. If the card number is not sent by the POS the GiveX extension will prompt for the card to be swiped on the EFTPOS terminal prior to sending the request to the GiveX host for processing.

Request:

Field	Description
Command Code	Set to 'M' to indicate transaction request
Merchant	Set to '52' to indicate a GiveX transaction
TxnType	Set to 'I' to indicate a Cancel/Void Transaction
AmtPurchase	Set to the transaction amount
Pan	Card Number if provided by the POS otherwise blank
PanSource	Card capture method if captured by the POS
Track2	Card Track 2 Data if captured by the POS, otherwise blank
TxnRef	Unique transaction reference number
App	Set to '02'
PurchaseAnalysisData
Pan	Alternative location for Card Pan (allows Pan length > 20)

Response:

Field	Description
Success	'1' if successful
Response Code	'00' if it was approved
Response Text	response message associated with the response code
PurchaseAnalysisData
BAL	Card Balance (optional)
EXP	Card Expiry Date (optional)
Pan	Card Pan (allows Pan length > 20)
HRC	GiveX Host response Code (optional)

Refund

This transaction can be used to perform a gift card refund.
The POS may send the card number in the request if this information is known to the POS. If the card number is not sent by the POS the GiveX extension will prompt for the card to be swiped on the EFTPOS terminal prior to sending the request to the GiveX host for processing.

Request:

Field	Description
Command Code	Set to 'M' to indicate transaction request
Merchant	Set to '52' to indicate a GiveX transaction
TxnType	Set to 'R' to indicate a Refund Transaction
AmtPurchase	Set to the transaction amount
Pan	Card Number if provided by the POS otherwise blank
PanSource	Card capture method if captured by the POS
Track2	Card Track 2 Data if captured by the POS, otherwise blank
TxnRef	Unique transaction reference number
App	Set to '02'
PurchaseAnalysisData
Pan	Alternative location for Card Pan (allows Pan length > 20)

Response:

Field	Description
Success	'1' if successful
Response Code	'00' if it was approved
Response Text	response message associated with the response code
PurchaseAnalysisData
BAL	Card Balance (optional)
EXP	Card Expiry Date (optional)
Pan	Card Pan (allows Pan length > 20)
HRC	GiveX Host response Code (optional)

Top-Up

This transaction can be used to perform a gift card top-up.
The POS may send the card number in the request if this information is known to the POS. If the card number is not sent by the POS the GiveX extension will prompt for the card to be swiped on the EFTPOS terminal prior to sending the request to the GiveX host for processing.

Request:

Field	Description
Command Code	Set to 'M' to indicate transaction request
Merchant	Set to '52' to indicate a GiveX transaction
TxnType	Set to 'T' to indicate a Top-Up Transaction
AmtPurchase	Set to the transaction amount
Pan	Card Number if provided by the POS otherwise blank
PanSource	Card capture method if captured by the POS
Track2	Card Track 2 Data if captured by the POS, otherwise blank
TxnRef	Unique transaction reference number
App	Set to '02'
PurchaseAnalysisData
Pan	Alternative location for Card Pan (allows Pan length > 20)

Response:

Field	Description
Success	'1' if successful
Response Code	'00' if it was approved
Response Text	response message associated with the response code
PurchaseAnalysisData
BAL	Card Balance (optional)
EXP	Card Expiry Date (optional)
Pan	Card Pan (allows Pan length > 20)
HRC	GiveX Host response Code (optional)

Registry

The TPP GiveX extension can also be configured by pushing values directly to the registry.
The following table summarises the registry values that should be set for the TPP GiveX extension.

Registry Key Or Value	Type	Description
..\CullenSoftwareDesign\PCEFFTPOS_BRIDGE\TPP-GIVEX	Key	GiveX Registry Key
USERNAME	String	GiveX Username value provided by GiveX
PASSWORD	String	GiveX Password value provided by GiveX

In addition to these settings, every lane that is using any TPP extension must also configure the following registry locations. These are shared by all TPP extensions.

Registry Key Or Value	Type	Description
..\PC-EFTPOS\LaneInfo	Key	Lane Information Registry Key
MerchantId	String	A unique 5-7 character label that is unique per Merchant/Brand (contact Linkly for this)
StoreId	String	A five-digit store identify of your choosing. It is recommended this be padded to 5 digits. Eg. 01234
LaneId	string	A thre digit lane number (pad to three digits) Eg."005"
StoreAddress	string	Optional store address information.

---

Humm

This extension adds to the core EFTPOS payment API that is provided to the POS by the Linkly EFT Client and allows the POS to perform the proprietary Humm transactions outlined in this section.
This document assumes an existing understanding of the Linkly solution and core API's as covered by the "PC-EFTPOS EFTClient TCP Specification" and "PC-EFTPOS ActiveX Control for EFTClient" documents.

The Humm extension file (TPP2_Humm.bcx) must be installed to the same folder as the EFT-Client executable (EftClnt.exe) on the POS (by default this is the "C:\PC_EFT" folder). The Humm extension is also dependant on the TPP_MasterGUI.bcx for standalone functionality.
In addition to the basic TPP2 lane configuration, the Humm extension requires various identifiers provided by Humm to be configured in the Registry. Please refer to the Registry section for further details.

Activation of TPP2_Humm is done in the background as long as the proper registry keys are set when installing the TPP Failure to properly activate the extension will result in 'Config required'/'Activation required' errors. See Registry section for more details.

Methods

Purchase

This method can be used to initiate an Humm transaction. The POS must pass in the total purchase amount for the sale in the 'AMT' Tag The POS will receive an Humm purchase number on the conclusion of the sale.

Request:

Field	Description
Command Code	Set to 'M' to start transaction
Merchant	Set to '67' to indicate a Humm transaction
TxnType	Set to 'P' to indicate a Purchase
AmtPurchase	Set to the amount to pay with Humm
TxnRef	Unique Transaction reference number
App	Set to '02' to indicate an extension request
Pan	Humm barcode value
PanSource	Barcode capture method
PurchaseAnalysisData
OPR	(optional) Operator ID who performed the sale
AMT	Total Purchase Amount (in cents)

Response:

Field	Description
Success	'1' if successful
Response Code	'00' if it was approved
Response Text	response message associated with the response code
PurchaseAnalysisData
HRC	Humm response Code
REF	Humm Purchase Number

Refund

This transaction can be used to perform a Refund using Humm.
The POS must pass in the Humm Purchase Number in the 'REF' Tag

Request:

Field	Description
Command Code	Set to 'M' to start transaction
Merchant	Set to '67' to indicate a Humm transaction
TxnType	Set to 'R' to indicate a Refund
AmtPurchase	Set to the amount to refund with Humm
TxnRef	Unique Transaction reference number
App	Set to '02' to indicate an extension request
PurchaseAnalysisData
REF	Reference (Purchase Id) of the purchase to refund
OPR	(Optional) Operator ID who performed the refund

Response:

Field	Description
Success	'1' if successful
Response Code	'00' if it was approved
Response Text	response message associated with the response code
PurchaseAnalysisData
HRC	Humm response Code

Invite

This Method can be used to perform an Humm Invite The POS must pass in the customer phone number in the 'PHN' Tag

Request:

Field	Description
Command Code	Set to 'M' to start transaction
Merchant	Set to '67' to indicate a Humm transaction
TxnType	Set to 'K' to indicate an Invite
AmtPurchase	Set to the amount to invite for with Humm
TxnRef	Unique Transaction reference number
App	Set to '02' to indicate an extension request
PurchaseAnalysisData
PHN	The customer's phone number
OPR	(Optional) Operator ID who performed the invite

Response:

Field	Description
Success	'1' if successful
Response Code	'00' if it was approved
Response Text	response message associated with the response code
PurchaseAnalysisData
HRC	Humm response Code

Registry

The Humm extension can be configured by pushing values directly to the registry.
The following table summarises the registry values that should be set for the TPP2 Humm extension.

Registry Key Or Value	Type	Description
## \CullenSoftwareDesign\EFTCLIENT\DLLS\Humm	Key	Humm Registry Key
ACTIVATION_KEY	String	Merchant POS Device Token, used for background activation
Merchant_ID	String	Humm defined MerchantId
NZ_MODE	String	Defines if txns go to New Zealand endpoint(1) or Australian endpoint(0) (Default: 0)

In addition to these settings, every lane that is using any TPP2 extension must also configure the following registry locations. These are shared by all TPP2 extensions.

Registry Key Or Value	Type	Description
..\CullenSoftwareDesign\EFTCLIENT\LANEINFO	Key	Lane Information Registry Key
MerchantId	String	A unique 5-7 character label that is unique per Merchant/Brand (contact Linkly for this)
StoreId	String	A five-digit store identify of your choosing. It is recommended this be padded to 5 digits. Eg. 01234
LaneId	string	A three digit lane number (pad to three digits) Eg."005"
StoreAddress	string	Optional store address information.

Note: ## refers to the "SOFTWARE" registry key. On pre-Win7 or 32-bit Windows this location is "HKEY_LOCAL_MACHINE\SOFTWARE". On Win7 64-bit and later it is usually mapped to the location "HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node". Please ensure values are stored at the appropriate location for your POS.

---

InComm

This extension adds to the core EFTPOS payment API that is provided to the POS by the Linkly EFT Client and allows the POS to perform the proprietary Incomm transactions outlined in this document. This document assumes an existing understanding of the Linkly solution and core API's as covered by the Linkly EFTClient TCP Specification.

The Incomm extension file (TPP_INCOMM.bcx) must be installed to the same folder as the EFT-Client executable (EftClnt.exe) on the POS (by default this is the "C:\PC_EFT" folder). The POS must also have the TPPS_GENERIC.BCX extension installed (or an alternative TPPS extension provided by Linkly). The Generic extension provides the TPP Control Panel that can be used for viewing and setting the lane configuration for the TPP extensions. In addition to the basic TPP lane configuration, the Incomm extension requires various identifiers provided by Incomm to be configured via the TPP Control Panel. Depending on the choice for deployment, all TPP settings may also be pushed directly to the registry.

Card Load/Sale

Request:

Field	Description
Command Code	Set to 'M' to indicate transaction request
Merchant	Set to '64' to indicate a InComm transaction
TxnType	Set to 'D' to indicate a Load/Sale
AmtPurchase	Set to the transaction amount
Pan	Card Number if provided by the POS otherwise blank
PanSource	Card capture method if captured by the POS
Track2	Card Track 2 Data if captured by the POS, otherwise blank
TxnRef	Unique transaction reference number
App	Set to '02'
PurchaseAnalysisData
UPC	Card UPC. (Optional)

Response:

Field	Description
Success	'1' if successful
Response Code	'00' if it was approved
Response Text	response message associated with the response code
PurchaseAnalysisData
BAL	Card Balance (Optional)
HRC	InComm Host Response Code (Optional)
REF	InComm transaction reference

Void Card Load/Sale

Request:

Field	Description
Command Code	Set to 'M' to indicate transaction request
Merchant	Set to '64' to indicate a InComm transaction
TxnType	Set to 'I' to indicate a Load/Sale Void
AmtPurchase	Set to the transaction amount
Pan	Card Number if provided by the POS otherwise blank
PanSource	Card capture method if captured by the POS
Track2	Card Track 2 Data if captured by the POS, otherwise blank
TxnRef	Unique transaction reference number
App	Set to '02'
PurchaseAnalysisData
UPC	Card UPC. (Optional)

Response:

Field	Description
Success	'1' if successful
Response Code	'00' if it was approved
Response Text	response message associated with the response code
PurchaseAnalysisData
BAL	Card Balance (Optional)
HRC	InComm Host Response Code (Optional)
REF	InComm transaction reference

Voucher Sale

Request:

Field	Description
Command Code	Set to 'M' to indicate transaction request
Merchant	Set to '64' to indicate a InComm transaction
TxnType	Set to 'V' to indicate a Voucher sale
AmtPurchase	Set to the transaction amount
TxnRef	Unique transaction reference number
App	Set to '02'
PurchaseAnalysisData
UPC	Product UPC (Required if PID not given)
PID	InComm Product ID (Required if UPC not given)

Response:

Field	Description
Success	'1' if successful
Response Code	'00' if it was approved
Response Text	response message associated with the response code
PurchaseAnalysisData
HRC	Response code from InComm
REF	InComm transaction reference
SRN	Product Serial Number (optional)
Voucher Redeem Code (Optional)

Void Voucher Sale

This transaction can be used to void a previous active code (voucher) product sale. Note that the POS must capture and pass the Redeem Code (VRC) of the voucher to void. This code is printed on the receipt and passed in the PurchaseAnalysisData of the original transaction.

Request:

Field	Description
Command Code	Set to 'M' to indicate transaction request
Merchant	Set to '64' to indicate a InComm transaction
TxnType	Set to 'R' to indicate a Voucher Void
AmtPurchase	Set to the transaction amount
TxnRef	Unique transaction reference number
App	Set to '02'
PurchaseAnalysisData
VRC	The Redeem Code of the voucher to void
PID	InComm Product ID (requird if UPC not given)
UPC	Product UPC (required if PID not given)

Response:

Field	Description
Success	'1' if successful
Response Code	'00' if it was approved
Response Text	response message associated with the response code
PurchaseAnalysisData
HRC	Response code from InComm
REF	InComm transaction reference

Registry

The TPP Incomm extension can be configured by pushing values directly to the registry. The following table summarises the registry values that should be set for the TPP Incomm extension.

Registry Key Or Value	Type	Description
..\CullenSoftwareDesign\PCEFFTPOS_BRIDGE\TPP-INCOMM	Key	InComm Registry Key
CAIC	String	Incomm Store ID
CATI	String	Incomm Terminal ID
AIIC	String	Incomm Merchant Retailer Id (optional)
RECEIPT_WIDTH	dword	Receipt width (optional, Default 24, minimum 24)

In addition to these settings, every lane that is using any TPP extension must also configure the following registry locations. These are shared by all TPP extensions.

Registry Key Or Value	Type	Description
..\PC-EFTPOS\LaneInfo	Key	Lane Information Registry Key
MerchantId	String	A unique 5-7 character label that is unique per Merchant/Brand (contact Linkly for this)
StoreId	String	A five-digit store identify of your choosing. It is recommended this be padded to 5 digits. Eg. 01234
LaneId	string	A thre digit lane number (pad to three digits) Eg."005"
StoreAddress	string	Optional store address information.

---

Klarna

Introduction

Klarna is a large Swedish bank that provides international financial services. They eliminate financial risks related to consumer credit by providing in-store credit checks and handling of customer payments.

The Linkly Klarna extension enables the POS to perform Klarna transactions outlined in this section.

Start Developing

Install required software

• Download the latest release candidate Linkly Software and install the "Offline Development" components
  • DevTools will be installed to C:\PC_EFT\DevTools
  • The VirtualPinpad.exe can be launched from the start menu
• Create a Klarna dev account and obtain test credentials.
• Contact Linkly POS Integrations Support - [email protected] - for test gateway credentials.
• Download and install the latest release candidate Linkly Klarna Installer
• Implement the Klarna API as outlined below

Methods

Once a purchase transaction request is made, the Klarna TPP2 Extension will initiate a Klarna payment session, providing a QRCode for the customer to scan. Alternatively, the customer can choose to enter their phone number by clicking the button on the pinpad to receive the Payment Session link via SMS. After the customer has confirmed the payment the approved transaction will be sent back to the POS. The RFN PAD tag will contain the order id and should be stored for any future refunds.

To integrate Klarna, it is recommended that all transactions go through the One Button API via the '99' Merchant number. Regardless, this integration must meet the minimum Core Payments requirements.

Purchase

This transaction can be used to perform a Purchase (QR code / SMS) using Klarna.
Note: QR code only works on compatible terminals. Depending on registry settings and PAD fields a direct SMS purchase can be performed instead of a QR code purchase.
Note: Selecting the SMS option (on the pinpad) at the QR code display will cancel the QR code transaction and fall back to an SMS transaction, prompting the customer to enter their phone number.
Note: This transaction can be cancelled while the QR Code is displayed (using the Cancel button on the POS dialog), but only before the customer completes the purchase.

Request

Field	Description
Command Code	Set to 'M' for a transaction request
App	Set to '02' to indicate an extension request
Merchant	Set to '70' to indicate a Klarna request
TxnType	Set to 'P' to indicate a Purchase
AmtPurchase	Amount to pay with Klarna in cents
CurrencyCode	ISO Currency code (e.g. AUD, NZD). Default AUD
TxnRef	Unique POS reference number
CutReceipt	Indicates to cut or not cut the receipt
ReceiptAutoPrint	Indicates where to print the receipt
PurchaseAnalysisData
SKU	Basket Id
OPR	Operator Reference
AMT	Total Amount
UID	Globally Unique ID
NME	POS Name
VER	POS Version
VND	POS Vendor ID
PCM	POS Capabilities Matrix

Response:

Field	Description
Success	'1' if transaction was successful
Response Code	'00' if the transaction was approved
Response Text	Response message
AmtPurchase	(cond. success) Approved purchase amount
TxnRef	Echoed from request
CurrencyCode	Code to indicate the currency the sale was processed using. Default is AUD
TxnType	Echoed from request
CardName	This returns the Card Bin number, which identifies the payment processor
PurchaseAnalysisData
HRC	Response code from Klarna
HRT	Response Text from Klarna
REF	Reference (Trade No) from Klarna
RFN	Retrieval Reference (used for Refund, Query, Cancel)
UID	Globally unique value echoed from request

---

Refund

This transaction can be used to perform a full or partial Refund using Klarna.
Please Note: Klarna does not support the cancellation (or reversal) of refunds.

Purchase online, refund in-store: When completing a refund in-store for an online purchase with Klarna:

• The REF pad tag indicates the unique identifier returned from the online purchase
• The RFN pad tag does not need to be set

Request:

Field	Description
Command Code	Set to 'M' for a transaction request
App	Set to '02' to indicate an extension request
Merchant	Set to '70' to indicate a Klarna request
TxnType	Set to 'R' to indicate a Refund request
AmtPurchase	Amount to refund from Klarna
CurrencyCode	ISO Currency code (e.g. AUD, NZD). Default AUD
TxnRef	Unique POS reference number
CutReceipt	Indicates to cut or not cut the receipt
ReceiptAutoPrint	Indicates where to print the receipt
PurchaseAnalysisData
RFN	Retrieval Reference of Purchase
OPR	Operator Reference
UID	Globally Unique ID
NME	POS Name
VER	POS Version
VND	POS Vendor ID
PCM	POS Capabilities Matrix

Response:

Field	Description
Success	'1' if transaction was successful
Response Code	'00' if the transaction was approved
Response Text	Response message
AmtPurchase	(cond. success) Approved refund amount
TxnRef	Echoed from request
CurrencyCode	Code to indicate the currency the sale was processed using. Default is AUD
TxnType	Echoed from request
CardName	This returns the Card Bin number, which identifies the payment processor
PurchaseAnalysisData
HRC	Response code from Klarna
HRT	Response Text from Klarna
REF	Reference (Trade No) from Klarna
UID	Globally unique value echoed from request

---

Basket Data

For reference, please see Basket API

---

Custom Deployment

Linkly recommends using the Linkly Klarna installer to install and configure the Linkly Klarna extension.

However, if a custom deployment is required follow these steps:

1. Ensure the latest production Linkly software is installed
2. Copy TPP2_Klarna.bcx from the latest production installer to the Linkly install directory (by default %PROGRAMFILES(x86)%\PC_EFT)
3. Configure registry settings as required
4. Restart the Linkly EFT-Client service

In addition to the basic TPP2 lane configuration, the Klarna extension requires a store level username and password provided by Klarna to be configured in the Registry.

Registry Settings

The following values are all STRING types, and set in the registry under HKEY_LOCAL_MACHINE\SOFTWARE\CullenSoftwareDesign\EFTCLIENT\DLLS\Klarna for x86 and HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\CullenSoftwareDesign\EFTCLIENT\DLLS\Klarna for 64-bit

Name	Default	Description
USERNAME		Klarna username
PASSWORD		Klarna password
COUNTRY_CODE		Klarna Country Code (e.g. AU, NZ)

In addition to these settings, every lane that is using any TPP2 extension must also configure the following registry locations. These are shared by all TPP2 extensions.

The following values are all STRING types, and set in the registry under HKEY_LOCAL_MACHINE\SOFTWARE\CullenSoftwareDesign\EFTCLIENT\LANEINFO for x86 and HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\CullenSoftwareDesign\EFTCLIENT\LANEINFO for 64-bit

Name	Default	Description
MerchantId		A unique 5-7 character label that is unique per Merchant/Brand (contact Linkly for this)
StoreId		A five-digit store identify of your choosing. It is recommended this be padded to 5 digits. Eg. 01234
LaneId		A thre digit lane number (pad to three digits) Eg."005"
StoreAddress		Optional store address information.

---

TruRating

Installation

This document outlines the POS API for the TPP TruRating extension. This extension adds to the core EFTPOS payment API that is provided to the POS by the Linkly EFT Client and allows the lane to capture and send TruRating customer rating to the TruRating host via the Linkly Data Centre. This document is primarily intended for POS software developers who are integrating the TruRating features into the POS. It assumes readers are familiar with the standard Linkly client API which is covered by the ActiveX Documentation.

The TruRating extension file (TPP_TRURATING.BCX) must be installed to the same folder as the EFT Client executable (EftClnt.exe) on the POS (by default this is the "C:\PC_EFT" folder). Like all TPP extensions, the TruRating extension requires the basic TPP lane configuration to be setup in the registry. By default, lane identification for TruRating is taken from the EFTPOS pinpad terminal and Merchant ID's which avoids the need for any special configuration for TruRating. However, these can be overridden if required by applying additional settings in the registry.
By default, the TruRating extension is designed to capture customer ratings on all EFTPOS purchase and refund transactions. This behaviour does not require the POS to specifically invoke the TruRating extension as such the POS may not need to implement any of the API calls outlined in this specification.

New Zealand TruRating uses different settings for New Zealand customers than the default, as such New Zealand customers should make sure the 'HOST_ID' registry setting is set to 'TRU115NZ'.

Methods

Rating

This transaction can be used to perform a customer rating capture via the TruRating extension. A POS would only need to implement this method for Rating capture if the automatic rating mechanism (that captures a rating during a standard EFTPOS tender) does not suffice. For example, the POS may choose to invoke a rating request during the basket scan stage, prior to the tender stage. A response will be sent to the POS at the end of the rating. Alternatively the POS may send a cancel key press event to the EFT Client at any time to terminate the rating capture. Note that the POS must ensure this transaction has ended before the POS makes another transaction request to the Linkly Client (such as an EFTPOS purchase). If the POS is invoking this transaction during basket scan it may be desirable to suppress the PC EFTPOS transaction dialog so that it does not display on the POS during this transaction. Refer to the standard Linkly Client API documentation for further information regarding this.

Request:

Field	Description
Command Code	Set to 'M'
Merchant	Set to '90' to indicate a TruRating transaction
TxnType	Set to 'R' to indicate a Rating Request
AmtPurchase	Set to the transaction amount(attached to the rating)
TxnRef	Unique transaction reference number
App	Set to '02'
PurchaseAnalysisData
OPR	Optional POS operator information
BSK
BFT

Response:

Field	Description
Success	true if successful
Response Code	'00' if it was approved
Response Text	response message associated with the response code

Top-Up

This transaction can be used to apply result, basket, and other additional information to the current rating; such as a rating taken using the above Rating transaction, or even a rating taken automatically during an EFTPOS transaction. The rating will be closed and sent once updated. For an EFTPOS transaction, even one for which a rating was taken using a Rating transaction, various fields, including the response code, amount and tip, will automatically be captured from the EFTPOS transaction result. In such cases it is not necessary to supply these values in the top-up transaction. A top-up transaction can only be used within a certain time period after a rating has been taken (see Registry for settings) and will only apply to the current rating. After the time period has elapsed, or if a new rating is invoked (either manually or automatically), the current rating will automatically be closed and sent. Note: Doing a top-up transaction will close the current rating, and as such, it can only be done once per rating. Note: Any value (including an empty value) passed in the PAD fields of a top-up transaction will overwrite the existing value for that field. It is therefore recommended that PAD fields only be included if a valid value is available.

Tender Types:
Current values for the tender type (Appendix C - Purchase Analysis Data 'TDR' field) include:

• S, Swipe
  
• E, Chip
  
• C, Contactless, Paywave, Tap
  
• K, Keyed, Manual
  
• Cash
  
• Mobile
  
• Gift, Voucher
  
• Other
  

Request:

Field	Description
Command Code	Set to 'M'
Merchant	Set to '90' to indicate a TruRating transaction
TxnType	Set to 'T' to indicate a Top-up request
TxnRef	Unique transaction reference number
App	Set to '02'
PurchaseAnalysisData
OPR	Optional POS operator information
BSK
BFT
TRC	Optional transaction response code to set for the rating
AMT	Optional transaction amount to set for the rating.
TIP	Optional transaction amount to set for the rating
TDR	Optional Tender Type. See Tender types above
LYL	Optional Loyalty Value, STAFF or LOYALTY
CUR	Optional currency value. this must be a ISO 4217 numeric value, e.g '036' for AUD, or '554' for NZD

Response:

Field	Description
Success	true if successful
Response Code	'00' if it was approved
Response Text	response message associated with the response code

Activation

This transaction can be used to perform a manual activation of TruRating on the lane. The main purpose of this transaction would be to reactivate a lane that had been deactivated by the TruRating host. The activation pass code will be prompted for during these transaction and an online TruRating activation will be attempted. A response will then be sent to the POS to indicate the result of the activation attempt.
Note: Activation can also be done by pushing a pass code to the registry. This however is a non interactive background process that administrators may prefer to use for the rare occasions that a reactivation of a lane might be required. Refer to section 5 Registry for further details.

Request:

Field	Description
Command Code	Set to 'M'
Merchant	Set to '90' to indicate a TruRating transaction
TxnType	Set to 'A' to indicate a Activation Request
TxnRef	Unique transaction reference number
App	Set to '02'
PurchaseAnalysisData
OPR	Optional POS operator information

Response:

Field	Description
Success	true if successful
Response Code	'00' if it was approved
Response Text	response message associated with the response code

Registry

In order for the TPP TruRating extension to operate correctly the extension must be configured by setting appropriate values in the POS registry. This can be done automatically via the installer. Every POS/lane that is using any TPP extension must configure the LaneInfo registry location. These are shared by all TPP extensions. The first three values, MerchantId, StoreId and LaneId are crucial to the correct functioning of all TPP extensions and must be configured. Other values are recommended but optional. By default, the TruRating MID and TID are derived from this information (MID is MerchantID_StoreID and TID is LaneId)

Registry Key Or Value	Type	Description
..\PC-EFTPOS\LaneInfo	Key	Lane Information Registry Key
MerchantId	String	A unique 5-7 character label that is unique per Merchant/Brand (contact Linkly for this)
StoreId	String	A five-digit store identify of your choosing. It is recommended this be padded to 5 digits. Eg. 01234
LaneId	string	A thre digit lane number (pad to three digits) Eg."005"
StoreAddress	string	Optional store address information.

The following table summarises additional registry values that affect the behaviour of the TruRating extension. These settings are not normally required and should not be set unless there is a particular need for them.

Registry Key Or Value	Type	Description
..\CullenSoftwareDesign\PCEFFTPOS_BRIDGE\TPP-TRURATING	Key	TruRating Registry Key
Merchant_CODE	String	TruRating Merchant identifier override (obtained from TruRating). When present the TruRating extension will use this as the Merchant identifier instead of using a value derived from the LaneInfo values.
TERMINAL_CODE	String	TruRating terminal identifier override (obtained from TruRating). When present the TruRating extension will use this as the terminal identifier instead of using a value derived from the LaneInfo values.
PASSCODE	string	Reactivation Passcode. When present (and the lane is in a deactivated state) the lane will start silently attempting activations. Once successful or after 5 failed responses, the passcode will be deleted from the registry and the activation attempts will stop.
RATING_TIMEOUT	integer	Rating prompt timeout in seconds. Defaults to 35 secs.
CURRENT_RATING_TIMEOUT	integer	Time Limit for a Top-up transaction to be applied to the current rating. Defaults to 300seconds (5minutes).
AUTO_RATING	integer	Set to 0 to skip automatic rating prompts at the start of an EFTPOS transaction. Default 1.
HOST_ID	string	Optional non-default host id.

Display Settings:

The following table summarises additional registry values that can be used to customise the various displays of the TruRating extension.

Registry Key Or Value	Type	Description
..\CullenSoftwareDesign\PCEFFTPOS_BRIDGE\TPP-TRURATING	Key	TruRating Registry Key
POS_RATING_DISPLAY	String	Optional custom text, up to 2 lines of 25 characters each, to display on POS while customer enters rating. See Note 1.
PRE_RATING_MSG	String	An optional message, up to 8 lines of 16 characters each, that is displayed before the rating prompt.
PRE_RATING_TIMEOUT	integer	Seconds to display the PRE_RATING_MSG for. Default 3
DISPLAY_RATING_1	string	Optional custom text, up to 4 lines of 16 characters each, to display after a rating has been taken. See Note 2, 3 and 4.
DISPLAY_RATING_2	string	Optional custom text, up to 4 lines of 16 characters each, to display after a rating has been taken. See Note 2, 3 and 4.
DISPLAY_RATING_3	string	Optional custom text, up to 4 lines of 16 characters each, to display after a rating has been taken. See Note 2, 3 and 4.
DISPLAY_RATING_DELAY	integer	Milliseconds to display rating text for. Default 1000
DISPLAY_PRIZE	String	Optional custom text, up to 4 lines of 16 characters each, to display if the customer wins a prize See Note 3 and 4.
DISPLAY_PRIZE_DELAY	integer	Milliseconds to display prize text for. Default 6000
DISPLAY_NO_RATING	String	Optional text, up to 4 lines of 16 characters each, to display if the customer skips the rating See Note 3 and 4.
DISPLAY_NO_RATING_DELAY	integer	Milliseconds to display no rating text for. Default 1000.

Note 1: POS_RATING_DISPLAY is split at 25 characters, but padding is otherwise ignored, with the text automatically centred on each line.

Note 2: DISPLAY_RATING_1, DISPLAY_RATING_2, and DISPLAY_RATING_3 are cycled between (unless set as empty) with each successful rating.

Note 3: The text for DISPLAY_RATING_1, DISPLAY_RATING_2, DISPLAY_RATING_3, DISPLAY_PRIZE, and DISPLAY_NO_RATING is split into lines of exactly 16 characters each. To create a nice display, please ensure that each intended line is exactly 16 characters in length (padding with spaces as necessary).

Note 4: DISPLAY_RATING_1, DISPLAY_RATING_2, DISPLAY_RATING_3, DISPLAY_PRIZE, and DISPLAY_NO_RATING are automatically vertically centred if only 1 or 2 lines of text are defined. To force a message to the top of the display add up to a third empty line (i.e. spaces) after the message.

---

WeChat

This extension adds to the core EFTPOS payment API that is provided to the POS by the Linkly EFT Client and allows the POS to perform WeChat payments outlined in this section.
This document assumes an existing understanding of the Linkly solution and core API's.

Purchase

This transaction can be used to perform a purchase using a Wechat payment.

Field	Description
Command Method	Set to 'M' for a transaction request
Merchant	Set to '69' to indicate a WeChat transaction
TxnType	Set to 'P' to indicate Purchase
AmtPurchase	Set the sale amount
Pan	(Optional) Wechat Barcode number
PanSource	(Optional) Barcode capture method
TxnRef	Unique Transaction reference number
App	Set to '02' to indicate an extension request
PurchaseAnalysisData
OPR	Operator ID who performed the sale

Field	Description
Success	'1' if successful
Response Code	'00' if it was approved
Response Text	response message associated with the response code
PurchaseAnalysisData
HRC	Wechat response Code
REF	WeChat Purchase Reference Number
RFN	Refund Code

Refund

This transaction can be used to refund using a Wechat payment.

Field	Description
Command Method	Set to 'M' for a transaction request
Merchant	Set to '69' to indicate a WeChat transaction
TxnType	Set to 'R' to indicate Purchase
AmtPurchase	Set the sale amount
TxnRef	Unique Transaction reference number
App	Set to '02' to indicate an extension request
PurchaseAnalysisData
RFN	Refund reference Code
OPR	Current POS operator id or name

Field	Description
Success	'1' if successful
Response Code	'00' if it was approved
Response Text	response message associated with the response code
PurchaseAnalysisData
HRC	WeChat response Code
REF	WeChat Purchase Reference Number
RFN	Refund Code

Registry

Please refer to the EpayWallet registry section for configuration of the extension.

---

Wishlist

This document outlines the POS API for the TPP Wishlist extension. This extension adds to the core EFTPOS payment API that is provided to the POS by the Linkly EFT Client and allows the POS to perform Wishlist gift card transactions to the Vii/Wishlist host via the Linkly Data Centre. This document is primarily intended for POS software developers who are integrating the Wishlist features into the POS. It assumes readers are familiar with the standard Linkly client API which is covered by the ActiveX interface documentation.

Installation

The Wishlist extension file (TPP_WISHLIST.BCX) must be installed to the same folder as the EFT Client executable (EftClnt.exe) on the POS (by default this is the "C:\PC_EFT" folder). In addition to the basic TPP lane configuration, the Wishlist extension requires the AIIC, CaTI and CaIC values that are provided by Vii to be configured. TPP settings may be pushed directly to the registry. However there is an installer available that will fill these in automatically.

Redeem

This transaction can be used to perform a redemption from a Wishlist gift card. The POS may send the card number in the request if this information is known to the POS. If the card number is not sent by the POS the Wishlist extension will prompt for the card to be swiped on the EFTPOS terminal prior to sending the request to the Wishlist host for processing.

Request:

Field	Description
CommandCode	Set to 'M'
Merchant	Set to '51' to indicate a Wishlist transaction
TxnType	Set to 'P' to indicate a Purchase/Redeem
AmtPurchase	Set to the transaction amount
Pan	Card number if provided by the POS otherwise blank
PanSource	Card capture method if captured by the POS
Track2	Card track 2 data if captured by the POS otherwise blank
TxnRef	Unique transaction reference number
App	Set to '02'
PurchaseAnalysisData
PIN	Card PIN can be sent by the POS here (optional)

Response:

Field	Description
Success	True if successful
Response Code	'00' if it was approved
Response Text	response message associated with the response code
PurchaseAnalysisData
BAL - Optional	Card Balance
EXP - Optional	Card Expiry Date
HRC	Vii/Wishlist Host Response Code

Balance

This transaction can be used to perform a balance enquiry on a Wishlist gift card. The POS may send the card number in the request if this information is known to the POS. If the card number is not sent by the POS the Wishlist extension will prompt for the card to be swiped on the EFTPOS terminal prior to sending the request to the Wishlist host for processing.

Request:

The request is invoked using the ActiveX transaction method. In addition to the usual fields expected for this method, the following table defines the fields that must be set for the Wishlist API.

Field	Description
CommandCode	Set to 'M'
Merchant	Set to '51' to indicate a Wishlist transaction
TxnType	Set to 'B' to indicate a Balance Enquiry
Pan	Card number if provided by the POS otherwise blank
PanSource	Card capture method if captured by the POS
Track2	Card track 2 data if captured by the POS otherwise blank
TxnRef	Unique transaction reference number
App	Set to '02'
PurchaseAnalysisData
PIN	Card PIN can be sent by the POS here (optional)
PMT	Set to '1' for balance prompt (optional)

Response:

Field	Description
Success	True if successful
Response Code	'00' if it was approved
Response Text	response message associated with the response code
PurchaseAnalysisData
BAL - Optional	Card Balance
EXP - Optional	Card Expiry Date
HRC - Optional	Vii/Wishlist Host Response Code

Load

This transaction can be used to load value onto a Wishlist gift card. The POS may send the card number in the request if this information is known to the POS. If the card number is not sent by the POS the Wishlist extension will prompt for the card to be swiped on the EFTPOS terminal prior to sending the request to the Wishlist host for processing.

Request:

Field	Description
CommandCode	Set to 'M'
Merchant	Set to '51' to indicate a Wishlist transaction
TxnType	Set to 'D' to indicate a Load Transaction
AmtPurchase	Set to the transaction amount
Pan	Card number if provided by the POS otherwise blank
PanSource	Card capture method if captured by the POS
Track2	Card track 2 data if captured by the POS otherwise blank
TxnRef	Unique transaction reference number
App	Set to '02'

Response:

Field	Description
Success	True if successful
Response Code	'00' if it was approved
Response Text	response message associated with the response code
PurchaseAnalysisData
BAL - Optional	Card Balance
EXP - Optional	Card Expiry Date
HRC - Optional	Vii/Wishlist Host Response Code

Cancel

This transaction can be used to cancel (or void) the load of a Wishlist gift card. The POS may send the card number in the request if this information is known to the POS. If the card number is not sent by the POS the Wishlist extension will prompt for the card to be swiped on the EFTPOS terminal prior to sending the redemption request to the Wishlist host for processing.

Request:

The request is invoked using the ActiveX transaction method. In addition to the usual fields expected for this method, the following table defines the fields that must be set for the Wishlist API.

Field	Description
Command Code	Set to 'M'
Merchant	Set to '51' to indicate a Wishlist transaction
TxnType	Set to 'I' to indicate a Cancel/Void
AmtPurchase	Set to the transaction amount
Pan	Card number if provided by the POS otherwise blank
PanSource	Card capture method if captured by the POS
Track2	Card track 2 data if captured by the POS otherwise blank
TxnRef	Unique transaction reference number
App	Set to '02'

Response:

The response will be received via transaction. In addition to the usual fields, the following are of particular importance for the Wishlist API.

Field	Description
Success	True if successful
Response Code	'00' if it was approved
Response Text	response message associated with the response code
PurchaseAnalysisData
BAL - Optional	Card Balance
EXP - Optional	Card Expiry Date
HRC - Optional	Vii/Wishlist Host Response Code

Registry

The TPP Wishlist extension can also be configured by pushing values directly to the registry. The following table summarises the registry values that should be set for the TPP Wishlist extension.

Registry Key Or Value	Type	Description
..\CullenSoftwareDesign\PCEFFTPOS_BRIDGE\TPP-WISHLIST	Key	Wishlist Registry Key
AIIC	String	Wishlist AIIC value provided by Vii
CATI	String	Wishlist CATI value provided by Vii
CAIC	String	Wishlist CAIC value provided by Vii

In addition to these settings, every lane that is using any TPP extension must also configure the following registry locations. These are shared by all TPP extensions.

Registry Key Or Value	Type	Description
..\PC-EFTPOS\LaneInfo	Key	Lane Information Registry Key
MerchantId	String	A unique 5-7 character label that is unique per Merchant/Brand (contact Linkly for this)
StoreId	String	A five-digit store identify of your choosing. It is recommended this be padded to 5 digits. Eg. 01234
LaneId	string	A thre digit lane number (pad to three digits) Eg."005"
StoreAddress	string	Optional store address information.

---

WrightExpress

This extension adds to the core EFTPOS payment API that is provided to the POS by the Linkly EFT Client and allows the POS to perform gift card transactions to the WrightExpress host via the PC EFTPOS Data Centre. This document is primarily intended for POS software developers who are integrating the WrightExpress features into the POS. It assumes readers are familiar with the standard Linkly client API which is covered by the Linkly EFTClient TCP Documentation.

The WrightExpress extension file (TPP_WRIGHTEXPRESS.BCX) must be installed to the same folder as the EFT-Client executable (EftClnt.exe) on the POS (by default this is the "C:\PC_EFT" folder). The POS must also have the TPPS_GENERIC.BCX extension installed (or an alternative TPPS extension provided by Linkly). The Generic extension provides the TPP Control Panel that can be used for viewing and setting the lane configuration for the TPP extensions.

In addition to the basic TPP lane configuration, the WrightExpress extension requires the WrightExpress Merchant Code that is provided by WrightExpress to be configured via the TPP Control Panel. Refer to the Linkly TPP Setup Guide for further information about installation and setup of TPP extensions. Depending on the choice for deployment, all TPP settings may also be pushed directly to the registry.

Redeem

This transaction can be used to perform a redemption from a WrightExpress gift card.
The POS may send the card number in the request if this information is known to the POS. If the card number is not sent by the POS the WrightExpress extension will prompt for the card to be swiped on the EFTPOS terminal prior to sending the request to the WrightExpress host for processing.

Request:

Field	Description
Command Code	Set to 'M' to indicate transaction request
Merchant	Set to '59' to indicate a WrightExpress transaction
TxnType	Set to 'P' to indicate a Purchase/Redeem Transaction
AmtPurchase	Set to the transaction amount
Pan	Card Number if provided by the POS otherwise blank
PanSource	Card capture method if captured by the POS
Expiry Date	Card expiry date if provided by POS otherwise blank
Track2	Card Track 2 Data if captured by the POS, otherwise blank
TxnRef	Unique transaction reference number
App	Set to '02'
PurchaseAnalysisData
EXP	voucher expiry Date in DDMMYY format (optional)

Response:

Field	Description
Success	'1' if successful
Response Code	'00' if it was approved
Response Text	response message associated with the response code
RRN	Retrieval Reference Number
PurchaseAnalysisData
BAL	Card Balance (optional)
HRC	WrightExpress Host response Code (optional)

Balance

This transaction can be used to perform a balance enquiry on a WrightExpress gift card.
The POS may send the card number in the request if this information is known to the POS. If the card number is not sent by the POS the WrightExpress extension will prompt for the card to be swiped on the EFTPOS terminal prior to sending the request to the WrightExpress host for processing.

Request:

Field	Description
Command Code	Set to 'M' to indicate transaction request
Merchant	Set to '59' to indicate a WrightExpress transaction
TxnType	Set to 'B' to indicate a Balance Inquiry
AmtPurchase	Set to the transaction amount
Pan	Card Number if provided by the POS otherwise blank
PanSource	Card capture method if captured by the POS
Expiry Date	Card expiry date if provided by POS otherwise blank
Track2	Card Track 2 Data if captured by the POS, otherwise blank
TxnRef	Unique transaction reference number
App	Set to '02'
PurchaseAnalysisData
EXP	voucher expiry Date in DDMMYY format (optional)

Response:

Field	Description
Success	'1' if successful
Response Code	'00' if it was approved
Response Text	response message associated with the response code
PurchaseAnalysisData
BAL	Card Balance (optional)
HRC	WrightExpress Host response Code (optional)

Activation

This transaction can be used to activate a WrightExpress gift card.
The POS may send the card number in the request if this information is known to the POS. If the card number is not sent by the POS the WrightExpress extension will prompt for the card to be swiped on the EFTPOS terminal prior to sending the request to the WrightExpress host for processing.

Request:

Field	Description
Command Code	Set to 'M' to indicate transaction request
Merchant	Set to '59' to indicate a WrightExpress transaction
TxnType	Set to 'D' to indicate a Load Transaction
AmtPurchase	Set to the transaction amount
Pan	Card Number if provided by the POS otherwise blank
PanSource	Card capture method if captured by the POS
Expiry Date	Card expiry date if provided by POS otherwise blank
Track2	Card Track 2 Data if captured by the POS, otherwise blank
TxnRef	Unique transaction reference number
App	Set to '02'
PurchaseAnalysisData
EXP	voucher expiry Date in DDMMYY format (optional)

Response:

Field	Description
Success	'1' if successful
Response Code	'00' if it was approved
Response Text	response message associated with the response code
RRN	Retrieval Reference Number
PurchaseAnalysisData
BAL	Card Balance (optional)
HRC	WrightExpress Host response Code (optional)

Activation

This transaction can be used to cancel (or void) the activation of a WrightExpress gift card.
The POS may send the card number in the request if this information is known to the POS. If the card number is not sent by the POS the WrightExpress extension will prompt for the card to be swiped on the EFTPOS terminal prior to sending the redemption request to the WrightExpress host for processing.

Request:

Field	Description
Command Code	Set to 'M' to indicate transaction request
Merchant	Set to '59' to indicate a WrightExpress transaction
TxnType	Set to 'I' to indicate a Cancel/Void
AmtPurchase	Set to the transaction amount
Pan	Card Number if provided by the POS otherwise blank
PanSource	Card capture method if captured by the POS
Track2	Card Track 2 Data if captured by the POS, otherwise blank
TxnRef	Unique transaction reference number
App	Set to '02'

Response:

Field	Description
Success	'1' if successful
Response Code	'00' if it was approved
Response Text	response message associated with the response code
PurchaseAnalysisData
HRC	WrightExpress Host response Code (optional)

Registry

The TPP WrightExpress extension can also be configured by pushing values directly to the registry. The following table summarises the registry values that should be set for the TPP WrightExpress extension.

Registry Key Or Value	Type	Description
..\CullenSoftwareDesign\PCEFFTPOS_BRIDGE\TPP-WEXPRESS	Key	WrightExpress Registry Key
Merchant_CODE	String	WrightExpress Merchant Code value provided by WrightExpress

In addition to these settings, every lane that is using any TPP extension must also configure the following registry locations. These are shared by all TPP extensions.

Registry Key Or Value	Type	Description
..\PC-EFTPOS\LaneInfo	Key	Lane Information Registry Key
MerchantId	String	A unique 5-7 character label that is unique per Merchant/Brand (contact Linkly for this)
StoreId	String	A five-digit store identify of your choosing. It is recommended this be padded to 5 digits. Eg. 01234
LaneId	string	A thre digit lane number (pad to three digits) Eg."005"
StoreAddress	string	Optional store address information.

---

ZipMoney

This extension adds to the core EFTPOS payment API that is provided to the POS by the Linkly EFT Client and allows the POS to perform the proprietary ZipMoney transactions outlined in this document. This document assumes an existing understanding of the Linkly solution and core API's as covered by the Linkly EFTClient TCP Specification. The use of this API assumes an existing understanding and implementation of the Linkly Basket API.

The ZipMoney extension file (TPP2_ZipMoney.bcx) must be installed to the same folder as the EFT Client executable (EftClnt.exe) on the POS (by default this is the "C:\PC_EFT" folder). The ZipMoney extension is also dependent on the TPP_MasterGUI.bcx for basket and certain standalone functionality.
In addition to the basic TPP lane configuration, the ZipMoney extension requires various identifiers provided by ZipMoney to be configured in the Registry.

GetLastTransaction and ReprintReceipt are supported in ZipMoney and follow the standard API format, with the exception that the Merchant is set to '89' for Zip instead of '00' for eftpos.

Purchase

Request:

Field	Description
Command Code	Set to 'M' to indicate transaction request
Merchant	Set to '89' to indicate a ZipMoney transaction
TxnType	Set to 'P' to indicate a Purchase
AmtPurchase	Set to the transaction amount
Pan	ZipMoney code if provided by the POS otherwise blank
PanSource	Code capture method if captured by the POS
TxnRef	Unique transaction reference number
App	Set to '02'
PurchaseAnalysisData
OPR	Operator info in the format: RefCode
AMT	Total Transaction amount (must be >= AmtPurchase) (optional)
TAX	Tax amount (optional)
SHP	Shipping amount (optional)
SKU	Basket Id from Basket API

Response:

Field	Description
Success	'1' if successful
Response Code	'00' if it was approved
Response Text	response message associated with the response code
PurchaseAnalysisData
HRC	Response Code from ZipMoney
REF	ZipMoney Transaction Id
RFN	ZipMoney transaction Id (to be used for refund)

Refund

Field	Description
Command Code	Set to 'M' to indicate transaction request
Merchant	Set to '89' to indicate a ZipMoney transaction
TxnType	Set to 'R' to indicate a Purchase
AmtPurchase	Set to the Refund amount
TxnRef	Unique transaction reference number
App	Set to '02'
PurchaseAnalysisData
OPR	Operator info in the format: RefCode
REF	ZipMoney Id of the transaction to refund
RFN	Refund reference code. Will override REF value for VAS API support.

Response:

Field	Description
Success	'1' if successful
Response Code	'00' if it was approved
Response Text	response message associated with the response code
PurchaseAnalysisData
HRC	Response Code from ZipMoney

Basket Data

For reference, please see Basket API

Registry

The TPP ZipMoney extension can be configured by pushing values directly to the registry. The following table summarises the registry values that should be set for the TPP ZipMoney extension.

Registry Key Or Value	Type	Description
..\CullenSoftwareDesign\EFTCLIENT\DLLS\TPPZIPMONEY	Key	ZIPMONEY Registry Key
API_KEY	String	API key provided by ZipMoney
LOCATION_ID	String	Location ID provided by ZipMoney
SEND_APPROVED_ACK	String	If acknowledgement is needed - Empty for disabled; Value of '1' to enable (Optional)

In addition to these settings, every lane that is using any TPP extension must also configure the following registry locations. These are shared by all TPP extensions.

Registry Key Or Value	Type	Description
..\CullenSoftwareDesign\EFTCLIENT\LaneInfo	Key	Lane Information Registry Key
MerchantId	String	A unique 5-7 character label that is unique per Merchant/Brand (contact Linkly for this)
StoreId	String	A five-digit store identify of your choosing. It is recommended this be padded to 5 digits. Eg. 01234
LaneId	String	A thre digit lane number (pad to three digits) Eg."005"
StoreAddress	String	Optional store address information.

---

Appendix

Appendix A - Merchant Codes

Below are the Merchant codes that can be entered into a Merchant field, this will perform the request/method ONLY with the Merchant specified, unless the Merchant is '00'.
The Default Merchant is '00' which is EFTPOS, for regular sales and requests use this merchant code.

Note: Not all functions are supported by all Merchants.

Merchant IDs & TID PREFIX FOR TPP DLL's

Merchant Code / Merchant HostId	Description
51 / WLT	Wishlist
52 / GVX	Givex
53 / BHN	Blackhawk
54 / PPL	Paypal
55 / ZOO	Zoo Republic
56 / EPY	ePay (Not Used)
57 / FDI	FDI
58 / TBM	The Bored Monkey
59 / WEX	WrightEXpress
60 / RNT	Rental Payments / NAB Transact
61 / HRS	Harris Scarfe
61 / UNP	United Petroleum (Fuel Card/Shopper Docket)
61 / FUS	Fusion Loyalty
62 / QLG	Qantas Loyalty Gateway
63 / EPY	ePay Universal Protocol
64 / INC	Incomm
65 / AFP	AfterPay
66 / ALI	Alipay
70 / KLA	Klarna
?? / ARK	Arkade Loyalty
89 / ZMY	ZipMoney
90 / TRU	TruRating
99 / SLV	Slave

Note: 61 can be used for any proprietary in-house extension that will never be deployed outside a given Merchant.

---

Appendix B - Response Codes

Below are the response codes to a specific function. The codes are usually associated with a 'Response Text' that describe the result of the function performed.
Eg. 00 for a transaction is approved and its Response Text is "APPROVED ".

Common Response Codes

Response Code	Response Text	Additional Information
00	APPROVED	Transaction / function completed successfully
S0	MODEM ERROR	(Should be CBA only) Generic Connection error - can't connect to the bank
S7	NO EFT SERVER	Linkly EFT Client is not connecting to EFT Server
S8	NO EFT SERVER	Error in the lines tab of the EFT Server
P7	COMMS ERROR	Comms issue with the pinpad or the EFT server
XT	CONFIG REQUIRED	Pinpad not configured with TID/MID
TF	INIT REQUIRED	Pinpad needs to be logged on
TB	TMS REQUIRED	Pinpad needs to logon to TMS
N8	SERVER ERROR	Invalid TID entered into the pinpad
B1	PRINTER ERROR	Linkly setup to handle printing, but no printer defined
97	ALREADY SETTLED	Pinpad already has been settled
78, 79, XG	SYSTEM ERROR	ANZ Specific: Bank configuration issue
ZB	PINPAD BUSY	ANZ Specific: Pinpad is not ready to accept transaction
X0	NO RESPONSE	Bank not responding to the terminal

Developer-Specific Response Codes

Response Code	Response Text	Additional Information
00	APPROVED
08	Approved
A1	Recursive Call	ActiveX busy
A4	Invalid Merchant	Merchant does not exist
A7	Internal Buffer	ActiveX message smaller than expected
B2	Unsupported Operation
B3	Client Offline	Client not running / another program using client
B4	Internal Buffer	ActiveX message larger than expected
B5	Invalid Amount	POS sent wrong amount
B6	Invalid Dialog
B7	Invalid TxnType
B8	Invalid TxnRef
BY	PINpad Busy
D0	Invalid AuthCode	POS sent wrong AuthCode
E2	No Previous Txn
TG	Display Error	POS display error
TH	Printer Error	POS Printer Error
Z0	Modem Error
Z5	Power Fail

---

Appendix C - Purchase Analysis Data

The purchase analysis data field allows the POS to send custom tag data to the pinpad.
It is also possible for the pinpad to return data to the POS in the field for certain messages.
The format for both send and receive of this data is the same. The value of each tag is dependent upon the pinpad application.

Only use this field if instructed by Linkly.

Byte Position	Field	Length	Description
THE FOLLOWING FIELDS ARE REPEATED FOR EACH TAG.
0	Tag Name	3	The name of the tag as defined by the pinpad
2	Tag Data Length	3	The length of the tag data to follow, not including the tag name and data length fields. ASCII and padded with leading zeros.
5	Tag Data	X	The tag data as defined by the pinpad

Example 1:
Setting the property to "XXX006ABCDEF" would mean the pinpad receives a tag called 'XXX' with a length of 6 and the data 'ABCDEF'

Example 2:
Setting the property to "XXX001aYYY003ABCZZZ00245" the pinpad receives:

• A tag called 'XXX' with a length of 1 and the data 'a'
  
• A tag called 'YYY' with a length of 3 and the data 'ABC'
  
• A tag called 'ZZZ' with a length of 2 and the data '45'
  

Silent Card Not Supported In Transaction

• This tag allows the pinpad to silently end a sale if the card that is presented is not handled by the pinpad.
  
• The pinpad will exit with a response code indicating the card is not accepted, but the pinpad will not do any displays on the POS.
  
• TAG:
  
  • SLT0011
• Direction
  • POS --> Linkly
    
• Banks Supported:
  
  • CBA
    
  • NAB?
    
• Transaction Types Supported:
  
  • Transaction
    

Limit Account Selection

• This tag instructs the pinpad to limit the accounts that are allowed for this sale. It can be used by the POS to stop a customer selecting a particular account (even if the bank rules allow it)
  
• TAG:
  
  • LAS
    
  • Where a = CHQ, b = SAV, c = CR
    
  • Values are '0' for not allowed and '1' for allowed
    
  • e.g. LAS003001 would only allow credit accounts
    
• Direction
  • POS --> Linkly
• Banks Supported:
  
  • CBA
    
• Transaction Types Supported:
  
  • Transaction
    

Operator Display Prompts

• Optional return tag on the Display Event or Transaction Response that returns additional operator display information
  
• TAG:
  
  • ODP
    
• Direction
  • POS --> Linkly
• Banks Supported:
  
  • None. Custom add-on DLL required
    
• Transaction Types Supported:
  
  • Display Events
    
  • Transaction Events
    

Field 48 Data

• Data to be sent to the bank in Field 48
  
• TAG:
  
  • F48
    
• Direction
  • POS --> Linkly
• Banks Supported:
  
  • ANZ
    
• Transaction Types Supported:
  
  • All
    

Myer Specific

• Myer Gift Card specific tags for ANZ to handle.
  
• TAG:
  
  • MYR
    
• Direction
  • POS --> Linkly
• Banks Supported:
  
  • ANZ
    
• Transaction Types Supported:
  
  • All
    

Tip value passed from POS

• Tip value collected by POS solution, only needed if the POS wishes to supress the tip collection by the Linkly solution. The value to be included is to be numeric and 4 characters long.
• TAG:
  
  • TIP
    
• Direction
  • POS --> Linkly
• Banks Supported:
  
  • All
    
• Transaction Types Supported:
  
  • Purchase
    

Amount tag

• Tag used to pass the outstanding total, used when transactions are performed that include incremental charges or additional values were added during the transaction. Numeric 9 digits
• TAG:
  
  • AMT
    
• Direction
  • Linkly --> POS
• Banks Supported:
  
  • All
    
• Transaction Types Supported:
  
  • All

SKU tag

• This tag is to contain the Basket ID that applies to this transaction.
• TAG:
  • SKU
• Directionn
  • POS --> Linkly
• Banks Supported:
  • All
• Transasaction Types Supported:
  • All

Unique Card Identifier

• The UCI tag may be returned to provide a unique hashed value of a card that can be used by the POS to identify the same card in future sales.
  
• The UCI will only be unique when returned from the same banks pinpad.
  
• TAG:
  
  • UCI{hash value}
    
  • Eg UCI1234567890
    
• Direction
  • Linkly --> POS
• Banks Supported:
  
  • None!
    
• Transaction Types Supported:
  • All.

Available Balance

• Balance available after a sale
• TAG:
  
  • ABA
    
• Direction
  • Linkly --> POS
• Banks Supported:
  
  • ANZ
    
• Transaction Types Supported:
  
  • Transaction Response
    

Cleared Funds Balance

• Balance of cleared funds.
  
• TAG:
  
  • CFD
    
• Direction
  • Linkly --> POS
• Banks Supported:
  
  • ANZ
    
• Transaction Types Supported:
  
  • Transaction Response
    

Appendix D - Application Codes

• These codes allow the POS to direct a command to a specific application.
  
• They should only be used in consultation with Linkly.
  

Code	Application
'00'	EFTPOS
'01'	AGENCY
'02'	Linkly Configurable Application
'03'	Gift Card
'04'	Fuel
'05'	Medicare
'06'	Amex
'07'	Cheque Auth

Appendix F - TxnType

Description:
This property should be set to indicate the type of transaction to be performed when calling transaction or settlement.

Values	Application
B	Balance Enquiry.
P	Purchase, Purchase & Cash
R	Refund
C	Cash Only
D	Deposit The deposit amount is placed in AmtPurchase (excluding STG Agency terminal) St George Agency terminal note: AmtPurchase contains the cheque amount AmtCash contains the cash amount to deposit TotalPurchaseCount contains the total number of cheques to deposit.
L	Completion
M	Auto-Completion The following properties must be set prior to this call: - rrn (as returned in original request) - auth code (as returned in original request) - AmtPurchase. - TxnRef - PanSource - Track2 (as returned in original request) - AccountType(as returned in original request)
V	Voucher Entry The following properties must be set prior to this call: AccountType ('0' = Savings, '1' = Cheque, '2' = Credit, '3' = Account 1, '4' = Account 2, '5' = Account 3, '6' = Account 4, '7' = Account 5) - Date (DDMMYY) - Time (HHMMSS) - rrn (as returned in original request) - auth code (as returned in original request) - AmtPurchase. - TxnRef - PanSource = 'K' - Pan (contents of the card number) - DateExpiry (MMYY) - CsdReservedString3 (Card Sequence Number. Normally 2 digits) - DataField (The original transaction type. 'P', 'C', 'R', 'D' )
T	Tip-Adjustment The following properties must be set prior to this call: - rrn (as returned in original request) - auth code (as returned in original request) - AmtPurchase. - TxnRef - PanSource - Track2 (as returned in original request) - DateExpiry (if manually keyed) - Pan (if manually keyed) - AccountType (as returned in original request)
W	Withdrawal The withdrawal amount is to be set in the AmtPurchase property.
F	Funds Transfer The amount to transfer is to be placed in the AmtPurchase property
O	Order Request An order request will ask the bank to send something to the customer (eg statement, cheque book, etc)
H	Mini Transaction History Retrieve recent transaction details based upon the customer's card details
X	Get and Authorise a PIN Ask the customer for their PIN, and authorise it with the bank
K	Enhanced PIN command This will perform an enhanced PIN command as defined by the bank pinpad The following properties can be set prior to this call: - AmtPurchase. - TxnRef - PanSource - Track2 (as returned in original request) - DateExpiry (if manually keyed) - Pan (if manually keyed) - AccountType (as returned in original request) - DataField
I	Void

Settlement Types

• 'S' Settlement
  
• 'P' Pre-Settlement
  
• 'L' Last Settlement
  
• 'U' Sub Totals or Summary Totals for ANZ
  
• 'H' Shift Totals or Subtotals for ANZ
  
• 'I' Txn Listing
  
• 'M' Start Cash
  
• 'F' Store and Forward (SAF) Totals report
  
• 'D' Daily Cash Statement (STG Agency)
  

Returned by transaction and SettlementEvent.
Applies to transaction and settlement.
Note: Not all TxnTypes are supported by all acquirers.

---

Appendix ZZZ - XML Message Format

The XML message format is based upon the standard Linkly ActiveX interface.
It does not comply with the TCP/IP interface specification at all.
Note:
There is currently no test client available using the XML interface. Do not use the XML interface without discussions with Linkly

Message Structure:

Byte Position	Tag Name	Length	Description
1	Start Flag	1	'&'
2	Length	6	Length of the message including start and length fields
8	XML Tags	*	XML document in the format: < PCEFTPOS_BRIDGE> < PCEFTPOS_MSGID > ? </ PCEFTPOS_MSGID > < PCEFTPOS_DESTINATION > </ PCEFTPOS_DESTINATION > < PCEFTPOS_SOURCE > </ PCEFTPOS_SOURCE > < PCEFTPOS_METHOD > < Tag1 >Value</ Tag1 > < Tag2 >Value </ Tag2 > ... < Tagn >Value</ Tagn > </ PCEFTPOS_METHOD > </ PCEFTPOS_BRIDGE >

Where:

• PCEFTPOS_MSGID is unique message id to identify the current message.
• PCEFTPOS_DESTINATION is the destination of the XML message(POS/EFTPOS/PCEFTPOS
  
• PCEFTPOS_SOURCE is the original sender of the XML message
• PCEFTPOS_METHOD is a method from the ActiveX control.
• PCEFTPOS_EVENT is an event returned from the Linkly Client.
• Tag1...etc is a property from the ActiveX control.

Methods

• The XML interface allows any ActiveX method to be called. The POS is required to accurately complete the required properties for each method as per the Linkly ActiveX Interface guide.
  

Events

• Linkly will generate events to the POS as per the ActiveX Developers Guide. These events will have the required properties set and are to be interpreted as per the ActiveX guide.
  

Properties

• Any property from the ActiveX control can be set in any method with an XML interface.

• The client will validate the properties for EFTPOS requests only.

Document Version

Version	Date	Revisions
1.0.3	18 August 2022	- Updating POS Support email to [email protected]
1.0.2	23 June 2022	- Removing Deprecated TxnType 'G' (MOTO); Use PanSource to perform MOTO transactions
1.0.1	31 May 2022	- Updating jquery version - moving Document Version section to end of document
1.0.0	16 May 2022	- Removed pre-authorisation and bar tab

---