Introduction

The ActiveX interface utilises the Linkly ActiveX control (CsdEft.ocx) which is included in the standard Windows Linkly installation. When using this interface the EFT-Client can be running on Windows XP SP2, Windows Vista, Windows 7 or Windows 10.

The interface works on the basis of settings properties that live in the controller, then calling the respective method (DoTransaction() for a transaction) and setting up eventHandlers to handle event responses such as displays, prints and transaction responses.

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

SDK

When the ActiveX component is linked to a project a wrapper is generated by the development environment. The video below shows how to setup the ActiveX controller on a C# Windows Form.

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 DoTransaction 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
Method	DoTransaction
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
PosProductId	Set to 'TXN_TAG_DATA'
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(64)	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 DoTransaction 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	'true' if successful, 'false' 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 dotransaction request format. The POS must ensure that the correct 'RFN' Tag is sent when performing a refund.

Request

Field	Description
Method	DoTransaction
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
PosProductId	Set to 'TXN_TAG_DATA'
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(64)	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 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
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
Method		Indicates to reprint or retrieve (sent to POS)	DoReprintReceipt or DoGetLastReceipt
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 DoGetLastTxn 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
Method		Get last transaction result	DoGetLastTransaction
Merchant	2	Must be '00' for the Core Payments API	'00'

Get Last Transaction Response

The POS will receive a standard DoGetLastTxn Response

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

---

Message Format

Basket data uses the "Generic POS Command" (see csdReservedMethod3) message type.

You must first send the basket using csdReservedMethod3 setting TxnType to '%'.
Then you can request a sale with a specific basket using it's SKU.

---

Basket Command Header Fields

//Example Basket Header Data
{   
 "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 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.

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
- 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 TransactionEvent, and will contain the value of the surcharge 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)

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

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

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

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

---

DoCardSwipe

axCsdEft1.Track2 = "0123456789=01234"; // Enter your track2 data to send here
axCsdEft1.DoCardSwipe();

Description:
This method is used to start a transaction on the EFTPOS device with the card read function already completed. The EFTPOS device will take the contents of track2 as the card read, and start at the "SELECT ACCOUNT‟ prompt.
Properties to Set:

Name	Description
Track2	Must be loaded with the output of a magnetic stripe read before calling DoCardSwipe.

Event that will fire:
The event CardSwipeEvent is fired when the command completes. Note: This method is not catered for by all acquirers.

---

DoChequeVerify

axCsdEft1.ChqBranch = "MyBranch"; //6 digit branch code for the cheque
axCsdEft1.ChqSerialNumber = "12DigitNumber"; //12 digit serial number of the cheque
axCsdEft1.ChqAccount = "14DigitAccountNumber"; //14 digit account number of the cheque
axCsdEft1.AmtPurchase = 10.00M; // $10.00 cheque amount
axCsdEft1.AccountType = "0"; //code with type of cheque
//This will fire a 'ChequeVerifyEvent' when the method completes.

Not supported by all banks

Description:
This method invokes the Cheque Authorisation capabilities of the Linkly system.

Properties to set:

Name	Description
ChqBranch	This is the 6 digit branch code for the cheque
ChqSerialNumber	12 digit serial number of the cheque
ChqAccount	14 digit account number of the cheque
AmtPurchase	The amount of the cheque
AccountType	The type of Cheque. "0‟ = Business Guarantee, "1‟ = Personal Guarantee, "2‟= Business Appraisal, "3‟ = Personal Appraisal

Event that will fire:
The event ChequeVerifyEvent is fired when the command completes.

---

DoConfigMerchant

Description:

This method configures the EFTPOS PINpad merchant parameters. Linkly recommends that POS vendors call the DoSetupPinpad() or DoControlPanel() to configure the Pinpad where possible.

Properties to set:

Name	Description
Aiic	set for the indicated merchant.
Nii	set for the indicated merchant.
Catid	set for the indicated merchant.
Caid	set for the indicated merchant.
Timeout	set for the indicated merchant. The PINpad retains the settings of Catid, Caid Aiic, Nii, and Timeout until another call to DoConfigMerchant.
Merchant	The current release does not support multi-merchant operation. The only allowable value for Merchant is 0.
TxnType	If this is set to "CONFIG_EXTEND", then the property DataField will be sent to the pinpad with any data that it contains. The format of this data is dependent upon the bank and this should only be used by Linkly.

Event that will fire:
The event ConfigMerchantEvent is fired when the command completes.

---

DoControlPanel

Description:
This method causes an EFTPOS Control Panel to be displayed, allowing the user to initiate EFTPOS operations and perform EFTPOS configurations (password required). While the control panel is active, any further method calls will fail. The operator can dismiss the EFTOPS control panel, re-enabling method calls.
Properties to set:

Name	Description
ReceiptAutoPrint	Should be set before calling this method, as receipt printing can be performed from the panel. Can be true or false
CutReceipt	Should be set before calling this method, as receipt printing can be performed from the panel. Can be true or false

Event that will fire:
The event ControlPanelEvent is fired when the command completes (when the control panel is closed).

---

DoDisplaySettlement

Description:
This method causes a Settlement Panel (dialog window) to be displayed containing settlement options for the acquirer. This method is recommended to be called by all POS vendors as it gives universal access to the settlement options available to all acquirers.
Properties to be set:

Name	Description
ReceiptAutoPrint	Should be set before calling this method, as receipt printing can be performed from the panel. Can be true or false
CutReceipt	Should be set before calling this method, as receipt printing can be performed from the panel. Can be true or false

Event that will fire:
The event DisplaySettlementEvent is fired when this operation completes (when the dialog is closed).

---

DoDisplayStatus

axCsdEft1.DoDisplayStatus();
//The event 'DisplayStatusEvent' will fire when this method completes.

Description:
This method causes a Status Panel (dialog window) to be displayed containing version and status information for the various EFTPOS subsystem components.
Properties to set:
None.
Event that will fire:
The event DisplayStatusEvent is fired when this operation completes (when the dialog is closed).

---

DoGetLastReceipt

Description:
This method retrieves the last receipt produced by the PINpad. It can also be used to request a previous receipt based upon card number and amount.

Properties to set:

Name	Description
MessageType	3 for retrieve using card number 4 to retrieve based upon card # and amounts.
DataField	CardNumber to lookup(10char) Purchase Amount (zero left filled with no decimal point) Cash Out Amount (zero left filled with no decimal point) Refund Amount (zero left filled with no decimal point) Eg. "4561234567000000100000000000000000000" Look for card 4561234567 with a 1.00 purchase and no cash or refund

Event that will fire:
The event GetLastReceiptEvent is fired when the command completes or times out. The Receipt property will be set

---

DoGetLastTransaction

axCsdEft1.DoGetLastTransaction();
//The event 'GetLastTransactionEvent' will fire when this method completes.

Description:
This method retrieves the details of the last transaction processed by the PINpad. This method could be called by a POS application to determine whether a transaction was successful or not following a power failure whilst an EFTPOS transaction was in progress. The POS application should in this case check the contents of the TxnRef and LastTxnSuccess properties after a successful call.
Note that the Success property refers to the outcome of the call to DoGetLastTransaction, 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 DoGetLastTransaction - use the method DoGetLastReceipt to retrieve receipt data for a specified merchant.
Properties to set:
None.
Event that will fire:
The event GetLastTransactionEvent is fired when this operation completes.

---

DoInvokeApplet(String AppName)

Not Supported
Description:
This method invokes a specified EFTPOS applet.
Properties to set:
None (yet!!!!)
Event that will fire:
The event InvokeAppletEvent is fired when this operation completes.

---

DoJournalViewer

axCsdEft1.DoJournalViewer();
//The event 'JournalViewerEvent' will fire when this method completes.

Description:
This method invokes the electronic journal viewer utility.
Properties to set:
None
Event that will fire:
The event JournalViewerEvent fires when the journal viewer is dismissed

---

DoLogon

Description:
This method initiates an EFTPOS logon to the acquirer (bank), regardless of whether the PINpad is already logged on or not. Linkly do not recommend calling this method as the EFTPOS device attached will automatically perform a logon if it requires it when a transaction is started.

TxnType	Description
RSA_LOGON	The Terminal will performs an RSA Logon
TMS_FULL	The terminal will perform a TMS Logon
TMS_PARAMS	The terminal will perform a TMS Params Logon
TMS_SW	The terminal will perform a TMS S/W Logon
LOGOFF	Send a logoff command to the pinpad . (Not required as most banks will not logoff)
Anything else	Standard Bank Logon

Event that will fire:
The event LogonEvent fires when the operation is complete.

---

DoQueryCard

axCsdEft1.txntype = 2;
axCsdEft1.DoQueryCard();
//The event 'QueryCardEvent' will fire when this methods completes.

Description:
This method will instruct the EFTPOS device to perform a card read operation. The details of the card read (track1, track2) are returned when the event fires.

Properties To Set:

Name	Description
TxnType	"2" = for the pinpad to read the card, then prompt for account. (Not supported by all banks) "7" = for pre-swipe (WW only "8" for Custom WW Card Read (WW Only)

Event that will fire:
The event QueryCardEvent fires when the operation is complete.If the request is of TxnType '7', there will be no event fire at all.

---

DoReprintReceipt

axCsdEft1.DoReprintReceipt();
//The event 'ReprintReceiptEvent' will fire when this method completes.

Description:
This method instructs the PINpad to print a copy of the last financial receipt. The EFTPOS receipt is always a "duplicate copy" receipt in line with bank certification requirements that no more than one copy of an EFTPOS receipt be printed without identifying it as a duplicate.
Properties to set:

Name	Description
ReceiptAutoPrint	AutoPrint should be set to indicate if POS is printing. Can be true or false
CutReceipt	should be set to indicate if the reprinted receipt should be cut and ejected from the printer. Can be true or false

Event that will fire:
The event ReprintReceiptEvent is fired when this operation ends.

---

DoReset

Description:
This method resets all of the ActiveX control's properties to their default settings.
Properties to set:
None
Event that will fire:
None

---

DoSelfTest

Description:
This method initiates an EFTPOS subsystem self-test.
Properties to set:
None
Event that will fire:
The event SelfTestEvent is fired when this operation ends.

---

DoSetFocus

//Takes a boolean parameter (Bool EnableTxnDialogFocus)
axCsdEft1.DoSetFocus(true);
//The event 'SetFocusEvent' is fired when this method completes.

Description:
This method allows the POS to return focus to the EFTPOS transaction dialog.
Properties to set:
None
Event that will fire:
The event SetFocusEvent is fired when this operation ends.

---

DoSettlement

Description:
This method forces a settlement with the acquirer (bank) and retrieves the totals since the last acquirer settlement. It is recommended that the POS does not call this method directly. The POS should use the DoDisplaySettlement method where possible.
Properties to set:

Name	Description
Merchant	See definitions
TxnType	See definitions
ResetTotals	The (shift Totals) TxnType can set this to indicate if the stored totals should be cleared (reset to zeros).
DateSettlement	This is set to ask the bank to return this days totals. (Not accepted by all banks).
TotalsData	specific to certain settlement types.
Tag Data is allowed. It is only used by specific pinpads.

Event that will fire:
The event SettlementEvent is fired when this operation ends. Note: Not all acquirers support all TxnTypes for this function.

---

DoSetupPinPad

Description:
This method causes a Pinpad Setup Panel (dialog window) to be displayed.
Properties to set:
None
Event that will fire:
The event SetupPinPadEvent is fired when this operation completes (when the dialog is closed).

---

DoShowDialog

//takes a boolean parameter (Bool Show)  
axCsdEft1.DoShowDialog(true);//set to true to show and false to hide

Description:
This method allows the POS application to show or hide an EFTPOS Dialog. Extreme care must be exercised when using this method and a special certification process may be required if it is used. While the EFTPOS dialog is in progress, operator keypress events are available to the POS via the KeyDownEvent.
Properties to set:
None -- Set the Show parameter to TRUE to display the dialog, or FALSE to hide it.
Event that will fire:
None

---

DoSoftwareActivate

NOT SUPPORTED:
Description:
This method activates the latest software downloaded and stored during a call to DoSoftwareDownload.
Properties to set:
None
Event that will fire:
The event SoftwareActivateEvent is fired when this operation ends.

---

DoSoftwareDownload

NOT SUPPORTED
Description:
This method starts a remote download of Linkly software to be stored locally. After a successful download, the software can be activated using the call DoSoftwareActivate.
Properties to set:

Name	Description
FileName	Name of the remote file.

Event that will fire:
The event SoftwareDownloadEvent is fired when this operation ends.

---

DoStatus

axCsdEft1.csdReservedString2 = "";
axCsdEft1.MessageType = 0;
axCsdEft1.DoStatus();
//The event 'StatusEvent' is fired when this method completes.

Description:
This method queries the PINpad details about its current configuration, and status.
Properties to set:

Name	Description
CsdReserverdString2	Name of application to request status from. If this is blank, the EFTPOS application will be returned.
MessageType	Type of Status to request. Current values are: 0 = Normal Status 1 = Terminal Application information 2 = Application CPAT 3 = Application Name Table 4 = Undefined 5 = Pre-Swipe Status (WW Only)

Event that will fire:
The event StatusEvent is fired when this operation ends.

---

DoTransaction

//Simple $10.50 sale with no cashOut
axCsdEft1.TxnRef = "1" //This should be a unique value for each txn
axCsdEft1.Merchant = 0;
axCsdEft1.TxnType = "P";
axCsdEft1.AmtPurchase = 10.50M //$10.50 sale
axCsdEft1.AmtCash = 0.00M // $0.00 cashout
axCsdEft1.DoTransaction()
//The Event 'TransactionEvent' is fired when the operation ends.

Description:
This method instructs the PINpad to perform a financial transaction. The TxnType property determines the type of transaction that is being started.The Pinpad will automatically logon (if required).

Properties to set:

Name	Description
AmtCash	The cashOut amount for the sale.
AmtPurchase	The sale amount.
CutReceipt	Set to true if the receipt should be cut when printed
DateExpiry	Set before calling DoTransaction if a customer's card details are manually entered by the operator.
DialogPosition	Positions the EFTPOS operator panel. For DialogPosition to be recognised, ensure that DialogX and DialogY properties are both set to zero.
DialogTitle	The title that is to appear on the EFTPOS Dialog. (Up to 32 characters)
DialogType	The type of dialog that you want to appear. Valid values are 'normal' and 'touchscreen'.
DialogX	Positions the EFTPOS operator panel at a precise screen location.
DialogY	Positions the EFTPOS operator panel at a precise screen location.
EnableTip	Set before calling DoTransaction. If EnableTip is True before calling DoTransaction, the customer receipt will have an area for a TIP to be entered.
EnableTopmost	If set to True, the EFTPOS Dialog will always be at the top of the window order.
Merchant	See definition
Pan	Card Number
ReceiptAutoPrint	Linkly printing
Track2	Track2 data on a card
PanSource	See definition
TxnRef	Unique number for each transaction
TxnType	type of transaction to perform (see definition)

Event that will fire: The event TransactionEvent is fired when this operation ends.

---

CsdReservedMethod1

Send Key request

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

Name	Description
DataField	Set the first byte of DataField to: '0' for the CANCEL key "1‟ for the YES key "2‟ for the NO key "3‟ for the AUTHORISE key The remaining bytes are either empty or contain up to 60 bytes of data that was input at the request of the pinpad in the DisplayEvent.

---

CsdReservedMethod2

Not Supported

---

CsdReservedMethod3

Not available in all pinpads. Check with Linkly before implementation.
Description:
This method invokes a generic request to the terminal to either:
1. Display text on the pinpad/pos display
2. Print a receipt on the NPT printer, or POS printer
3. Get a password from the terminal.
Properties to set:
TxnType indicates the request to perform:
"0" = Display
"1" = Print
"2" = Get Password
Normal Dialog properties for the Display Request:
CsdReservedString1 contains a structure representing the request parameters to the terminal. The structure is as follows:
For Display (TxnType = 0)

axCsdEft1.TxnType = "0";// Display on the pinpad and the pos
axCsdEft1.CsdReservedString1 = ("2").PadLeft(2, ' ');//Number of lines that will be shown on the pinpad and/or pos
axCsdEft1.CsdReservedString1 += ("30").PadLeft(3, ' ');// Display timeout
axCsdEft1.CsdReservedString1 += "1";//1 for displaying on the pinpad, 0 for not doing that
axCsdEft1.CsdReservedString1 += "1";//1 for displaying on the pos, 0 for not doing that
axCsdEft1.CsdReservedString1 += "1";//1 for enabling the pressing of the enter key on pinpad, 0 for not
axCsdEft1.CsdReservedString1 += "1";//1 for enabling the pressing of the clear key on pinpad, 0 for not
axCsdEft1.CsdReservedString1 += "      ";//This is padding for the rest of the keymasks, should equal 6
axCsdEft1.CsdReservedString1 += "11      ";//First 2 numbers are for displaying the pos ok key, and the pos cancel key. 0 means no show. Followed by 6 spaces that are for the rest of the keymasks
axCsdEft1.CsdReservedString1 += ("16").PadLeft(3, ' ');//For the line length, on pinpads won't be more than 20 but pos can show more, must be 3 bytes
axCsdEft1.CsdReservedString1 += ("Printing on").PadRight(20, ' ');
axCsdEft1.CsdReservedString1 += ("The POS!!!").PadRight(20, ' ');
axCsdEft1.CsdReservedString1 += ("Hello").PadRight(16, ' ');//print data, pad to meet format
axCsdEft1.CsdReservedString1 += ("New").PadRight(16, ' ');
axCsdEft1.CsdReservedMethod3();

Field	Bytes
# line of text to display	2
Timeout before returning to idle	3
Display Map options. Byte 0 = '1' to indicates that the Pinpad will display. Byte 1 = '1' to indicates that the POS will display	2
Pinpad Keymap: Byte 0 = '1' indicates ENTER key allowed. Byte 1 = '1' indicates CLEAR key allowed Byte 2-7 = Note used.	8
POS Keymap: Byte 0 = OK button displayed on POS display Byte 1 = CANCEL button on POS display Byte 2-7 = Not Used	8
Pinpad Line Length	3
POS Display Data (2 Lines at 20 char each line)	40
Pinpad Line Data (line length) char blocks	#lines * line length

For Print (TxnType = 1)

axCsdEft1.TxnType = "1";
axCsdEft1.CsdReservedString1 = ("5").PadLeft(3, ' '); //print 5 lines, pad to meet format
axCsdEft1.CsdReservedString1 += "10"; // print on NPT printer (internal pinpad printer)
axCsdEft1.CsdReservedString1 += ("10").PadLeft(3, ' '); // print each line at a length of 10 char, pad to meet format
axCsdEft1.CsdReservedString1 += ("Line1").PadRight(10, ' '); //print data, pad to meet format
axCsdEft1.CsdReservedString1 += ("Line2").PadRight(10, ' '); //print data, pad to meet format
axCsdEft1.CsdReservedString1 += ("Line3").PadRight(10, ' '); //print data, pad to meet format
axCsdEft1.CsdReservedString1 += ("Line4").PadRight(10, ' '); //print data, pad to meet format
axCsdEft1.CsdReservedString1 += ("Line5").PadRight(10, ' '); //print data, pad to meet format
//Print data is 50bytes long as #lines * line length is the format in this case #lines = 5 and line length = 10.
//5 * 10 = 50 for byteLength of printData.
axCsdEft1.CsdReservedMethod3();

Field	Bytes
# lines to print	3
Printer Bytemap: Byte 0 = '1' to print on NPT printer Byte 1 = Not supported	2
Line length of each print line	3
Print data. This is #lines * line length	#lines * line length

For get password(TxnType = 2)

axCsdEft1.txntype = "2";
axCsdEft1.CsdReservedString1 = "04"; //min length of 4;
axCsdEft1.CsdReservedString1 += "06"; //max length of 6;
axCsdEft1.CsdReservedString1 += "030"; //30 second timeout
axCsdEft1.CsdReservedString1 += "01" // Display "PASSWORD"
axCsdEft1.CsdReservedMethod3();

Field	Bytes
Minimum length of password	2
Maximum length of password	2
Timeout for prompt	3
Type of display: "01" = "PASSWORD" "02" = "FUNCTION" "03" = "OLD PASSWORD" "04" = "NEW PASSWORD" "05" = "VERIFY PASSWORD"	2

Event that will fire:
The event CsdReservedMethod3Event is fired when this operation ends. If the TxnType = "2", the following properties will be set:
DataField Property contains the following:
Length of data (2)
Password (data length)

---

Events

CardSwipeEvent

string response = axCsdEft1.ResponseCode; //store the result of the cardSwipe
string responseTxt = axCsdEft1.ResponseText; // store the message associated with the ResponseCode

Fired upon completion of a DoCardSwipe request.
Applicable properties:

Return Property	Description
Response Code	A 2 character code returned by the bank indicating the result of the transaction.
Response Text	A textual description of the bank response code (up to 20 characters).

---

ChequeVerifyEvent

string response = axCsdEft1.ResponseCode; //store the result of the ChequeVerify
string responseTxt = axCsdEft1.ResponseText; // store the message associated with the ResponseCode
bool success = axCsdEft1.Success; //store the boolean value for the result of the ChequeVerify

Fired upon completion of a DoChequeVerify request.
Applicable properties:

Return Property	Description
Success	Indicates success or failure of relevant event/method call.
Response Code	A 2 character code returned by the bank indicating the result of the transaction.
Response Text	A textual description of the bank response code (up to 20 characters).

---

ConfigMerchantEvent

string response = axCsdEft1.ResponseCode; //store the result of the ConfigMerchant
string responseTxt = axCsdEft1.ResponseText; // store the message associated with the ResponseCode
bool success = axCsdEft1.Success; //store the boolean value for the result of the ConfigMerchant

Fired upon completion of a DoConfigMerchant request.
Applicable properties:

Return Property	Description
Success	Indicates success or failure of relevant event/method call.
Response Code	A 2 character code returned by the bank indicating the result of the transaction.
Response Text	A textual description of the bank response code (up to 20 characters).

---

ControlPanelEvent

string response = axCsdEft1.ResponseCode; //store the result of the DoControlPanel Call
string responseTxt = axCsdEft1.ResponseText; // store the message associated with the ResponseCode
bool success = axCsdEft1.Success; //store the boolean value for the result of the DoControlPanel Call

Fired upon completion of a DoControlPanel request (when the control panel is dismissed).
Applicable properties:

Return Property	Description
Success	Indicates success or failure of relevant event/method call.
Response Code	A 2 character code returned by the bank indicating the result of the transaction.
Response Text	A textual description of the bank response code (up to 20 characters).

---

CsdReservedEvent1

Not supported Fired upon completion of a CsdReservedMethod1 request (when the control panel is dismissed).
Applicable properties:
See CsdReservedMethod1

---

CsdReservedEvent2

Not Supported Fired upon completion of a CsdReservedMethod2 request (when the control panel is dismissed).
Applicable properties:
See CsdReservedMethod2

---

CsdReservedEvent3

Not Supported Fired upon completion of a CsdReservedMethod3 request (when the control panel is dismissed).
Applicable properties:
See CsdReservedMethod3

---

DisplayEvent

Fired when the operator display is updated. Use this event to update any additional displays such as a customer display with the current display text.
Applicable properties:
- DataField: This field contains multiple lines of text to display (usually 2 lines of 20 characters each).
- CsdReservedString1: This property contains a byte-map representation of what keys are available to be pressed when this event occurs.
- "0" = disabled
- "1" = enabled
If the Input Data Field button is enabled, the pinpad is expecting up to 16 characters of data to be input before a button press.
The last byte indicates the Graphic Code that the display will use to play the AVI.
Format of Datafield:

Field	Description
Byte 0	CANCEL Key
Byte 1	ACCEPT Key
Byte 2	DECLINE Key
Byte 3	Authorise Key
Byte 4	"Input Data Field" Enabled
Byte 5	OK Key
Byte 6, 7	Not Defined
Byte 8	Graphics Code that the display will use

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

---

DisplaySettlementEvent

string response = axCsdEft1.ResponseCode; //store the result of the DoDisplaySettlement Call
string responseTxt = axCsdEft1.ResponseText; // store the message associated with the ResponseCode
bool success = axCsdEft1.Success; //store the boolean value for the result of the DoDisplaySettlement Call

Fired upon completion of a DoDisplaySettlement request (when the settlement panel is dismissed).
Applicable properties:

Return Property	Description
Success	Indicates success or failure of relevant event/method call.
Response Code	A 2 character code returned by the bank indicating the result of the transaction.
Response Text	A textual description of the bank response code (up to 20 characters).

---

DisplayStatusEvent

string response = axCsdEft1.ResponseCode; //store the result of the DoDisplayStatus Call
string responseTxt = axCsdEft1.ResponseText; // store the message associated with the ResponseCode
bool success = axCsdEft1.Success; //store the boolean value for the result of the DoDisplayStatus Call

Fired upon completion of a DoDisplayStatus request (when the status panel is dismissed).
Applicable properties:

Return Property	Description
Success	Indicates success or failure of relevant event/method call.
Response Code	A 2 character code returned by the bank indicating the result of the transaction.
Response Text	A textual description of the bank response code (up to 20 characters).

---

GetLastReceiptEvent

bool success = axCsdEft1.Success; //store the boolean value for the result of the DoGetLastReceipt Call
int merchant = axCsdEft1.Merchant; //store the merchant value from the last receipt
int stan = axCsdEft1.Stan; //store the stan of the last receipt
string txnref = axCsdEft1.TxnRef //store the transaction reference number for the last receipt
string receipt = axCsdEft1.Receipt // store actual last receipt printed 

Fired upon completion of a DoGetLastReceipt request.
Applicable properties:

Return Property	Description
Success	Indicates success or failure of relevant event/method call.
Merchant	See Definition
Stan	The Systems Trace Audit Number of the last transaction performed. (0-999999).
TxnRef	Application supplied reference number up to 16 characters in length.
Receipt	Formatted EFTPOS receipt information (Up to 2048 characters).

---

GetLastTransactionEvent

Fired upon completion of a DoGetLastTransaction request.
The properties returned by this event are the same as for TransactionEvent except for Success, which indicates the result of the call to DoGetLastTransaction, not the result of the retrieved transaction. The property LastTxnSuccess indicates the success of the retrieved txn.
Applicable properties:

Return Property	Description
AccountType	The type of account used for a given transaction.
AmtCash	The amount of cash out for the transaction
AmtTip	Amount of tip given (if any).
AmtPurchase	The purchase amount for the transaction
AuthCode	Authorisation code.
Caid	Card Acceptor ID, also known as the "Merchant" ID.
Catid	Card Acceptor Terminal ID.
CardType	The card type used for the transaction as described by the bank.
DateExpiry	The Card Expiry Date
DateSettlement	Contains the settlement date for the transaction in 'DDMMYYYY' format.
Date	Date of transaction
LastTxnSuccess	Set to True if the last transaction was successful.
Merchant	See Definition
MessageType	See Definition
Pan	Primary Account Number. Loaded with the customer card number
Stan	The Systems Trace Audit Number of the last transaction performed. (0-999999).
Success	Indicates success or failure of relevant event/method call.
Time	Transaction time returned by the acquirer. 'HHMMSS' format.
Track2	Contents of magnetic card track 2.
TxnRef	Application supplied reference number up to 16 characters in length.
TxnType	See Definition
ResponseCode	A 2 character code returned by the bank indicating the result of the transaction.
ResponseText	A textual description of the bank response code (up to 20 characters).

---

InProgress(Boolean InProgress)

Fired upon start and completion of EFT processing. The parameter indicates a 'busy' status.

---

InvokeAppletEvent

Fired upon completion of a DoInvokeApplet request. Note: not currently implemented.

---

JournalViewerEvent

Fired upon completion of a DoJournalViewer request (when the journal viewer is dismissed).

---

KeyDownEvent(long KeyCode, long KeyData)

Indicates that a key has been pressed by the operator while the EFTPOS Dialog is displayed. Two parameters allow the application to determine which key or key combination has been pressed. The POS application could use this to allow POS-specific keys to be handled while the EFTPOS Dialog is active.
KeyCode:
Specifies the virtual key-code of the key being pressed. The virtual key-code is the device-independent value that identifies the purpose of a keystroke as interpreted by the Windows device driver.
KeyData:
Specifies the repeat count, scan code, extended-key flag, context code, previous key state flag and transition-state flag as shown in the following table:

Value	Description
0-15	Specifies the repeat count. The value is the number of times the keystroke is repeated as a result of the user holding down the key.
16-23	Specifies the scan code. The value depends on the original equipment manufacturer (OEM)
24	Specifies whether the key is an extended key, such as the right-handed ALT and CTRL keys that appear on enhanced 101 or 102-key keyboards. The value is a 1 if it is an extended key,otherwise it is 0.
25-28	Reserved - Do not use.
29	Specifies the context code. The value is 1 if the ALT key is down while the key is pressed. It is 0if the WM_SYSKEYDOWN message is posted to the active window because no window has the keyboard focus.
30	Specifies the previous key state. The value is 1 if the key is down before the message is sent,or 0 if the key is up.
31	Specifies the transition state. The value is always 0 for a WM_SYSKEYDOWN message.

---

LogonEvent

bool success = axCsdEft1.Success; //store the boolean value for the result of the DoLogon Call
int stan = axCsdEft1.Stan; //store the stan of the DoLogon
string caid = axCsdEft1.Caid; //Store the Merchant ID from the DoLogon call
string catid = axCsdEft1.Catid; //Store the Terminal ID from the DoLogon Call
string response = axCsdEft1.ResponseCode; //store the result of the DoLogon
string responseTxt = axCsdEft1.ResponseText; // store the message associated with the ResponseCode
string date = axCsdEft1.Date; // store the date of the Logon
string pinpadversion = axCsdEft1.PinPadVersion; //store the pinpad version number
string time = axCsdEft1.Time; //store the time of the DoLogon call

Description:
Fired upon completion of a DoLogon request.
The following properties will be set by the event.

Return Property	Description
Success	Indicates success or failure of relevant event/method call.
CAID	Card Acceptor ID, also known as the "Merchant" ID.
CATID	Card Acceptor Terminal ID.
Date	Date of transaction
PinPadVersion	The PINpad software name and version (Up to 16 characters).
STAN	The Systems Trace Audit Number of the last transaction performed. (0-999999).
Time	Transaction time returned by the acquirer. 'HHMMSS' format.
ResponseCode	A 2 character code returned by the bank indicating the result of the transaction.
ResponseText	A textual description of the bank response code (up to 20 characters).

---

PrintReceiptEvent

Description
This event is fired to indicate that an EFTPOS receipt is either available to print, or is about to be sent. If the ReceiptType is not an "R", then the event is a warning that the EFTPOS system is about to print. The application may use this event to print a header that will appear before the EFTPOS receipt. If the ReceiptAutoPrint property was set to FALSE (recommended!!!), then the receipt event will contain the actual receipt data in the Receipt property. The Receipttype will be "R".
Possible values for ReceiptType are:

Value	Description
"R"	Receipt present for POS to print. The receipt is a string contained in the Receipt property.
"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
"G"	The system wants the POS to print a logo. The next "R" receipt will have the actual filename that the POS should print.

---

QueryCardEvent

Fired upon completion of a DoQueryCard request.
Applicable properties:
DataField is set if extended card info is returned.

Value	Description
Success	Indicates success or failure of relevant event/method call.
Track1	Contents of magnetic card track 1 or 3, if either is read by the PINpad.
Track2	Contents of magnetic card track 2.
AccountType	Settlement receipt about to be printed
ResponseCode	A 2 character code returned by the bank indicating the result of the transaction.
ResponseText	A textual description of the bank response code (up to 20 characters).

---

ReprintReceiptEvent

bool success = axCsdEft1.Success; //store the boolean value for the result of the DoReprintReceipt Call
string responsecode = axCsdEft1.ResponseCode; //store the response code(result) of the DoReprintReceipt Call
string responseTxt = axCsdEft1.ResponseText; // store the response text associated with the response code
string receipt = axCsdEft1.Receipt; // The actual receipt from the DoReprintReceipt call

Fired upon completion of a DoReprintReceipt request.
Applicable properties:

Return Property	Description
Success	Indicates success or failure of relevant event/method call.
Receipt	Formatted EFTPOS receipt information (Up to 2048 characters).
ResponseCode	A 2 character code returned by the bank indicating the result of the transaction.
ResponseText	A textual description of the bank response code (up to 20 characters).

---

RequestCommsEvent(String Port, Boolean Requested)

Not used in Australia.
Fired when the EFT Server requires access to a COM Port for dial-up EFTPOS operation. This event will only occur for clients with an EFT Server process resident on the same PC. The event is intended for applications that share a modem with the EFT Server. When the application receives this event with the "Requested" parameter set to True, it must immediately release (close) the specified COM Port within 2 seconds. When the event is fired with the "Requested" parameter set to False, EFTPOS has finished with the COM Port for the current operation and the application may attempt to access the port. The parameter Port is a string describing the port being requested.
eg "COM1:".

---

SelfTestEvent

Fired upon completion of a DoSelfTest request.
Applicable properties:

Value	Description
Success	Indicates success or failure of relevant event/method call.
DataField	Contains an array of possible settlement values for this acquirer. The array is a 16 byte array with a "1" indicating that the option is supported. Options are: [0] Settlement [1] Pre-Settlement [2] Last Settlement [3] Sub-Totals [4] Shift Totals [5] Txn Listing [6] Summary Totals.

---

SetFocusEvent

Not Supported

---

SettlementEvent

Fired upon completion of a DoSettlement request.
Applicable properties:

Value	Description
Success	Indicates success or failure of relevant event/method call.
SettleCardCount	The number of card settlement records contained within the property SettleCardData.
SettleCardData
TotalsData	A totals record containing the locally stored terminal totals.
ResponseCode	A 2 character code returned by the bank indicating the result of the transaction.
ResponseText	A textual description of the bank response code (up to 20 characters).

---

SettlementCutoverEvent

Fired upon completion of a DoSettlementCutover request.
Applicable properties:

Value	Description
Success	Indicates success or failure of relevant event/method call.
SettleCardCount	The number of card settlement records contained within the property SettleCardData.
SettleCardData
TotalsData	A totals record containing the locally stored terminal totals.
ResponseCode	A 2 character code returned by the bank indicating the result of the transaction.
ResponseText	A textual description of the bank response code (up to 20 characters).

---

SettlementEnquiryEvent (NOT SUPPORTED)

Fired upon completion of a DoSettlementEnquiry request.
Applicable properties:

Value	Description
Success	Indicates success or failure of relevant event/method call.
SettleCardCount	The number of card settlement records contained within the property SettleCardData.
SettleCardData
TotalsData	A totals record containing the locally stored terminal totals.
ResponseCode	A 2 character code returned by the bank indicating the result of the transaction.
ResponseText	A textual description of the bank response code (up to 20 characters).

---

SetupPinPadEvent

bool success = axCsdEft1.Success; //store the boolean value for the result of the DoSetupPinPad Call
string responsecode = axCsdEft1.ResponseCode; //store the response code(result) of the DoSetupPinPad Call
string responseTxt = axCsdEft1.ResponseText; // store the response text associated with the response code

Fired upon completion of a DoSetupPinPad request (when the pinpad setup panel is dismissed).
Applicable properties:

Value	Description
Success	Indicates success or failure of relevant event/method call.
ResponseCode	A 2 character code returned by the bank indicating the result of the transaction.
ResponseText	A textual description of the bank response code (up to 20 characters).

SoftwareActivateEvent

bool success = axCsdEft1.Success; //store the boolean value for the result of the DoSoftwareActivate Call
string responsecode = axCsdEft1.ResponseCode; //store the response code(result) of the DoSoftwareActivate Call
string responseTxt = axCsdEft1.ResponseText; // store the response text associated with the response code

Fired upon completion of a DoSoftwareActivate request.
Applicable properties:

Value	Description
Success	Indicates success or failure of relevant event/method call.
ResponseCode	A 2 character code returned by the bank indicating the result of the transaction.
ResponseText	A textual description of the bank response code (up to 20 characters).

Note: Not used - reserved for future use.

---

SoftwareDownloadEvent

bool success = axCsdEft1.Success; //store the boolean value for the result of the DoSoftwareDownload Call
string responsecode = axCsdEft1.ResponseCode; //store the response code(result) of the DoSoftwareDownload Call
string responseTxt = axCsdEft1.ResponseText; // store the response text associated with the response code

Fired upon completion of a DoSoftwareDownload request.
Applicable properties:

Value	Description
Success	Indicates success or failure of relevant event/method call.
ResponseCode	A 2 character code returned by the bank indicating the result of the transaction.
ResponseText	A textual description of the bank response code (up to 20 characters).

Note: Not used - reserved for future use.

---

StatusEvent

Fired upon completion of a DoStatus request.
Applicable properties:
DataField will contain specific information depending upon which Messagetype is returned. See DataField definition.

Value	Description
Success	Indicates success or failure of relevant event/method call.
Aiic	Acquiring Institution Identification Code.
Caid	Card Acceptor ID, also known as the "Merchant" ID.
Catid	Card Acceptor Terminal ID.
ConfigLocked	See Definition
LoggedOn	Set to True if the PINpad is in a logged on state, False if a logon is required.
Merchant	Indicates the active merchant.
Nii	EFTPOS Network International Identifier.
Timeout	EFTPOS transaction timeout.
PinPadSerialNumber	The hardware ID or Serial Number of the attached PINpad.
PinPadVersion	The PINpad software name and version (Up to 16 characters).
MessageType	See Definition
ResponseCode	A 2 character code returned by the bank indicating the result of the transaction.
ResponseText	A textual description of the bank response code (up to 20 characters).

The following properties will be returned if the status request was a Pre-Swipe Status:

Value	Description
Success	Indicates success or failure of relevant event/method call.(Always TRUE)
AccountType	See Definition
AmtCash	The amount of cash out for the transaction.
AmtTip	Amount of tip given (if any).
AmtPurchase	The purchase amount for the transaction.
Pan	Primary Account Number. Loaded with the customer card number
Track2	Contents of magnetic card track 2.
Catid	Card Acceptor Terminal ID.
DataField	See definition (This has all data from the card data on that the pinpad sends back to the system)
ResponseCode	A 2 character code returned by the bank indicating the result of the transaction.
ResponseText	A textual description of the bank response code (up to 20 characters).

---

TransactionEvent

Fired upon completion of a DoTransaction request.

Applicable properties:

Return Property	Description
AccountType	The type of account used for a given transaction.
AmtCash	The amount of cash out for the transaction
AmtTip	Amount of tip given (if any).
AmtPurchase	The purchase amount for the transaction
AuthCode	Authorisation code.
Caid	Card Acceptor ID, also known as the "Merchant" ID.
Catid	Card Acceptor Terminal ID.
CardType	The card type used for the transaction as described by the bank.
DateExpiry	The Card Expiry Date
DateSettlement	Contains the settlement date for the transaction in 'DDMMYYYY' format.
Date	Date of transaction
LastTxnSuccess	Set to True if the last transaction was successful.
Merchant	See Definition
MessageType	See Definition
Pan	Primary Account Number. Loaded with the customer card number
Stan	The Systems Trace Audit Number of the last transaction performed. (0-999999).
Success	Indicates success or failure of relevant event/method call.
Time	Transaction time returned by the acquirer. 'HHMMSS' format.
Track2	Contents of magnetic card track 2.
TxnRef	Application supplied reference number up to 16 characters in length.
TxnType	See Definition
ResponseCode	A 2 character code returned by the bank indicating the result of the transaction.
ResponseText	A textual description of the bank response code (up to 20 characters).
RRN	Retrieval Reference Number to uniquely identify a card transaction

CsdReserverdBool1: This field indicates if the transaction was performed offline or online. True is online, False is offline.

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.
Event results for this property:

Returned Property	Description
From a 'TransactionEvent'	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 'QueryCardEvent'	It will be "0" = Savings, "2" = Cheque, "3" = Credit

---

Aiic

Acquiring Institution Identification Code.
Returned by StatusEvent.
Applies to DoConfigMerchant.
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 DoTransaction.

---

AmtCreditLimit

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

---

AmtPurchase

The purchase amount for the transaction.
Applies to DoTransaction.

---

AmtTip

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

---

AuthCode

Authorisation code. Returned by TransactionEvent if the EFTPOS Acquirer returned the AuthCode field. Also required as input to DoTransaction when a Completion is being performed.
Returned by ChequeVerifyEvent if the acquirer returned a reference.
Returned by TransactionEvent, ChequeVerifyEvent.
Applies to DoTransaction.

---

Caid

Card Acceptor ID, also known as the "Merchant" ID.
Returned by TransactionEvent, LogonEvent, StatusEvent.
Applies to DoConfigMerchant.

---

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 TransactionEvent, LogonEvent, StatusEvent.
Applies to DoConfigMerchant.

---

ChqAccount

Cheque Account Number.
Applies to DoChequeVerify.
NOT Used

---

ChqBranch

Cheque Branch Number.
Applies to DoChequeVerify.
NOT Used

---

ChqSerialNumber

Cheque Serial Number.
Applies to DoChequeVerify.
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

---

csdReservedBool1

This is a reserved field that is used when new functionality is added to the Linkly system.
Response to a transaction. This field indicates if the transaction was performed online or offline. True is online, False is offline.

---

csdReservedString1

A Reserved String for additional functionality. This is used in the following ways:

Return Property	Description
DisplayEvent	This property contains the bytemap of the keys available. The bytemap is an 8 byte field. The 9th byte is the graphic code that was chosen.
DoTransaction	When using the Ordering TxnType for a transaction, this property contains the item that is to be ordered. Current items are: SMT-xx Statement. (xx is the number of statements to order) CHQ-xx Cheque book (xx is the number of cheque books) DEP-xx Deposit book (xx is the number of deposit books) You can order multiple items (maximum of 4) by comma separating each item. Eg SMT-01,CHQ-02,DEP-01

---

csdReservedString2

A Reserved String for additional functionality. This is used in the following ways:
This property defines which application the EFT-Client is to send the transaction details to.
If the property is empty, the default EFTPOS application will be used.
Other values are:

Value	Description
AGENCY	Use the Agency application within the terminal.
EFTPOS	Use the EFTPOS application (default)

---

CutReceipt

Set to True if the receipt should be cut by the printer after the receipt is printed.
Applies to DoTransaction, DoReprintReceipt, DoControlPanel and DoDisplaySettlement.

---

DataField

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

For the QueryCard Event
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 TransactionEvent, this field contains the TO/FROM data when a Funds Transfer is performed.

For the method csdReservedMethod1, this property contains the key to be pressed.

For the LogonEvent, this property contains a byte array of values: Currently assigned bytes are byte 0 = EFTPOS txns allowed, byte 1 = Agency txns allowed.
For the SelfTestEvent, this field will contain the array of settlement options that are available to the terminal.
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 StatusEvent, this field will contain the Extra Status information which is used in PX328 Linkly systems and onward.
For a DoTransaction 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 TransactionEvent, LogonEvent.

---

DateExpiry

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

---

DateSettlement

Contains the settlement date for the transaction in 'DDMMYYYY' format.
Used as input to DoSettlement 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 TransactionEvent and SettlementEvent
Applies to DoSettlement.

---

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 DoTransaction, DoChequeVerify, DoLogon, DoSettlement

---

DialogTitle

The title that is to appear on the EFTPOS Dialog. (Up to 32 characters)
Applies to DoTransaction, DoChequeVerify, DoLogon, DoSettlement

---

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 DoTransaction, DoChequeVerify, DoLogon, DoSettlement

---

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 DoTransaction, DoChequeVerify, DoLogon, DoSettlement

---

EftPosNetwork

Indicates the network to which the PINpad is connected.
Returned by StatusEvent.

---

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 DoTransaction. If EnableTip is True before calling DoTransaction, 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 DoTransaction method (with TxnType = "T").
Applies to DoTransaction.
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 DoTransaction.
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 toDoTransaction, DoChequeVerify, DoLogon, DoSettlement
Note: It is not advisable to use this property, as the POS may require bank certification.

---

FileName

The name of the file to download.
Applies to DoSoftwareDownload.
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 GetLastTransactionEvent.

---

LicenseId

The unique license identification string for the PINpad.
Returned by StatusEvent.
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 DoLogon to explicitly logon a PINpad as auto-logons are performed.
Returned by StatusEvent.

---

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 DoTransaction, DoChequeVerify, DoLogon, DoSettlement, and DoStatus.
Note: Not used - Reserved for future use.

---

MessageType

A property to represent:
- The Message type returned by TransactionEvent.
- The Subcode to select in a DoStatus request.
- The resulting subcode in a StatusEvent

---

Nii

EFTPOS Network International Identifier.
Returned by StatusEvent.
Applies to DoConfigMerchant.
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 TransactionEvent (return format is acquirer dependent any may be in short 6...3 format).
Applies to DoTransaction.

---

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 DoTransaction and DoChequeVerify.

---

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 DoTransaction, DoChequeVerify, DoLogon, DoSettlement
Note: Not supported by all acquirers.

---

PinPadSerialNumber

The hardware ID or Serial Number of the attached PINpad.
Returned by StatusEvent.

---

PinPadVersion

The PINpad software name and version (Up to 16 characters).
Returned by StatusEvent, LogonEvent.

---

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.

---

Ready

Indicates if the EFTPOS subsystem has been successfully initialised and is ready to accept commands.
Note that a True status for this property does not guarantee that any subsequent method call will be successfully executed, but can be used to avoid unnecessary delays if the EFTPOS subsystem has determined that EFTPOS is not currently available (PINpad offline or processing a reversal, Client not running, etc).

---

Receipt

Formatted EFTPOS receipt information (Up to 2048 characters).
Returned by PrintReceiptEvent("R"), GetLastReceiptEvent.

---

ReceiptAutoPrint

If set to True (the default), the EFTPOS subsystem will automatically handle EFTPOS receipt printing as part of the transaction operation initiated by DoTransaction. Power-fail recovery and reprinting of receipts if necessary is also handled by EFTPOS in this case. If the application is to assume responsibility for receipt printing of EFTPOS receipts, set ReceiptAutoPrint to False before calling DoTransaction. The receipt will not be automatically printed, but will instead be returned in the Receipt property for a PrintReceiptEvent("R").
Applies to DoTransaction, DoLogon, DoSettlement DoControlPanel and DoDisplaySettlement.
Note: Setting the ReceiptAutoPrint flag to False is strongly encouraged.

---

ResetTotals

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

---

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

---

SettleCardCount

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

---

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

Returned by SettlementEvent.

---

Stan

The Systems Trace Audit Number of the last transaction performed. (0-999999).
Returned by TransactionEvent, GetLastTransactionEvent, LogonEvent.

---

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 TransactionEvent, LogonEvent.

---

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 StatusEvent.
Applies to DoConfigMerchant.
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 DoSettlement 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.

Returned by SettlementEvent.

---

Track1

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

---

TotalPurchaseCount

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

---

Track2

Contents of magnetic card track 2. This property should be loaded by the application prior to calling DoTransaction if the customer card is read by an application Magnetic Stripe Reader.
DoQueryCard 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 TransactionEvent, QueryCardEvent.
Applies to DoTransaction.

---

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 DoTransaction.
Returned by TransactionEvent, GetLastTransactionEvent.
Applies to DoTransaction.

---

TxnType

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

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

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 TransactionEvent and SettlementEvent.
Applies to DoTransaction and DoSettlement.
Note: Not all TxnTypes are supported by all acquirers.

---

VersionMajor

Major version number for the ActiveX control.

---

VersionMinor

Minor version number for the ActiveX control.

---

VersionRevision

Revision level for the ActiveX control.

---

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"
• CsdReservedString2 "APP_1"

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"
• CsdReservedString2 "APP_1"

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"
• CsdReservedString2 "APP_1"

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 CsdReservedMethod1 (Send Key Request) as detailed below:

Send Key Request

Name	Description
DataField	Set the first byte of DataField to: '0' for the CANCEL key "1‟ for the YES key "2‟ for the NO key "3‟ for the AUTHORISE key The remaining bytes up to a length of 60 contain entry data collected by POS (the barcode)

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
Method	DoTransaction
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
PosProductId	Set to 'TXN_TAG_DATA'
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(64)	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 responsibility for Token Management.

Request:

Field	Description
Command Method	Call DoTransaction() to start transaction
Merchant	Set to '65' to indicate a AfterPay transaction
TxnType	Set to 'A' to indicate a Activation
csdReservedString2	Set to 'APP_1'
PurchaseAnalysisData
DID - Optional	Device name as assigned by AfterPay
KEY - Optional	Onetime secret as generated by AfterPay

Response:

Field	Description
Success Flag	'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.

Field	Description
Command Method	Call DoTransaction() to start transaction
Merchant	Set to '65' to indicate a AfterPay transaction
TxnType	Set to 'X' to indicate a Create Token
csdReservedString2	Set to 'APP_1'
PurchaseAnalysisData
DID - Optional	Device Id as returned in Activation
KEY - Optional	Token creation key as returned in Activation

Response:

Field	Description
Success Flag	'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 Method	Call DoTransaction() to start transaction
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
PAN Source	Barcode capture method
csdReservedString2	Set to 'APP_1'
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 Flag	'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 (Purchase) transactions; the Response Code to indicate this is 'X0'.

Request:

Field	Description
Command Method	Call DoTransaction() to start transaction
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
PAN Source	Barcode capture method
Currency Code	(Optional) ISO Currency code (e.g. AUD)
TxnRef	Unique transaction reference number
csdReservedString2	Set to 'APP_1'
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 Flag	'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
Command Method	Call DoTransaction() to start transaction
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
Currency Code	(Optional) ISO Currency code (e.g. AUD)
TxnRef	Unique transaction reference number
csdReservedString2	Set to 'APP_1'
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 Flag	'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
Command Method	Call DoTransaction() to start transaction
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
Currency Code	(Optional) ISO Currency code (e.g. AUD)
csdReservedString2	Set to 'APP_1'
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 Flag	'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 three 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.
The use of this API 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 dependent 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.

Methods

Status Query

This transaction (see DoTransaction) 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
Method	Call DoTransaction for a transaction request
csdReservedString2	Set to 'APP_1' 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 Flag	'1' if transaction was successful
Response Code	'00' if the transaction was approved
Response Text	Response message
Purchase Amount	(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 (see DoTransaction) 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 canceled 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
Method	Call DoTransaction for a transaction request
csdReservedString2	Set to 'APP_1' to indicate an extension request
Merchant	Set to '66' to indicate an Alipay request
Txn Type	Set to 'P' to indicate a Purchase
Amount Purchase	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 Flag	'1' if transaction was successful
Response Code	'00' if the transaction was approved
Response Text	Response message
Purchase Amount	(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 (see DoTransaction) 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
Method	Call DoTransaction for a transaction request
csdReservedString2	Set to 'APP_1' to indicate an extension request
Merchant	Set to '66' to indicate an Alipay request
Txn Type	Set to 'R' to indicate a Refund
Amount Purchase	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 Flag	'1' if transaction was successful
Response Code	'00' if the transaction was approved
Response Text	Response message
Purchase Amount	(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
Method	Call DoTransaction for a transaction request
csdReservedString2	Set to 'APP_1' 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 Flag	'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 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.

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 Blackhawk 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 Method	Call DoTransaction() to start transaction
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
PAN Source	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
csdReservedString2	Set to 'APP_1'
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 Flag	'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 cancellation 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 Method	Call DoTransaction() to start transaction
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
PAN Source	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
csdReservedString2	Set to 'APP_1'
PurchaseAnalysisData
UPC	Card UPC. Required if card information is being sent by the POS.

Response:

Field	Description
Success Flag	'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 three 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. Additionally 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 Method	Call DoTransaction() to start transaction
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
PAN Source	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
csdReservedString2	Set to 'APP_1'
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 Flag	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 Method	Call DoTransaction() to start transaction
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
PAN Source	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
csdReservedString2	Set to 'APP_1'
PurchaseAnalysisData
PPD	Set to 'EPY' for Epay processing
PID	Epay Product Id
UPC	Card UPC (aka EAN) (Optional)

Response:

Field	Description
Success Flag	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 Method	Call DoTransaction() to start transaction
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
PAN Source	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
csdReservedString2	Set to 'APP_1'
PurchaseAnalysisData
PPD	Set to 'EPY' for Epay processing
PID	Epay Product Id
UPC	Card UPC (aka EAN) (Optional)

Response:

Field	Description
Success Flag	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 Method	Call DoTransaction() to start transaction
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
PAN Source	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
csdReservedString2	Set to 'APP_1'
PurchaseAnalysisData
PPD	Set to 'EPY' for Epay processing
PID	Epay Product Id
UPC	Card UPC (aka EAN) (Optional)

Response:

Field	Description
Success Flag	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 Method	Call DoTransaction() to start transaction
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
csdReservedString2	Set to 'APP_1'
PurchaseAnalysisData
PPD	Set to 'EPY' for Epay processing
PID	Epay Product Id
PHN	Phone Number

Response:

Field	Description
Success Flag	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 Method	Call DoTransaction() to start transaction
Merchant	Set to '63' to indicate a Epay gift card transaction
TxnType	Set to 'X' to indicate a Reprint
TxnRef	Unique transaction reference number
csdReservedString2	Set to 'APP_1'
PurchaseAnalysisData
PPD	Set to 'EPY' for Epay processing
REF	Epay transaction reference (optional)
RRN	Original transaction Txn Ref Number (optional)

Response:

Field	Description
Success Flag	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 Method	Call DoTransaction() to start transaction
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
PAN Source	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
csdReservedString2	Set to 'APP_1'
PurchaseAnalysisData
PPD	Set to 'EPY' for Epay processing
REF	Epay transaction reference (optional)
RRN	Original transaction Txn Ref Number (optional)

Response:

Field	Description
Success Flag	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 three 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 Method	Call DoTransaction() 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
csdReservedString2	Set to 'APP_1'
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 Method	Call DoTransaction() 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
csdReservedString2	Set to 'APP_1'
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 Method	Call DoTransaction() 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
csdReservedString2	Set to 'APP_1'
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 Method	Call DoTransaction() 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
csdReservedString2	Set to 'APP_1'
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 Method	Call DoTransaction() 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
csdReservedString2	Set to 'APP_1'
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
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 Linkly 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 Method	Call DoTransaction() to start transaction
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
PAN Source	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
csdReservedString2	Set to 'APP_1'
Command Method	Call DoTransaction() to start transaction
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 Flag	'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 Method	Call DoTransaction() to start transaction
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
PAN Source	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
csdReservedString2	Set to 'APP_1'
Command Method	Call DoTransaction() to start transaction
PurchaseAnalysisData
PAN	Alternative location for Card PAN (allows PAN length > 20)

Response:

Field	Description
Success Flag	'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 Method	Call DoTransaction() to start transaction
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
PAN Source	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
csdReservedString2	Set to 'APP_1'
PurchaseAnalysisData
PAN	Alternative location for Card PAN (allows PAN length > 20)

Response:

Field	Description
Success Flag	'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 Method	Call DoTransaction() to start transaction
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
PAN Source	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
csdReservedString2	Set to 'APP_1'
PurchaseAnalysisData
PAN	Alternative location for Card PAN (allows PAN length > 20)

Response:

Field	Description
Success Flag	'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 Method	Call DoTransaction() to start transaction
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
PAN Source	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
csdReservedString2	Set to 'APP_1'
PurchaseAnalysisData
PAN	Alternative location for Card PAN (allows PAN length > 20)

Response:

Field	Description
Success Flag	'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 Method	Call DoTransaction() to start transaction
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
PAN Source	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
csdReservedString2	Set to 'APP_1'
PurchaseAnalysisData
PAN	Alternative location for Card PAN (allows PAN length > 20)

Response:

Field	Description
Success Flag	'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 three 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 dependent 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 Method	Call DoTransaction() to start transaction
Merchant	Set to '67' to indicate a Humm transaction
TxnType	Set to 'P' to indicate aPurchase
Amount Purchase	Set to the amount to pay with Humm
TxnRef	Unique Transaction reference number
csdReservedString2	Set to 'APP_1'
PAN	Humm barcode value
PAN Source	Barcode capture method
PurchaseAnalysisData
OPR	(optional) Operator ID who performed the sale
AMT	Total Purchase Amount (in cents)

Response:

Field	Description
Success Flag	'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 Method	Call DoTransaction() to start transaction
Merchant	Set to '67' to indicate a Humm transaction
TxnType	Set to 'R' to indicate a Refund
Amount Purchase	Set to the amount to refund with Humm
TxnRef	Unique Transaction reference number
csdReservedString2	Set to 'APP_1'
PurchaseAnalysisData
REF	Reference (Purchase Id) of the purchase to refund
OPR	(Optional) Operator ID who performed the refund

Response:

Field	Description
Success Flag	'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 Method	Call DoTransaction() to start transaction
Merchant	Set to '67' to indicate a Humm transaction
TxnType	Set to 'K' to indicate an Invite
Amount Purchase	Set to the amount to invite for with Humm
TxnRef	Unique Transaction reference number
csdReservedString2	Set to 'APP_1'
PurchaseAnalysisData
PHN	The customer's phone number
OPR	(Optional) Operator ID who performed the invite

Response:

Field	Description
Success Flag	'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 Method	Call DoTransaction() to start transaction
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
PAN Source	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
csdReservedString2	Set to 'APP_1'
PurchaseAnalysisData
UPC	Card UPC. (Optional)

Response:

Field	Description
Success Flag	'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 Method	Call DoTransaction() to start transaction
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
PAN Source	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
csdReservedString2	Set to 'APP_1'
PurchaseAnalysisData
UPC	Card UPC. (Optional)

Response:

Field	Description
Success Flag	'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 Method	Call DoTransaction() to start transaction
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
csdReservedString2	Set to 'APP_1'
PurchaseAnalysisData
UPC	Product UPC (Required if PID not given)
PID	InComm Product ID (Required if UPC not given)

Response:

Field	Description
Success Flag	'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 Method	Call DoTransaction() to start transaction
csdReservedString2	Set to 'APP_1'
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
PurchaseAnalysisData
VRC	The Redeem Code of the voucher to void
PID	InComm Product ID (required if UPC not given)
UPC	Product UPC (required if PID not given)

Response:

Field	Description
Success Flag	'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 three 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 Method	Call DoTransaction() to start transaction
csdReservedString2	Set to 'APP_1'
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 Method	Call DoTransaction() to start transaction
csdReservedString2	Set to 'APP_1'
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.

Qantas Loyalty

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 Qantas Loyalty 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 Documentation.

The Qantas Loyalty extension file (TPP_QantasLoyalty.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 Qantas Loyalty extension requires basic lane configuration settings as well as various identifiers provided by Qantas Loyalty to be configured in the Registry, done automatically via installer.

If the TPPS_GENERIC.BCX is installed you can use the TPP Control Panel for the basic lane configuration, however the specific TPP_QantasLoyalty values will need to be pushed directly to the registry.

Methods

The POS can use the following methods to perform Qantas Loyalty transactions. For most POS setups it will be sufficient to implement calls only to the Proposition Transaction Workflow (which can optionally include a Member Info Query and / or Quote) and Void. However individual methods are provided if a more complex or custom workflow is required.

Note: If implementing a custom workflow, you may want to use the PurchaseAnalysisData 'SLT' tag to disable the POS response dialog and / or receipt printing for intermediate steps. SLT values include: '1' = Disable All; '2' = Print Receipt only; '4' = Display Response only

Member Info Query

Used to query the Qantas Loyalty platform for a frequent flyer members' information, including name and loyalty tier.

Request:

Field	Description
Command Method	Call DoTransaction() to start transaction
Merchant	Set to '62' to indicate a Qantas Loyalty transaction
TxnType	Set to 'B' to indicate a Member Info Query
PAN	Card Number if provided by the POS otherwise blank
PAN Source	Card capture method if captured by the POS
csdReservedString2	Set to 'APP_1'

Response:

Field	Description
Success Flag	'1' if successful
Response Code	'00' if it was approved
Response text	response message associated with the response code
PurchaseAnalysisData
HRC	Qantas Loyalty Host response Code
FNM	Member's First Name
SNM	Member's Surname
RNK	Membership tier

Authorisation

Used to get an authorisation token as part of a custom POS workflow.
Note: In most cases a separate authorisation transaction will not be needed, as transactions that rely on authorisation will do so automatically. It is however provided as a convenience for custom multi step workflows so they don't have to capture or hold the users' PIN code. Note: Authorisation is only required for Transaction and Quote requests where the Amount Purchase is greater than 0.

Request:

Field	Description
Command Method	Call DoTransaction() to start transaction
Merchant	Set to '62' to indicate a Qantas Loyalty transaction
TxnType	Set to 'X' to indicate a Authorisation query
PAN	Card Number if provided by the POS otherwise blank
PAN Source	Card capture method if captured by the POS
csdReservedString2	Set to 'APP_1'

Response:

Field	Description
Success Flag	'1' if successful
Response Code	'00' if it was approved
Response text	response message associated with the response code
PurchaseAnalysisData
HRC	Qantas Loyalty Host response Code
TKN	Authorisation Token

Quote

Used to query the Qantas Loyalty platform for a quote of how many points would be earned and / or burned for the given transaction values.
Note: The requested Amount Purchase must be a valid burn currency amount. If this is to be used for other than Earn (where the Amount Purchase can be set to 0), a valid value should either be obtained from a Proposition Transaction Workflow or pre-arranged with Qantas Loyalty.
Note: The returned Amount Purchase is only a quote, and should only be paid attention to if the transaction is Approved (i.e. Response Code '00')

Request:

Field	Description
Command Method	Call DoTransaction() to start transaction
Merchant	Set to '62' to indicate a Qantas Loyalty transaction
TxnType	Set to 'A' to indicate a Authorisation query
AmtPurchase	Set to the Currency amount for points to burn, otherwise 0 for earn only
PAN	Card Number if provided by the POS otherwise blank
PAN Source	Card capture method if captured by the POS
TxnRef	Unique Transaction reference number
csdReservedString2	Set to 'APP_1'
PurchaseAnalysisData
BFT	Basket Format (optional). Default VST
BSK	Basket Values
AMT	Total Transaction amount (must be >= Amount purchase)
TKN	Authorisation token (optional)

Response:

Field	Description
Success Flag	'1' if successful
Response Code	'00' if it was approved
Response text	response message associated with the response code
AmtPurchase	Quoted Currency Amount
PurchaseAnalysisData
HRC	Qantas Loyalty Host response Code
PBR	Quoted points burned
PER	Quoted points earned

Transaction

Used to perform a Qantas Loyalty Transaction to earn / burn points.
Note: The requested Amount Purchase must be a valid burn currency amount. If this is to be used for other than Earn (where the Amount Purchase can be set to 0), a valid value should either be obtained from a Proposition Transaction Workflow or pre-arranged with Qantas Loyalty. Note: The returned Amount Purchase should only be applied as a discount if the transaction is Approved (i.e. Response Code '00')

Request:

Field	Description
Command Method	Call DoTransaction() to start transaction
Merchant	Set to '62' to indicate a Qantas Loyalty transaction
TxnType	Set to 'P' to indicate a Earn/Burn Transaction
AmtPurchase	Set to the Currency amount for points to burn, otherwise 0 for earn only
PAN	Card Number if provided by the POS otherwise blank
PAN Source	Card capture method if captured by the POS
TxnRef	Unique Transaction reference number
csdReservedString2	Set to 'APP_1'
PurchaseAnalysisData
BFT	Basket Format (optional). Default VST
BSK	Basket Values
AMT	Total Transaction amount (must be >= Amount purchase)
TKN	Authorisation token (optional)

Response:

Field	Description
Success Flag	'1' if successful
Response Code	'00' if it was approved
Response text	response message associated with the response code
AmtPurchase	Quoted Currency Amount
PurchaseAnalysisData
HRC	Qantas Loyalty Host response Code
REF	Qantas Loyalty Transaction Reference
PBR	points burned
PER	points earned

Proposition Transaction Workflow

Used to perform a full earn / burn Qantas Loyalty workflow with dynamic burn propositions. Note: The default workflow consists of a Burn Proposition query and amount prompt, followed by a Transaction. From the POS point of view It is similar to a normal 4.4 Transaction except that the user will be prompted to select a burn amount (or earn only) on the pin pad.
Note: The PurchaseAnalysisData 'TXN' tag can be used to modify the steps included in the workflow:
'N' = Proposition Only (i.e. no follow up Transaction), 'B' = with Member Info, 'A' = with Quote
For example: TXN002NB = Proposition Only with Member Info

Request:

Field	Description
Command Method	Call DoTransaction() to start transaction
Merchant	Set to '62' to indicate a Qantas Loyalty transaction
TxnType	Set to 'N' to indicate a Transaction Flow
PAN	Card Number if provided by the POS otherwise blank
PAN Source	Card capture method if captured by the POS
TxnRef	Unique Transaction reference number
csdReservedString2	Set to 'APP_1'
PurchaseAnalysisData
BFT	Basket Format (optional). Default VST
BSK	Basket Values
AMT	Total Transaction amount (must be >= Amount purchase)
TKN	Authorisation token (optional)

Response:

Field	Description
Success Flag	'1' if successful
Response Code	'00' if it was approved
Response text	response message associated with the response code
AmtPurchase	Confirmed Currency Amount
PurchaseAnalysisData
HRC	Qantas Loyalty Host response Code
REF	Qantas Loyalty Transaction Reference
PBR	points burned
PER	points earned
FNM	Member's first name (optional)
SNM	Member's surname (optional)
RNK	Membership tier (optional)

Void

Used to void a previous Qantas Loyalty transaction.

Request:

Field	Description
Command Method	Call DoTransaction() to start transaction
Merchant	Set to '62' to indicate a Qantas Loyalty transaction
TxnType	Set to 'I' to indicate a Void
PAN	Card Number if provided by the POS otherwise blank
PAN Source	Card capture method if captured by the POS
TxnRef	Unique Transaction reference number
csdReservedString2	Set to 'APP_1'
PurchaseAnalysisData
REF	Qantas Loyalty Transaction reference to void
CMT	Void reason sent to Qantas Loyalty

Response:

Field	Description
Success Flag	'1' if successful
Response Code	'00' if it was approved
Response text	response message associated with the response code
PurchaseAnalysisData
HRC	Qantas Loyalty Host response Code
REF	Qantas Loyalty Transaction Reference
PBR	points burned
PER	points earned

Registry

The TPP Qantas Loyalty 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 Qantas Loyalty extension.

Registry Key Or Value	Type	Description
..\CullenSoftwareDesign\PCEFFTPOS_BRIDGE\TPP-QANTASLG	Key	Qantas Loyalty Registry Key
USERNAME	String	Username provided by Qantas Loyalty
PASSWORD	String	Password provided by Qantas Loyalty
ALLOW_EARN_ONLY	dword	Set to 0 to disable Earn Only*. Default 1
CODE_RETRY_MAX_ATTEMPTS	dword	Max code entry retries allowed by client*. Default 3
CODE_RETRY_MSG_TIMEOUT	dword	Seconds to display 'Invalid code, please retry' message after a failed attempt*. Default 3
RECEIPT_WIDTH	dword	Custom receipt width. Default 24

• Note these settings only apply to the Proposition Transaction Workflow, not the individual methods. Also, the number of retries specified by CODE_RETRY_MAX_ATTEMPTS may not be reached if the server dis-allows further attempts.

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 three digit lane number (pad to three digits) Eg."005"
StoreAddress	string	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 Method	Call DoTransaction() to start transaction
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
csdReservedString2	Set to 'APP_1'
PurchaseAnalysisData
OPR	Optional POS operator information
BSK
BFT

Response:

Field	Description
Success Flag	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 (PurchaseAnalysisData 'TDR' field) include:

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

Request:

Field	Description
Command Method	Call DoTransaction() to start transaction
Merchant	Set to '90' to indicate a TruRating transaction
TxnType	Set to 'T' to indicate a Top-up request
TxnRef	Unique transaction reference number
csdReservedString2	Set to 'APP_1'
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 Flag	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 Method	Call DoTransaction() to start transaction
Merchant	Set to '90' to indicate a TruRating transaction
TxnType	Set to 'A' to indicate a Activation Request
TxnRef	Unique transaction reference number
csdReservedString2	Set to 'APP_1'
PurchaseAnalysisData
OPR	Optional POS operator information

Response:

Field	Description
Success Flag	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 three 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	Call DoTransaction() 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
CsdReservedString2	Set to 'APP_1' 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	Call DoTransaction() 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
CsdReservedString2	Set to 'APP_1' 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
Command Method	Call DoTransaction() to start transaction
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
PAN Source	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
csdReservedString2	Set to 'APP_1'
PurchaseAnalysisData
PIN	Card PIN can be sent by the POS here (optional)

Response:

Field	Description
Success Flag	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 DoTransaction 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 Method	Call DoTransaction() to start transaction
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
PAN Source	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
csdReservedString2	Set to 'APP_1'
PurchaseAnalysisData
PIN	Card PIN can be sent by the POS here (optional)
PMT	Set to '1' for balance prompt (optional)

Response:

Field	Description
Success Flag	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
Command Method	Call DoTransaction() to start transaction
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
PAN Source	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
csdReservedString2	Set to 'APP_1'

Response:

Field	Description
Success Flag	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 DoTransaction 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 Method	Call DoTransaction() to start transaction
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
PAN Source	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
csdReservedString2	Set to 'APP_1'

Response:

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

Field	Description
Success Flag	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 three 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 Method	Call DoTransaction() to start transaction
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
PAN Source	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
csdReservedString2	Set to 'APP_1'
PurchaseAnalysisData
EXP	voucher expiry Date in DDMMYY format (optional)

Response:

Field	Description
Success Flag	'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 Method	Call DoTransaction() to start transaction
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
PAN Source	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
csdReservedString2	Set to 'APP_1'
PurchaseAnalysisData
EXP	voucher expiry Date in DDMMYY format (optional)

Response:

Field	Description
Success Flag	'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 Method	Call DoTransaction() to start transaction
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
PAN Source	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
csdReservedString2	Set to 'APP_1'
PurchaseAnalysisData
EXP	voucher expiry Date in DDMMYY format (optional)

Response:

Field	Description
Success Flag	'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 Method	Call DoTransaction() to start transaction
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
PAN Source	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
csdReservedString2	Set to 'APP_1'

Response:

Field	Description
Success Flag	'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 three 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 Method	Call DoTransaction() to start transaction
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
PAN Source	Code capture method if captured by the POS
TxnRef	Unique transaction reference number
csdReservedString2	Set to 'APP_1'
PurchaseAnalysisData
OPR	Operator info in the format: RefCode
AMT	Total Transaction amount (must be >= Amount Purchase)
TAX	Tax amount (optional)
SHP	Shipping amount (optional)
SKU	Basket Id from Basket API

Response:

Field	Description
Success Flag	'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 Method	Call DoTransaction() to start transaction
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
csdReservedString2	Set to 'APP_1'
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 Flag	'1' if successful
Response Code	'00' if it was approved
Response Rext	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 three 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 a 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 perform a 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
    

Document Version

Version	Date	Revisions
1.0.4	18 August 2022	- Updating POS Support email to [email protected]
1.0.3	01 August 2022	Added settlement report example and adapted Pascal case for keys in json
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

---