NAV Navbar
C# REST
  • Introduction
  • Start Developing
  • Core Payments
  • Food & Beverage
  • API Specification
  • Value Added Applications
  • Appendix
  • Document Version
  • 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

    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

    Management of merchant/bank functions

    Transactional Scenarios

    Error Handling

    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

    Example 2

    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:

    Input types:

    Example displays

    No keys enabled

    No keys enabled

    Cancel key enabled

    No keys enabled

    OK key enabled

    No keys enabled

    Accept/decline keys enabled

    No keys enabled

    Auth input enabled

    No keys 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:

    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:

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

    Surcharge Screen

    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:

    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.

    Patrestserver

    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.

    Pat std sd

    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

    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.

    Pat rest setup

    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.

    Pat local setup

    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.

    Tipping Screen

    If a tip is applied:

    This feature supports the following tip entry methods:

    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

    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:

    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

    Management of merchant/bank functions

    Transactional Scenarios

    Error Handling

    Purchase

    Purchase Request

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

    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:

    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:

    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

    img

    Below is a ZipMoney Refund Receipt

    img

    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

    img

    Below is an AfterPay Refund Receipt

    img

    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:

    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:

    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

    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:

    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

    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:

    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:

    Silent Card Not Supported In Transaction

    Limit Account Selection

    Operator Display Prompts

    Field 48 Data

    Myer Specific

    Tip value passed from POS

    Amount tag

    SKU tag

    Unique Card Identifier

    Available Balance

    Cleared Funds Balance

    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