Introduction

The Linkly Local REST API enables communication between a POS and payment app running on the same mobile payments device.

Payment flow

• POS POSTS HTTP payment request to local loopback address, and waits for the response
• Linkly app initates payment and payment app UI moves to the foreground
• User completes the payment and payment app UI closes
• POS app receives HTTP payment result, and POS app UI moves to the foreground

Start Developing

Technical Requirements

• All communications over HTTP. No requirement for HTTPS since both POS and payment app are on the same device
• Connect with the loopback IP address. No DNS required
• Session connectivity:
  
  • A unique session ID must be randomly generated using standard UUID v4 generating algorithms for each and every session made by the POS, even if a previous session was not successful. Duplicate session IDs will be rejected. The only exception is when requesting 'TransactionStatus', in which case the session ID of the desired transaction must be supplied.

TBD - POS development will require Linkly Connect app and Linkly payment app emulator. TODO: embed description of how to download and setup APK's - TODO: embed links for Android sample code via Github

Please direct any questions on the Linkly Cloud REST API to [email protected]

API Requests

Request URI

The request URI is made up of 4 parts; the base endpoint, a SessionId, the type of request to make, and the async URI parameter.

• A SessionId is a valid UUID which identifies the current POS request. This must be generated by the POS using standard GUID/UUID generating libraries, i.e. this must be a standard, globally unique UUID value for each and every Transaction Request.
• The request type portion of the path needs to be one of the following strings:

Request Types
transaction
logon
settlement
status
querycard
configuremerchant
reprintreceipt
sendkey

• An API Request object should be constructed and POSTed to the appropriate API endpoint.

Error Recovery

Error recovery only applies to the Transaction request and simply refers to performing a GET request to the API to request the Transaction Status, using the same SessionId as the original Transaction Request.

The POS must enter error recovery if, on POSTing a Transaction Request:

• the POS receives an HTTP 500-599 server error, HTTP 408 timeout, or any connection error, whilst waiting for a POSTed Transaction Response.

In recovery the POS should use the same 'SessionId' as the original transaction to periodically call Transaction Status until one of the following HTTP Status codes is received:

• 200 OK - this response should include an APIResponse
• 400 Invalid Request - this is an error condition indicating that the Transaction Status request was invalid. Do not retry, log it and return an error to the operator (the transaction result cannot be determined).
• 401 Unauthorised - try getting a new token and then continue. If this persists, abort (the password may have changed).
• 404 Not Found - Either the Transaction Status URI used was incorrect (check configuration) or the transaction was not submitted successfully and can be resubmitted safely.

Any other HTTP status code (202, 408, 500-599) should mean the POS continues to retry.

Example

1. You POST a transaction to https://127.0.0.1/v1/sessions/c98433543a0d43eeba8f5876607f1df0/transaction
2. You receive an HTTP error 408 indicating that the request has timed out. This does not specify whether or not the transaction succeeded.
3. You enter recovery mode and start polling GET https://127.0.0.1/v1/sessions/c98433543a0d43eeba8f5876607f1df0/transaction every few seconds.
4. You receive an HTTP 202 each time indicating the transaction is still in progress.
5. Eventually you receive an HTTP 200 with a valid Transaction Response. The Transaction Response object (not the HTTP Status code) indicates the financial success of the Transaction Request.

The error recovery can end when either:

• The POS receives an HTTP 200 "OK" with a valid Transaction Response,
• The POS receives an HTTP 404 "Resource not found" response, which (assuming the correct GET request URI is used) indicates that the original transaction was not processed, or
• The POS receives an HTTP 400 "Invalid request" response, indicating an invalid POS request which should be investigated and resolved.

All other HTTP response codes indicate that, in one way or another, the POS should keep trying to GET the Transaction Response, as outlined below.

Sync Mode Recovery

The error recovery sequence diagrams for both client-to-cloud and server-to-cloud synchronous mode of communication is shown below.

HTTP Response codes returned from Transaction Status.

HTTP Code	Description	Required action
200	OK - This will be accompanied by a valid response. The 'success' property in the Response object indicates the financial status of the transaction.	Inspect the response to check the result of the financial transaction (e.g. Approved, Declined, Approve with signature, etc.)
202	Accepted - The original transaction has been received but is not yet complete. Response body will be null.	The POS should retry the GET request every 1-2 seconds for up to 3 minutes, or until another HTTP code is received.
400	Invalid request - This error does NOT indicate success or failure of the original transaction, but rather that the GET request is badly formed. It is likely that the session Id is not a valid UUID.	Do NOT retry this GET request, as it is incorrectly formed.
401	Unauthorised - The token supplied is invalid. This error does NOT indicate success or failure of the original transaction.	The POS should refresh the token and attempt the GET request again.
404	Resource not found - Either the GET request URI is incorrect (the endpoint was not found) or the session Id requested was not found, hence the original transaction was not submitted successfully.	So long as the Transaction Status URI is configured correctly, the POS can safely retry the original transaction with the same (or new) SessionId.
408	Request Timeout - This should be rare: a transient error has occurred, possibly due to server overloading.	The POS should retry the GET request every few seconds for up to 3 minutes, or until another code is received. Please use exponential backoff to avoid overloading the server further.
500-599	A server error has occurred.	The POS should continue to perform the GET request using exponential backoff to avoid overloading the server.

Core Payments

Overview

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

Minimum Requirements

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

Transaction Types

• Purchase (P)
• Refund (R)

Management of merchant/bank functions

• Reprint Receipt
• Transaction Status

Transactional Scenarios

• Partial/Split Payments

Error Handling

• Error Recovery

Purchase

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

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

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

Purchase Request

Example Transaction Request object

{
  "Request": {
    "Merchant": "00",
    "TxnType": "P",
    "AmtPurchase": 100,
    "TxnRef": "1234567890",
    "CurrencyCode": "AUD",
    "CutReceipt": "0",
    "ReceiptAutoPrint": "0",
    "Application": "00",
    "PurchaseAnalysisData": {
      "OPR": "00766|test",
      "AMT": "0042000",
      "PCM": "0000"
    },
    "Basket": {
      "Id": "t39kq18134553",
      "Amt": 2145,
      "Tax": 200,
      "Dis": 50,
      "Sur": 0,
      "Items": [
        {
          "Id": "t39kq002",
          "Sku": "k24086723",
          "Qty": 2,
          "Amt": 2145,
          "tax": 200,
          "Dis": 50,
          "Name": "XData USB Drive"
        }
      ]
    }
  }
}

Below are the fields from the transaction request that must be set for a purchase transaction.

Field Name	Type	Required value	Notes
Merchant	string(2)	Variable	Two Digit Merchant Code. Defaults to '00' (EFTPOS)
TxnType	string(1)	'P'	Purchase
AmtPurchase	number	Variable	Left zero filled, amount of sale in cents.
TxnRef	string(16)	Variable	The reference number to attach to the transaction. This will appear on the receipt.
CurrencyCode	string(3)	Variable	Code to indicate requested currency. e.g. 'AUD'
CutReceipt	string(1)	Variable	Indicates whether Linkly should cut receipts. Defaults to '0' (DontCut)
ReceiptAutoPrint	string(1)	Variable	Indicates if the POS is to receive receipt events. Default '0'.
Application	string(2)	'00'	Instructs Linkly to perform a card payment
PurchaseAnalysisData	object	Variable	Extended fields. See PurchaseAnalysisData note below.
Basket	object	Variable	See basket section for details

PurchaseAnalysisData

Tag	Name	Type	Notes	Example
OPR	OperatorReference	string(128)	POS operator name and id. Format: ID|Name	{"OPR": "66|test" }
AMT	TotalAmount	string(9)	Total amount of the entire sale in cents, not Tender amount	{"AMT": "20000" } $200.00 total sale
PCM	POSCapabilitiesMatrix	string(128)	POS Capabilities Matrix. First byte = POS can scan Barcode	{"PCM": "0000"}

Purchase Response

Example purchase Response object

{
  "SessionId": "dd250a0c81c202b66220d7379b338b8f",
  "ResponseType": "transaction",
  "Response": {
    "TxnType": "P",
    "Merchant": "00",
    "CardType": "AMEX CARD           ",
    "CardName": "05",
    "RRN": "123456789012",
    "DateSettlement": "2018-07-31T00:00:00",
    "AmtCash": 0,
    "AmtPurchase": 100,
    "AmtTip": 0,
    "AuthCode": 123456,
    "TxnRef": "1234567890      ",
    "Pan": "37601234567890      ",
    "DateExpiry": "4909",
    "Track2": "37601234567890=0949?,,S, YES, 05??????  ",
    "AccountType": "2",
    "TxnFlags": {
      "Offline": "1",
      "ReceiptPrinted": "0",
      "CardEntry": "S",
      "CommsMethod": "0",
      "Currency": "0",
      "PayPass": "0",
      "UndefinedFlag6": "0",
      "UndefinedFlag7": "0"
    },
    "BalanceReceived": false,
    "AvailableBalance": 0,
    "ClearedFundsBalance": 0,
    "Success": true,
    "ResponseCode": "00",
    "ResponseText": "APPROVED            ",
    "Date": "2018-07-31T16:14:40",
    "Catid": "12345678",
    "Caid": "0987654321     ",
    "Stan": 0,
    "PurchaseAnalysisData": {
      "RFN": "klujhadsc9ph87asd",
      "REF": "12345",
      "HRC": "ERR1",
      "HRT": "INVALID CARD"
    },
    "Receipts": [
      {
        "Type": "C",
        "ReceiptText": [
          "------------------------",
          " *** TRAINING MODE ***  ",
          "  TEST MERCHANT TITLE   ",
          "   TEST MERCHANT NAME   ",
          "         LINE2          ",
          "                        ",
          "00:38:34 16/10/20       ",
          "                        ",
          "SAVINGS ACCOUNT         ",
          "                        ",
          "PURCHASE   AUD     $2.00",
          "                --------",
          "TOTAL      AUD     $2.00",
          "                        ",
          "APPROVED -  00          ",
          "                        ",
          "PLEASE RETAIN AS RECORD ",
          "      OF PURCHASE       ",
          "------------------------"
        ],
        "IsPrePrint": false
      }
    ]
  }
}

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

PurchaseAnalysisData

Tag	Name	Type	Notes	Example
RFN	Reference Number	string(128)	Transaction Reference Number to be used in a refund, can contain additional information	{"RFN":"klujhadsc9ph87asd"}
REF	Host reference Number	string(32)	Reference number to the sale from the provider systems, printed on receipt	{"REF":"12345"}
HRC	Host Response Code	string(64)	Response code from the payment processor	{"HRC":"ERR1"}
HRT	Host Response Text	string(999)	Response text from the payment processor	{"HRT":"INVALID CARD"}

Refund

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

Refund Request

{
  "Request": {
    "Merchant": "00",
    "TxnType": "R",
    "AmtPurchase": 100,
    "TxnRef": "1234567890",
    "CurrencyCode": "AUD",
    "CutReceipt": "0",
    "ReceiptAutoPrint": "0",
    "App": "00",
    "PurchaseAnalysisData": {
      "RFN": "klujhadsc9ph87asd",
      "OPR": "00766|test",
      "AMT": "0042000",
      "PCM": "0000"
    }
  }
}

Field Name	Type	Required value	Notes
Merchant	string(2)	Variable	Two Digit Merchant Code. Defaults to '00' (EFTPOS)
TxnType	string(1)	'R'	Purchase
AmtPurchase	number	Variable	Left zero filled, amount of sale in cents.
TxnRef	string(16)	Variable	The reference number to attach to the transaction. This will appear on the receipt.
CurrencyCode	string(3)	Variable	Code to indicate requested currency. e.g. 'AUD'
CutReceipt	string(1)	Variable	Indicates whether Linkly should cut receipts. Defaults to '0' (DontCut)
ReceiptAutoPrint	string(1)	Variable	Indicates if the POS is to receive Receipt Events, default '0'.
Application	string(2)	'00'	Instructs Linkly to perform a card payment
PurchaseAnalysisData	object	Variable	Extended fields. See PurchaseAnalysisData note below.
Basket	object	Variable	See basket section for details

PurchaseAnalysisData

Tag	Name	Type	Notes	Example
RFN	Reference Number	string(128)	Reference Number from purchase request this refund is for	{"RFN":"klujhadsc9ph87asd"}
OPR	OperatorReference	string(128)	POS operator name and id. Format: ID|Name	{"OPR": "66|test" }
AMT	TotalAmount	string(9)	Total amount of the entire sale in cents, not Tender amount	{"AMT": "20000" } $200.00 total sale
PCM	POSCapabilitiesMatrix	string(128)	POS Capabilities Matrix. First byte = POS can scan Barcode	{"PCM": "0000"}

Refund Response

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

PurchaseAnalysisData

Tag	Name	Type	Notes	Example
REF	Host reference Number	string(128)	Reference number to the sale from the provider systems, printed on receipt	{"REF":"12345"}
HRC	Host Response Code	string(64)	Response code from the payment processor	{"HRC":"ERR1"}
HRT	Host Response Text	string(999)	Response text from the payment processor	{"HRT":"INVALID CARD"}

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 Transaction Status

Reprint Receipt

The reprint receipt function allows for the retrieval/reprint of a financial receipt. 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

Example reprint receipt request object

{
  "Request": {
    "Merchant": "99",
    "ReceiptAutoPrint": "0",
    "ReprintType": "2"
  }
}

Field Name	Type	Required value	Notes
Merchant	string(2)	Variable	Two Digit Merchant Code. Defaults to '00' (EFTPOS)
CutReceipt	string(1)	Variable	Indicates whether Linkly should cut receipts. Defaults to '0' (DontCut)
ReceiptAutoPrint	string(1)	Variable	Indicates if the POS is to receive Receipt Events, default '0'. Linkly recommends the POS receive receipt events and handle them accordingly

Reprint Receipt Response

See Reprint Receipt Response Object for response format

Transaction Status

This function returns the last transaction event processed by Linkly. 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.

See Transaction Status for request/response format

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 paid for.

Example 1

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

Example 2

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

Error Handling

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

Linkly Basket

The "basket" in the Transaction Request contains information about items in the transaction.

Basket Command Header Fields

{
  "Id": "t39kq18134553",
  "Amt": 17890,
  "Tax": 1790,
  "Dis": 1000,
  "Sur": 358,
  "Items": [...]
}

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

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

Basket Command Item Fields

Example basket item data object

{
  "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, max 16
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, max 16
Upc		The UPC (Universal Product Code) for the item	String, max 16
Gtin		The GTIN (Global Trade Item Number) for the item	String, max 16
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, max 16
Img		URL to an image for the item	String
Link		URL to a product page for the item	String
Tag		Comma separated category or type information for the item (e.g. "food, confectionery”)	String, max 64

Basket Command Extended Item Fields

{
  "Id": "t39kq001",
  "Sku": "s63787452",
  "Qty": 1,
  "Amt": 1995,
  "Weight": "2kg"
}

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

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

Basket Command Full Example

Full Basket Example

{
  "Id": "t39kq18134553",
  "Amt": 18700,
  "Tax": 1760,
  "Dis": 650,
  "Sur": 374,
  "Items": [
    {
      "Id": "t39kq002",
      "Sku": "k24086723",
      "Qty": 2,
      "Amt": 2145,
      "Tax": 200,
      "Dis": 50,
      "Name": "XData USB Drive"
    },
    {
      "Id": "t39kq003",
      "Sku": "s23475697",
      "Qty": 1,
      "Amt": 8910,
      "Tax": 810,
      "Name": "MSoft OSuite",
      "Srl": "ms7843k346j23"
    },
    {
      "Id": "t39kq004",
      "Sku": "m47060855",
      "Qty": 5,
      "Amt": 1100,
      "Tax": 110,
      "Dis": 110,
      "Name": "A4 Notepad"
    }
  ]
}

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

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 use the Linkly Merchant Portal to set their desired surcharging rates.

If a surcharge is applied:

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

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.

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 Merchant Portal, and set EnableTip to '1' in the Transaction Request.

If a tip is applied:

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

This feature supports the following tip entry methods:

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

To provide POS partners with the flexibility to use their own tipping solutions Linkly supports the following requests as part of the transaction 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 its own tipping solution. For all other instances, nothing is needed from the POS to enable tipping for a merchant.

TIP tag definition

API Specification

All Requests and Responses are wrapped in ApiRequest and ApiResponse JSON objects respectively.

ApiRequest

Example APIRequest object

{
  "Request":{
    "SomeKey":"somevalue",
    "SomeKey":"somevalue",
    ....
  }
}

A request to the Linkly Cloud REST API is made up of two JSON objects a "Request" and a "Notification" (optional for sync mode, mandatory for async mode).
The "Request" object will contain all the information a POS will send to make a request, be it a transaction or a settlement.

The "Notification" object contains information about the POS' web server that is capable of receiving responses from the Linkly Cloud REST API about its current requests. Most requests will generate display responses and receipt responses in addition to the original request response that the POS is expected to handle. All these will be in JSON wrapped in a "Response" object and contain a "SessionId".

GET and POST Requests
All requests are made using POST, except for Transaction, which also has GET functionality, for Transaction Status. When using GET on Transaction the POS must send the SessionId of the Transaction they want retrieved, the POS will either receive a 202 "in progress" or a 200 OK with the Transaction Response in the body.

ApiResponse

Example APIResponse object

{
  "SessionId": "a1b2c3d4e5",
  "ResponseType": "transaction",
  "Response": {
    "SomeKey": "somevalue",
    "SomeOtherKey": "somevalue"
  }
}

An ApiResponse is made up of a "Response" object which contains the information relating to the original request such as a Transaction.

It also contains a "SessionId", a valid UUID which forms the unique session identifier for this request.

Finally the Linkly Cloud REST API also sends a ResponseType field which contains an identifier for this response.

It's important to understand what the Cloud API response means, and that there are at least two layers to responses.

HTTP Response

The REST API is a layer on top of back-end EFT services. The API has its own response codes to indicate error conditions in the API itself which have no relation to anything financial or transaction-related. It does this with HTTP Status Codes. There are two "non-error" HTTP status codes, HTTP 200 and HTTP 202.

HTTP 200 OK

This indicates that the request was able to be processed successfully, but does not say what the result of that request is.

Example 1:

You POST a synchronous Transaction to the API for a purchase of $10. The API responds with HTTP 200 and an ApiResponse. The HTTP 200 response code indicates that it was able to pass on the Transaction Request to the EFT Client, and got a Transaction Response. It does not mean the transaction was successful. In order to check if the transaction was successful (i.e. money was actually transferred) you need to check the Response's Success flag.

Example 2:

You POST a Logon request to the API, but the PIN pad is offline. The API responds with HTTP 200, indicating that it was able to relay the request to the EFT Client, and the EFT Client gave a valid response back. Again, you need to inspect the Response to determine that the PIN pad is offline.

Example 3:

After a power failure, your POS enters error recovery to determine the status of the last transaction it sent. Upon sending the GET Transaction Status request, the API responds with an HTTP 404 Unauthorised response. This is no reflection on the original transaction, but instead the POS refreshes its token and retries the request. This time it receives an HTTP 200, which once again needs to be inspected to find out if the transaction was actually successful.

HTTP 202 Accepted

This indicates that the request has been accepted by the API and it is currently processing that request. It does not indicate that the Transaction Request has necessarily been "accepted" yet by either the EFT Client, PIN pad, or bank. You should wait for the Transaction Response and determine the result from that.

Other HTTP status codes

All other status codes besides 200 and 202 indicate that the API was unable to fulfill the REST request, not whether or not the transaction succeeded (although you can sometimes determine unsuccessful requests based on HTTP status code).

** Example 1:**

You POST a synchronous Transaction to the API for a purchase of $10. The API responds with HTTP 500. This indicates that there's something wrong with either the API itself or infrastructure around the API. Examples may include: internet outages, server overloading, etc. The POS should enter error recovery to find out whether it was successful.

** Example 2:**

You POST a synchronous Transaction to the API for a purchase of $10. The API responds with HTTP 401. This indicates that the authorisation token is not valid and needs to be renewed. In this case it can be safely assumed that the transaction was not successful yet, but the POS should renew the token and try again.

EFT Response

The next layer is the EFT Response, which is found inside the API Response. The EFT Response is received in one of only 3 ways:

1. As a notification message posted to the POS's appropriate endpoint, if supplied
2. In the body of the response to an HTTP POST request (e.g. Transaction, Status or Logon), but only where the HTTP Status code is 200.
3. In the body of the response to an HTTP GET transaction status request.

Methods

Transaction

Transaction Request

# replace <<token>> with the token returned from your auth request
curl -v "https://127.0.0.1/v1/sessions/$(uuidgen)/transaction?async=false" \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <<token>>' \
  -H 'Accept: application/json' \
  -d '{
        "Request": {
          "TxnType": "P",
          "AmtPurchase": 100,
          "TxnRef": "0123456789ABCDEF"
        }
      }'

var token = "<<token>>"; // replace <<token>> with the token returned from your auth request
var requestContent = new
{
  Request = new
  {
    TxnType = "P",
    AmtPurchase = 100,
    TxnRef = DateTime.Now.ToString("yyMMddhhmmssffff"),
  }
};

var request = new HttpRequestMessage(HttpMethod.Post, $"https://127.0.0.1/v1/sessions/{Guid.NewGuid().ToString()}/transaction?async=false")
{
  Content = new StringContent(Newtonsoft.Json.JsonConvert.SerializeObject(requestContent), System.Text.Encoding.UTF8, "application/json")
};
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
var httpClient = new HttpClient(); // Note: in production don't create multiple HttpClient instances. Share one single instance.
HttpResponseMessage httpResponse = await httpClient.SendAsync(request);
string responseContent = await httpResponse.Content.ReadAsStringAsync();

import datetime
import uuid
import requests; # http://python-requests.org

token = '<<token>>' # replace <<token>> with the token returned from your auth request
request_payload = {
  "Request": {
    "TxnType": "P",
    "AmtPurchase": 100,
    "TxnRef": datetime.datetime.now().strftime('%y%m%d%H%M%S%f')[:-4]
  }
}
uri = 'https://127.0.0.1/v1/sessions/' + str(uuid.uuid4()) + '/transaction?async=false'
headers = {'Authorization': 'Bearer ' + token}
response = requests.post(uri, json=request_payload, headers=headers)
response_payload = response.json()

Send a Transaction Request (e.g. purchase, refund, cash out).

URI Path

POST ~/v1/sessions/<<sessionid>>/transaction&async=false

Headers

Parameter	Value
Content-Type	application/json
Accept	application/json

Transaction Request Object

Example Transaction Request object

{
  "Request": {
    "AmtPurchase": 100,
    "TxnType": "P",
    "TxnRef": "1234567890",
    "Basket": {
      "Id": "t39kq18134553",
      "Amt": 2145,
      "Tax": 200,
      "Dis": 50,
      "Sur": 0,
      "Items": [
        {
          "Id": "t39kq002",
          "Sku": "k24086723",
          "Qty": 2,
          "Amt": 2145,
          "Tax": 200,
          "Dis": 50,
          "Name": "XData USB Drive"
        }
      ]
    }
  }
}

Field KeyName	Type	Required	Description
Merchant	string(2)		Two Digit Merchant Code. Defaults to '00' (EFTPOS) unless performing TPP transactions
ReceiptAutoPrint	string(1)		Indicates if the POS is to receive Receipt Events, default '0'.
CutReceipt	string(1)		Indicates whether Linkly should cut receipts. Defaults to '0' (DontCut)
TxnType	string(1)	Yes	Required. Indicated the type of transaction to perform
CurrencyCode	string(3)		Currency code for this transaction (e.g. AUD) A 3-digit ISO currency code. Defaults to " "(NotSet)
OriginalTxnType	string(1)		The original type of transaction for voucher entry. Defaults to 'P' (PurchaseCash)
Date	string(12)	Yes	Nullable. Original transaction time. Used for voucher or completion only
Time	string(12)		Nullable. Original transaction time. Used for voucher or completion only
TrainingMode	bool		Nullable. Determines if the transaction is a training mode transaction. Set to TRUE if the transaction is to be performed in training mode. The default is FALSE.
EnableTip	bool		Nullable. Set to TRUE if tipping is to be enabled for this transaction. The default is FALSE
AmtCash	number		In Cents. The cash amount for the transaction. This property is mandatory for a 'C' transaction type.
AmtPurchase	number	Yes	In Cents. The purchase amount for the transaction.
AuthCode	string(6)		Nullable. The authorisation number for the transaction. Defaults to 0
TxnRef	string(16)	Yes	Required.
PanSource	string(1)		Indicates the source of the PAN. Use this property for card not present transactions. Defaults to ' ' (PIN pad)
Pan	string(20)		The PAN to use when pan source of POS keyed is used. Use this property in conjunction with PanSource
DateExpiry	string(4)		The expiry date of the card when of POS keyed is used. In MMYY format. Use this property in conjunction with PanSource when passing the card expiry date to Linkly.
Track2	string(40)		The track 2 to use when of POS swiped is used. Use this property in conjunction with PanSource
AccountType	string(1)		The account to use for this transaction. Defaults to ' ' (prompt user)
RRN	string(12)		The retrieval reference number for the transaction. Only required for some transaction types
PurchaseAnalysisData	object		Extended fields. See Purchase Analysis Data section for details
Basket	object		See basket section for details

Transaction Response HTTP Status Codes

Code	Description	Required action
200	Only for synchronous mode. The transaction completed and a valid response has been returned. The 'success' property in the Response object indicates the financial success of the transaction.	Check the body for an APIResponse object
202	Only for asynchronous mode. The transaction has been started. Response body will be null.	The POS should await the result in its Notification postback
400	Invalid request. The transaction has not completed successfully.	Report the error and notify the operator. Do not retry.
401	The token supplied is invalid.	The POS should refresh the token and attempt the request again. If this persists, the password may have changed.
404	Resource not found. The transaction was not submitted successfully.	The request URI is not configured properly. Report the error and notify the operator. Do not retry.
408	A transient error has occurred.	The POS should enter error recovery
500-599	A server error has occurred.	The POS should enter error recovery

Transaction Response Object

Example Transaction Response object

{
  "SessionId": "dd250a0c81c202b66220d7379b338b8f",
  "ResponseType": "transaction",
  "Response": {
    "TxnType": "P",
    "Merchant": "00",
    "CardType": "AMEX CARD           ",
    "CardName": "05",
    "RRN": "123456789012",
    "DateSettlement": "2018-07-31T00:00:00",
    "AmtCash": 0,
    "AmtPurchase": 100,
    "AmtTip": 0,
    "AuthCode": 123456,
    "TxnRef": "1234567890      ",
    "Pan": "37601234567890      ",
    "DateExpiry": "4909",
    "Track2": "37601234567890=0949?,,S, YES, 05??????  ",
    "AccountType": "2",
    "TxnFlags": {
      "Offline": "1",
      "ReceiptPrinted": "0",
      "CardEntry": "S",
      "CommsMethod": "0",
      "Currency": "0",
      "PayPass": "0",
      "UndefinedFlag6": "0",
      "UndefinedFlag7": "0"
    },
    "BalanceReceived": false,
    "AvailableBalance": 0,
    "ClearedFundsBalance": 0,
    "Success": true,
    "ResponseCode": "00",
    "ResponseText": "APPROVED            ",
    "Date": "2018-07-31T16:14:40",
    "Catid": "12345678",
    "Caid": "0987654321     ",
    "Stan": 0,
    "PurchaseAnalysisData": {},
    "Receipts": [
      {
        "Type": "C",
        "ReceiptText": [
          "------------------------",
          " *** TRAINING MODE ***  ",
          "  TEST MERCHANT TITLE   ",
          "   TEST MERCHANT NAME   ",
          "         LINE2          ",
          "                        ",
          "00:38:34 16/10/20       ",
          "                        ",
          "SAVINGS ACCOUNT         ",
          "                        ",
          "PURCHASE   AUD     $2.00",
          "                --------",
          "TOTAL      AUD     $2.00",
          "                        ",
          "APPROVED -  00          ",
          "                        ",
          "PLEASE RETAIN AS RECORD ",
          "      OF PURCHASE       ",
          "------------------------"
        ],
        "IsPrePrint": false
      }
    ]
  }
}

Field KeyName	Type (Length)	Description
Merchant	string(2)	Two Digit Merchant Code. Defaults to '00' (EFTPOS) unless performing TPP transactions
CardType	string(20)	Indicates the card type that was used in the transaction.
CardName	string(2)	BIN Number of the card
TxnType	string(1)	Required. Indicated the type of transaction to perform
DateSettlement	string(12)	Indicates which settlement batch this transaction will be included in.
AmtTip	number	In cents. The tip amount for the transaction.
TxnFlags	object	Flags that indicate how the transaction was processed.
BalanceReceived	bool	Indicates if an available balance is present in the response.
AvailableBalance	number	Balance available on the processed account.
ClearedFundsBalance	number	Cleared balance on the processed account.
AmtCash	number	In cents. The cash amount for the transaction. This property is mandatory for a 'C' transaction type.
AmtPurchase	number	In cents. The purchase amount for the transaction.
Success	bool	Indicates if the request was successful.
TxnRef	string(16)	The reference number to attach to the transaction. This will appear on the receipt.
ResponseCode	string(2)	The response code of the request.
Pan	string(20)	The PAN to use when pan source of POS keyed is used. Use this property in conjunction with PanSource
ResponseText	string(20)	The response text for the response code.
Track2	string(40)	The track 2 to use when of POS swiped is used. Use this property in conjunction with PanSource
Date	string(12)	Date and time of the response returned by the bank
RRN	string(12)	The retrieval reference number for the transaction. Only required for some transaction types
Catid	string(8)	Terminal ID configured in the PIN pad.
Caid	string(15)	Merchant ID configured in the PIN pad.
Stan	number	System Trace Audit Number
PurchaseAnalysisData	object	Extended fields. See Purchase Analysis Data section for details

Synchronous mode of communication

The sequence diagram for a sample successful transaction in synchronous mode of communication is shown below

Transaction Status

Transaction Status request

# replace <<SessionId>> with the SessionId of the transaction to retrieve
# replace <<token>> with the token returned from your auth request
curl -v "https://127.0.0.1/v1/sessions/<<SessionId>>/transaction?async=false" \
  -X GET \
  -H 'Authorization: Bearer <<token>>' \
  -H 'Accept: application/json'

var SessionId = "<<SessionId>>"; // replace <<SessionId>> with the SessionId of the transaction to retrieve
var token = "<<token>>"; // replace <<token>> with the token returned from your auth request
var request = new HttpRequestMessage(HttpMethod.Get, $"https://127.0.0.1/v1/sessions/{SessionId}/transaction?async=false");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
var httpClient = new HttpClient(); // Note: in production don't create multiple HttpClient instances. Share one single instance.
HttpResponseMessage httpResponse = await httpClient.SendAsync(request);
string responseContent = await httpResponse.Content.ReadAsStringAsync();

import datetime
import uuid
import requests; # http://python-requests.org

SessionId = '<<SessionId>>' # replace <<SessionId>> with the SessionId of the transaction to retrieve
token = '<<token>>' # replace <<token>> with the token returned from your auth request
uri = 'https://127.0.0.1/v1/sessions/' + SessionId + '/transaction?async=false'
headers = {'Authorization': 'Bearer ' + token}
response = requests.get(uri, headers=headers)
response_payload = response.json()

Request the status of a previous transaction.

URI Path

GET ~/v1/sessions/<<sessionid>>/transaction

Headers

Parameter	Value
Content-Type	application/json
Accept	application/json

Transaction Status Response HTTP Status Codes

Code	Description	Required action
200	The transaction completed and a valid response has been returned. The 'success' property in the Response object indicates the financial success of the requested transaction.	Check the body for an APIResponse object
202	The transaction has been started. Response body will be null.	The POS should wait a few seconds and try again.
400	Invalid request. It is likely that the session Id is not a valid UUID.	Report the error and notify the operator. Do not retry.
401	The token supplied is invalid.	The POS should refresh the token and attempt the request again. If this persists, the password may have changed.
404	Resource not found. Either the request URI is wrong or the transaction was not submitted successfully and could not be found.	Check to ensure that the URI is correct. If in Recovery mode, the original transaction can be retried.
408	A transient error has occurred.	Wait a few seconds and retry
500-599	A server error has occurred.	Wait a few seconds and retry

Transaction Status Response Body

Exmaple Transaction Status response

{
  "SessionId": "dd250a0c81c202b66220d7379b338b8f",
  "ResponseType": "transaction",
  "Response": {
    "TxnType": "P",
    "Merchant": "00",
    "CardType": "AMEX CARD           ",
    "CardName": "05",
    "RRN": "123456789012",
    "DateSettlement": "2018-07-31T00:00:00",
    "AmtCash": 0,
    "AmtPurchase": 100,
    "AmtTip": 0,
    "AuthCode": 123456,
    "TxnRef": "1234567890      ",
    "Pan": "37601234567890      ",
    "DateExpiry": "4909",
    "Track2": "37601234567890=0949?,,S, YES, 05??????  ",
    "AccountType": "2",
    "TxnFlags": {
      "Offline": "1",
      "ReceiptPrinted": "0",
      "CardEntry": "S",
      "CommsMethod": "0",
      "Currency": "0",
      "PayPass": "0",
      "UndefinedFlag6": "0",
      "UndefinedFlag7": "0"
    },
    "BalanceReceived": false,
    "AvailableBalance": 0,
    "ClearedFundsBalance": 0,
    "Success": true,
    "ResponseCode": "00",
    "ResponseText": "APPROVED            ",
    "Date": "2018-07-31T16:14:40",
    "Catid": "12345678",
    "Caid": "0987654321     ",
    "Stan": 0,
    "PurchaseAnalysisData": {},
    "Receipts": [
      {
        "Type": "C",
        "ReceiptText": [
          "------------------------",
          " *** TRAINING MODE ***  ",
          "  TEST MERCHANT TITLE   ",
          "   TEST MERCHANT NAME   ",
          "         LINE2          ",
          "                        ",
          "00:38:34 16/10/20       ",
          "                        ",
          "SAVINGS ACCOUNT         ",
          "                        ",
          "PURCHASE   AUD     $2.00",
          "                --------",
          "TOTAL      AUD     $2.00",
          "                        ",
          "APPROVED -  00          ",
          "                        ",
          "PLEASE RETAIN AS RECORD ",
          "      OF PURCHASE       ",
          "------------------------"
        ],
        "IsPrePrint": false
      }
    ]
  }
}

Field KeyName	Description
Merchant	Two Digit Merchant Code. Defaults to '00' (EFTPOS) unless performing TPP transactions
CardType	Indicates the card type that was used in the transaction.
CardName	BIN Number of the card
TxnType	Required. Indicated the type of transaction to perform
DateSettlement	Indicates which settlement batch this transaction will be included in.
AmtTip	The tip amount for the transaction.
TxnFlags	Flags that indicate how the transaction was processed.
BalanceReceived	Indicates if an available balance is present in the response.
AvailableBalance	Balance available on the processed account.
ClearedFundsBalance	Cleared balance on the processed account.
AmtCash	In Cents. The cash amount for the transaction. This property is mandatory for a 'C' transaction type.
AmtPurchase	In Cents. The purchase amount for the transaction.
Success	Indicates if the request was successful.
TxnRef	Required.
ResponseCode	The response code of the request.
Pan	The PAN to use when pan source of POS keyed is used. Use this property in conjunction with PanSource
ResponseText	The response text for the response code.
Track2	The track 2 to use when of POS swiped is used. Use this property in conjunction with PanSource
Date	Date and time of the response returned by the bank
RRN	The retrieval reference number for the transaction. Only required for some transaction types
Caid	Terminal ID configured in the PIN pad.
Stan	Merchant ID configured in the PIN pad.
PurchaseAnalysisData	Extended fields. See Purchase Analysis Data section for details

Status

Status request

# replace <<token>> with the token returned from your auth request
curl -v "https://127.0.0.1/v1/sessions/$(uuidgen)/status?async=false" \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <<token>>' \
  -H 'Accept: application/json' \
  -d '{
        "Request": {
          "StatusType": "0"
        }
      }'

var token = "<<token>>"; // replace <<token>> with the token returned from your auth request
var requestContent = new
{
  Request = new
  {
    StatusType = "0"
  }
};

var request = new HttpRequestMessage(HttpMethod.Post, $"https://127.0.0.1/v1/sessions/{Guid.NewGuid().ToString()}/status?async=false")
{
  Content = new StringContent(Newtonsoft.Json.JsonConvert.SerializeObject(requestContent), System.Text.Encoding.UTF8, "application/json")
};
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
var httpClient = new HttpClient(); // Note: in production don't create multiple HttpClient instances. Share one single instance.
HttpResponseMessage httpResponse = await httpClient.SendAsync(request);
string responseContent = await httpResponse.Content.ReadAsStringAsync();

import datetime
import uuid
import requests; # http://python-requests.org

token = '<<token>>' # replace <<token>> with the token returned from your auth request
request_payload = {
  "Request": {
    "StatusType": "0"
  }
}
uri = 'https://127.0.0.1/v1/sessions/' + str(uuid.uuid4()) + '/status?async=false'
headers = {'Authorization': 'Bearer ' + token}
response = requests.post(uri, json=request_payload, headers=headers)
response_payload = response.json()

Instruct the EFT-Client to send a status message to the PIN pad to check if the PIN pad is available for use.

URI Path

POST ~/v1/sessions/<<sessionid>>/status&async=false

Headers

Parameter	Value
Authorization	The bearer token returned from ~/v1/tokens/cloudpos
Content-Type	application/json
Accept	application/json

Status Request Object

Example Status Request object

{
  "Request": {
    "Merchant": "00",
    "StatusType": "0"
  }
}

Field KeyName	Required	Description
Merchant		Two Digit Merchant Code. Defaults to '00' (EFTPOS)
Application		Indicates where the request is to be sent to. Defaults to "00" (EFTPOS)
StatusType		Type of status to perform. Defaults to '0' (standard)

Status Response HTTP Status Codes

Code	Description
200	Only for synchronous mode. The request completed and a valid response has been returned from the PIN pad. The 'success' property in the Response object indicates the actual success of the transaction.
202	Only for asynchronous mode. The request has been started. The POS should await the result in its notification postback (Asynchronous mode only). Response body will be null.
400	Invalid request. The request has not completed successfully.
401	The token supplied is invalid. The POS should refresh the token and attempt the request again
404	Resource not found. The request was not submitted successfully.
408	A transient error has occurred. The POS should allow the operator to try the request again.
500-599	A server error has occurred. The POS should allow the operator to try the request again.

Status Response Object

Example status Response object

{
  "SessionId": "df8db91bbb10d62057877b5df00a89b0",
  "ResponseType": "status",
  "Response": {
    "Merchant": "00",
    "AIIC": null,
    "NII": 0,
    "Catid": "123456",
    "Caid": "654321",
    "Timeout": 0,
    "LoggedOn": false,
    "PinPadSerialNumber": "",
    "PinPadVersion": "",
    "BankCode": " ",
    "BankDescription": "",
    "KVC": "",
    "SAFCount": 0,
    "NetworkType": "3",
    "HardwareSerial": "",
    "RetailerName": "",
    "OptionsFlags": {
      "Tipping": false,
      "PreAuth": false,
      "Completions": false,
      "CashOut": false,
      "Refund": false,
      "Balance": false,
      "Deposit": false,
      "Voucher": false,
      "MOTO": false,
      "AutoCompletion": false,
      "EFB": false,
      "EMV": false,
      "Training": false,
      "Withdrawal": false,
      "Transfer": false,
      "StartCash": false
    },
    "SAFCreditLimit": 0,
    "SAFDebitLimit": 0,
    "MaxSAF": 0,
    "KeyHandlingScheme": "2",
    "CashoutLimit": 0,
    "RefundLimit": 0,
    "CPATVersion": "",
    "NameTableVersion": "",
    "TerminalCommsType": "2",
    "CardMisreadCount": 0,
    "TotalMemoryInTerminal": 0,
    "FreeMemoryInTerminal": 0,
    "EFTTerminalType": "Unknown",
    "NumAppsInTerminal": 0,
    "NumLinesOnDisplay": 0,
    "HardwareInceptionDate": "0001-01-01T00:00:00",
    "Success": false,
    "ResponseCode": "PF",
    "ResponseText": "PINpad Offline      "
  }
}

Field KeyName	Description
Merchant	Two Digit Merchant Code. Defaults to '00' (EFTPOS)
AIIC	The AIIC that is configured in the terminal.
NII	The NII that is configured in the terminal.
CatId	The Terminal ID configured in the PIN pad
CaId	The Merchant ID configured in the PIN pad
Timeout	The bank response timeout that is configured in the terminal
LoggedOn	Indicates if the PIN pad is currently logged on
PinPadSerialNumber	The serial number of the terminal
PinPadVersion	PIN pad software version
BankCode	the bank acquirer code
BankDescriptionBankDescription	the bank description
KVC	Key Verification Code
SAFCount	Current number of stored transactions
NetworkType	The Acquirer communications type
HardwareSerial	The hardware serial number
RetailerName	The Merchant retailer name
OptionFlags	PIN pad terminal supported option flags
SAFCreditLimit	Store-and-forward credit limit
SAFDebitLimit	Store-and-forward debit limit
MaxSAF	The maximum number of store transaction
KeyHandlingScheme	The terminal key handling scheme
CashoutLimit	The maximum cash out limit
RefundLimit	The Maximum refund limit
CPATVersion	Card prefix table version
NameTableVersion	Card Name Table version
TerminalCommsType	The terminal to PC communications type
CardMisreadCount	The number of card mis-reads
TotalMemoryInTerminal	Number of memory pages in the PIN pad Terminal
FreeMemoryInTerminal	number of free memory pages in the PIN pad terminal
EFTTerminalType	The Type of the PIN pad
NumAppsInTerminal	Number of applications in the terminal
NumLinesOnDisplay	Number of available display lines on the terminal
HardwareInceptionDate	The date the hardware was incepted
Success	Indicates if the request was successful
ResponseCode	The response code of the request
ResponseText	The response text for the response code

Logon

Logon request

# replace <<token>> with the token returned from your auth request
curl -v "https://127.0.0.1/v1/sessions/$(uuidgen)/logon?async=false" \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <<token>>' \
  -H 'Accept: application/json' \
  -d '{
        "Request": {
              "LogonType": " "
            }
      }'  

var token = "<<token>>"; // replace <<token>> with the token returned from your auth request
var requestContent = new
{
  Request = new
  {
    LogonType = " "
  }
};

var request = new HttpRequestMessage(HttpMethod.Post, $"https://127.0.0.1/v1/sessions/{Guid.NewGuid().ToString()}/logon?async=false")
{
  Content = new StringContent(Newtonsoft.Json.JsonConvert.SerializeObject(requestContent), System.Text.Encoding.UTF8, "application/json")
};
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
var httpClient = new HttpClient(); // Note: in production don't create multiple HttpClient instances. Share one single instance.
HttpResponseMessage httpResponse = await httpClient.SendAsync(request);
string responseContent = await httpResponse.Content.ReadAsStringAsync();

import datetime
import uuid
import requests; # http://python-requests.org

token = '<<token>>' # replace <<token>> with the token returned from your auth request
request_payload = {
  "Request": {
    "LogonType": " "
  }
}
uri = 'https://127.0.0.1/v1/sessions/' + str(uuid.uuid4()) + '/logon?async=false'
headers = {'Authorization': 'Bearer ' + token}
response = requests.post(uri, json=request_payload, headers=headers)
response_payload = response.json()

Instruct the EFT-Client to send a logon request to the PIN pad.

URI Path

POST ~/v1/sessions/<<sessionid>>/logon&async=false

Headers

Parameter	Value
Content-Type	application/json
Accept	application/json

Logon Request Object

Example logon request object

{
  "Request": {
    "Merchant": "00",
    "LogonType": " ",
    "Application": "00",
    "ReceiptAutoPrint": "0",
    "CutReceipt": "0"
  }
}

Field KeyName	Required	Description
Merchant		Two Digit Merchant Code. Defaults to '00' (EFTPOS)
Application		Indicates where the request is to be sent to. Defaults to "00" (EFTPOS)
ReceiptAutoPrint		Indicates if the POS is to receive receipt events, default '0'.
CutReceipt		Indicates whether Linkly should cut receipts. Defaults to '0' (DontCut)
LogonType		see definition
PurchaseAnalysisData		Extended fields. See Purchase Analysis Data section for details

Logon Response HTTP Status Codes

Code	Description
200	Only for synchronous mode. The request completed and a valid response has been returned from the PIN pad. The 'success' property in the Response object indicates the actual success of the transaction.
202	Only for asynchronous mode. The request has been started. The POS should await the result in its notification postback (Asynchronous mode only). Response body will be null.
400	Invalid request. The request has not completed successfully.
401	The token supplied is invalid. The POS should refresh the token and attempt the request again
404	Resource not found. The request was not submitted successfully.
408	A transient error has occurred. The POS should allow the operator to try the request again.
500-599	A server error has occurred. The POS should allow the operator to try the request again.

Logon Response Object

Example logon Response object

{
  "SessionId": "74a5505913df3ecd53d45930a82c3fd3",
  "ResponseType": "logon",
  "Response": {
    "PinPadVersion": "100800          ",
    "Success": true,
    "ResponseCode": "00",
    "ResponseText": "APPROVED            ",
    "Date": "0001-01-01T00:00:00",
    "Catid": "12345678",
    "Caid": "0987654321     ",
    "Stan": 0,
    "PurchaseAnalysisData": {}
  }
}

Field KeyName	Description
PinPadVersion	PIN pad software version.
Success	Required. Indicates if the request was successful.
ResponseCode	The response code of the request
ResponseText	The response text for the response code
Date	Date and time of the response returned by the bank.
Catid	Terminal ID configured in the PIN pad
Caid	Merchant ID configured in the PIN pad
Stan	System Trace Audit Number
PurchaseAnalysisData	Extended fields. See Purchase Analysis Data section for details

Settlement

Settlement request

# replace <<token>> with the token returned from your auth request
curl -v "https://127.0.0.1/v1/sessions/$(uuidgen)/settlement?async=false" \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <<token>>' \
  -H 'Accept: application/json' \
  -d '{
        "Request": {
              "SettlementType": "S"
            }
      }'  

var token = "<<token>>"; // replace <<token>> with the token returned from your auth request
var requestContent = new
{
  Request = new
  {
    SettlementType = "S"
  }
};

var request = new HttpRequestMessage(HttpMethod.Post, $"https://127.0.0.1/v1/sessions/{Guid.NewGuid().ToString()}/settlement?async=false")
{
  Content = new StringContent(Newtonsoft.Json.JsonConvert.SerializeObject(requestContent), System.Text.Encoding.UTF8, "application/json")
};
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
var httpClient = new HttpClient(); // Note: in production don't create multiple HttpClient instances. Share one single instance.
HttpResponseMessage httpResponse = await httpClient.SendAsync(request);
string responseContent = await httpResponse.Content.ReadAsStringAsync();

import datetime
import uuid
import requests; # http://python-requests.org

token = '<<token>>' # replace <<token>> with the token returned from your auth request
request_payload = {
  "Request": {
    "SettlementType": "S"
  }
}
uri = 'https://127.0.0.1/v1/sessions/' + str(uuid.uuid4()) + '/settlement?async=false'
headers = {'Authorization': 'Bearer ' + token}
response = requests.post(uri, json=request_payload, headers=headers)
response_payload = response.json()

Send a settlement request.

URI Path

POST ~/v1/sessions/<<sessionid>>/settlement&async=false

Headers

Parameter	Value
Authorization	The bearer token returned from ~/v1/tokens/cloudpos
Content-Type	application/json
Accept	application/json

Settlement Request Object

Example settlement request object

{
  "Request": {
    "Merchant": "00",
    "SettlementType": "S",
    "Application": "00",
    "ReceiptAutoPrint": "0",
    "CutReceipt": "0"
  }
}

Field KeyName	Required	Description
Merchant		Two Digit Merchant Code. Defaults to '00' (EFTPOS)
Application		Indicates where the request is to be sent to. Defaults to "00" (EFTPOS)
SettlementType		Type of settlement to perform. Defaults to 'S' (Settlement)
ReceiptAutoPrint		Indicates if the POS is to receive receipt events, default '0'.
CutReceipt		Indicates whether Linkly should cut receipts. Defaults to '0' (DontCut)
ResetTotals		Reset totals after settlement. Only used for settlement type 'H' (SubShiftTotals). Defaults to false

Settlement Response HTTP Status Codes

Code	Description
200	Only for synchronous mode. The request completed and a valid response has been returned from the PIN pad. The 'success' property in the Response object indicates the actual success of the transaction.
202	Only for asynchronous mode. The request has been started. The POS should await the result in its notification postback (Asynchronous mode only). Response body will be null.
400	Invalid request. The request has not completed successfully.
401	The token supplied is invalid. The POS should refresh the token and attempt the request again
404	Resource not found. The request was not submitted successfully.
408	A transient error has occurred. The POS should allow the operator to try the request again.
500-599	A server error has occurred. The POS should allow the operator to try the request again.

Settlement Response Object

Example settlement Response object

{
  "SessionId": "7a2c33ce29b985f52f2bab7dfa4cce7d",
  "ResponseType": "settlement",
  "Response": {
    "Merchant": "00",
    "SettlementTotalsData": [
      {
        "CardName": "MasterCard",
        "PurchaseAmount": 100000,
        "PurchaseCount": 3,
        "CashOutAmount": 0,
        "CashOutCount": 0,
        "RefundAmount": 7000,
        "RefundCount": 1,
        "TotalAmount": 93000,
        "TotalCount": 4
      },
      {
        "CardName": "TOTAL",
        "PurchaseAmount": 100000,
        "PurchaseCount": 3,
        "CashOutAmount": 0,
        "CashOutCount": 0,
        "RefundAmount": 7000,
        "RefundCount": 1,
        "TotalAmount": 93000,
        "TotalCount": 4
      }
    ],
    "SettlementReport": {
      "IsPreprint": false,
      "ReceiptText": [
        "------------------------",
        "     Merchant Line 0    ",
        "     Merchant Line 1    ",
        "     Merchant Line 2    ",
        "     Merchant Line 3    ",
        "MERCH ID: 00002547000005",
        "TERM ID:        47000005",
        "BATCH NO: 07/00         ",
        "                        ",
        "                        ",
        "    SETTLEMENT REPORT   ",
        "                        ",
        "                        ",
        "PURCHASE:  x3   $1000.00",
        "CASH OUT:  x0      $0.00",
        "REFUND:    x1     $70.00",
        "NET TOTAL: x4    $930.00",
        "                        ",
        "                        ",
        "Inclusive Of            ",
        "CASHBACK:  x0      $0.00",
        "TIP:       x0      $0.00",
        "                        ",
        "                        ",
        "Card Scheme Net Totals: ",
        "MASTERCARD:x4    $930.00",
        "                        ",
        "                        ",
        "   SETTLEMENT SUCCESS   ",
        "************************",
        "*   TOTALS IN BALANCE  *",
        "*     Totals reset     *",
        "************************",
        "------------------------"
      ],
      "Type": "M"
    },
    "Success": true,
    "ResponseCode": "00",
    "ResponseText": "APPROVED"
  }
}

Field KeyName	Description
Merchant	Two Digit Merchant Code. Defaults to '00' (EFTPOS)
Success	Required. Indicates if the request was successful.
ResponseCode	The response code of the request
ResponseText	The response text for the response code
SettlementReport	Contains the receipt with settlement totals
SettlementTotalsData	JSON formatted settlement totals data returned from the bank

QueryCard

Query card request

# replace <<token>> with the token returned from your auth request
curl -v "https://127.0.0.1/v1/sessions/$(uuidgen)/querycard?async=false" \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <<token>>' \
  -H 'Accept: application/json' \
  -d '{
        "Request": {
              "QueryCardType": "0"
            }
      }'  

var token = "<<token>>"; // replace <<token>> with the token returned from your auth request
var requestContent = new
{
  Request = new
  {
    QueryCardType = "0"
  }
};

var request = new HttpRequestMessage(HttpMethod.Post, $"https://127.0.0.1/v1/sessions/{Guid.NewGuid().ToString()}/querycard?async=false")
{
  Content = new StringContent(Newtonsoft.Json.JsonConvert.SerializeObject(requestContent), System.Text.Encoding.UTF8, "application/json")
};
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
var httpClient = new HttpClient(); // Note: in production don't create multiple HttpClient instances. Share one single instance.
HttpResponseMessage httpResponse = await httpClient.SendAsync(request);
string responseContent = await httpResponse.Content.ReadAsStringAsync();

import datetime
import uuid
import requests; # http://python-requests.org

token = '<<token>>' # replace <<token>> with the token returned from your auth request
request_payload = {
  "Request": {
    "QueryCardType": "0"
  }
}
uri = 'https://127.0.0.1/v1/sessions/' + str(uuid.uuid4()) + '/querycard?async=false'
headers = {'Authorization': 'Bearer ' + token}
response = requests.post(uri, json=request_payload, headers=headers)
response_payload = response.json()

Send a query card request.

URI Path

POST ~/v1/sessions/<<sessionid>>/querycard&async=false

Headers

Parameter	Value
Content-Type	application/json
Accept	application/json

Query Card Request Object

Example querycard request object

{
  "Request": {
    "Merchant": "00",
    "QueryCardType": "0",
    "Application": "00"
  }
}

Field KeyName	Required	Description
Merchant		Two Digit Merchant Code. Defaults to '00' (EFTPOS)
Application		Indicates where the request is to be sent to. Defaults to "00" (EFTPOS)
QueryCardType		Type of querycard to perform. Defaults to '0'
PurchaseAnalysisData		Extended fields. See Purchase Analysis Data section for details

Query Card Response HTTP Status Codes

Code	Description
200	Only for synchronous mode. The request completed and a valid response has been returned from the PIN pad. The 'success' property in the Response object indicates the actual success of the transaction.
202	Only for asynchronous mode. The request has been started. The POS should await the result in its notification postback (Asynchronous mode only). Response body will be null.
400	Invalid request. The request has not completed successfully.
401	The token supplied is invalid. The POS should refresh the token and attempt the request again
404	Resource not found. The request was not submitted successfully.
408	A transient error has occurred. The POS should allow the operator to try the request again.
500-599	A server error has occurred. The POS should allow the operator to try the request again.

Query Card Response Object

Example querycard Response object

{
  "SessionId": "7a2c33ce29b985f52f2bab7dfa4cce7d",
  "ResponseType": "querycard",
  "Response": {
    "Merchant": "00",
    "IsTrack1Available": false,
    "IsTrack2Available": true,
    "IsTrack3Available": false,
    "Track1": "",
    "Track2": "1234567890=0949?,,S, YES, 05???????\u0000",
    "Track3": "",
    "CardName": "32",
    "AccountType": " ",
    "Success": true,
    "ResponseCode": "00",
    "ResponseText": "APPROVED            ",
    "PurchaseAnalysisData": {}    
  }
}

Field KeyName	Description
Merchant	Two Digit Merchant Code. Defaults to '00' (EFTPOS)
Success	Required. Indicates if the request was successful.
ResponseCode	The response code of the request
ResponseText	The response text for the response code
AccountType	Account type selected
IsTrack1Available	Indicates if track1 was read
IsTrack2Available	Indicates if track2 was read
IsTrack3Available	Indicates if track3 was read
Track1	Data encoded on track1 of the card
Track2	Data encoded on track2 of the card
Track3	Data encoded on track3 of the card
CardName	The BIN number of the card
PurchaseAnalysisData	Extended fields. See Purchase Analysis Data section for details

ConfigureMerchant

Configure merchant request

# replace <<token>> with the token returned from your auth request
curl -v "https://127.0.0.1/v1/sessions/$(uuidgen)/configuremerchant?async=false" \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <<token>>' \
  -H 'Accept: application/json' \
  -d '{
        "Request": {
              "Catid": "12345678",
              "Caid": "0123456789ABCDE"
            }
      }'  

var token = "<<token>>"; // replace <<token>> with the token returned from your auth request
var requestContent = new
{
  Request = new
  {
    Catid = "12345678",
    Caid = "0123456789ABCDE"
  }
};

var request = new HttpRequestMessage(HttpMethod.Post, $"https://127.0.0.1/v1/sessions/{Guid.NewGuid().ToString()}/configuremerchant?async=false")
{
  Content = new StringContent(Newtonsoft.Json.JsonConvert.SerializeObject(requestContent), System.Text.Encoding.UTF8, "application/json")
};
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
var httpClient = new HttpClient(); // Note: in production don't create multiple HttpClient instances. Share one single instance.
HttpResponseMessage httpResponse = await httpClient.SendAsync(request);
string responseContent = await httpResponse.Content.ReadAsStringAsync();

import datetime
import uuid
import requests; # http://python-requests.org

token = '<<token>>' # replace <<token>> with the token returned from your auth request
request_payload = {
  "Request": {
    "Catid": "12345678",
    "Caid": "0123456789ABCDE"
  }
}
uri = 'https://127.0.0.1/v1/sessions/' + str(uuid.uuid4()) + '/configuremerchant?async=false'
headers = {'Authorization': 'Bearer ' + token}
response = requests.post(uri, json=request_payload, headers=headers)
response_payload = response.json()

Send a configure merchant request.

URI Path

POST ~/v1/sessions/<<sessionid>>/configuremerchant&async=false

Headers

Parameter	Value
Authorization	The bearer token returned from ~/v1/tokens/cloudpos
Content-Type	application/json
Accept	application/json

Configure Merchant Request Object

Example configure merchant request object

{
  "Request": {
    "Merchant": "00",
    "Catid": "12345678",
    "Caid": "0123456789"
  }
}

Field KeyName	Required	Description
Merchant		Two Digit Merchant Code. Defaults to '00' (EFTPOS)
Application		Indicates where the request is to be sent to. Defaults to "00" (EFTPOS)
Catid		The terminal ID (CatID) to configure the terminal with
CaId		The merchant ID (CaID) to configure the terminal with
AIIC		The AIIC to configure the terminal with. Defaults to 0
NII		The NII to configure the terminal with. Defaults to 0
Timeout		The bank response timeout specified in seconds. Defaults to 45

Configure Merchant Response HTTP Status Codes

Code	Description
200	Only for synchronous mode. The request completed and a valid response has been returned from the PIN pad. The 'success' property in the Response object indicates the actual success of the transaction.
202	Only for asynchronous mode. The request has been started. The POS should await the result in its notification postback (Asynchronous mode only). Response body will be null.
400	Invalid request. The request has not completed successfully.
401	The token supplied is invalid. The POS should refresh the token and attempt the request again
404	Resource not found. The request was not submitted successfully.
408	A transient error has occurred. The POS should allow the operator to try the request again.
500-599	A server error has occurred. The POS should allow the operator to try the request again.

Configure Merchant Response Object

Example configure merchant Response object

{
  "SessionId": "7a2c33ce29b985f52f2bab7dfa4cce7d",
  "ResponseType": "configuremerchant",
  "Response": {
    "Merchant": "00",
    "Success": true,
    "ResponseCode": "00",
    "ResponseText": "APPROVED            "
  }
}

Field KeyName	Description
Merchant	Two Digit Merchant Code. Defaults to '00' (EFTPOS)
Success	Required. Indicates if the request was successful.
ResponseCode	The response code of the request
ResponseText	The response text for the response code

Reprint Receipt

Reprint receipt request

# replace <<token>> with the token returned from your auth request
curl -v "https://127.0.0.1/v1/sessions/$(uuidgen)/reprintreceipt?async=false" \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <<token>>' \
  -H 'Accept: application/json' \
  -d '{
        "Request": {
              "ReprintType": "2"
            }
      }'  

var token = "<<token>>"; // replace <<token>> with the token returned from your auth request
var requestContent = new
{
  Request = new
  {
    ReprintType = "2"
  }
};

var request = new HttpRequestMessage(HttpMethod.Post, $"https://127.0.0.1/v1/sessions/{Guid.NewGuid().ToString()}/reprintreceipt?async=false")
{
  Content = new StringContent(Newtonsoft.Json.JsonConvert.SerializeObject(requestContent), System.Text.Encoding.UTF8, "application/json")
};
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
var httpClient = new HttpClient(); // Note: in production don't create multiple HttpClient instances. Share one single instance.
HttpResponseMessage httpResponse = await httpClient.SendAsync(request);
string responseContent = await httpResponse.Content.ReadAsStringAsync();

import datetime
import uuid
import requests; # http://python-requests.org

token = '<<token>>' # replace <<token>> with the token returned from your auth request
request_payload = {
  "Request": {
    "ReprintType": "2"
  }
}
uri = 'https://127.0.0.1/v1/sessions/' + str(uuid.uuid4()) + '/reprintreceipt?async=false'
headers = {'Authorization': 'Bearer ' + token}
response = requests.post(uri, json=request_payload, headers=headers)
response_payload = response.json()

Send a reprint receipt request.

URI Path

POST ~/v1/sessions/<<sessionid>>/reprintreceipt&async=false

Headers

Parameter	Value
Content-Type	application/json
Accept	application/json

Reprint Receipt Request Object

Example reprint receipt request object

{
  "Request": {
    "Merchant": "00",
    "Application": "00",
    "ReceiptAutoPrint": "0",
    "ReprintType": "2",
    "Type": "M"
  }
}

Field KeyName	Required	Description
Merchant		Two Digit Merchant Code. Defaults to '00' (EFTPOS)
Application		Indicates where the request is to be sent to. Defaults to "00" (EFTPOS)
ReceiptAutoPrint		indicates whether to trigger receipt events. Defaults to '0' (POSPrinter)
CutReceipt		Indicates whether Linkly should cut receipts. Defaults to '0' (DontCut)
ReprintType		Indicates whether the receipt should be returned or reprinted. Defaults to '2' (GetLast) '1' is Reprint
OriginalTxnRef		The original txnRef of the transaction
PurchaseAnalysisData		Extended fields. See Purchase Analysis Data section for details
Type		Indicates type/copy of receipt to reprint. "M" = Merchant copy, "C" = Customer copy. Default is Customer if not specified

Reprint Receipt Response HTTP Status Codes

Code	Description
200	Only for synchronous mode. The request completed and a valid response has been returned from the PIN pad. The 'success' property in the Response object indicates the actual success of the transaction.
202	Only for asynchronous mode. The request has been started. The POS should await the result in its notification postback (Asynchronous mode only). Response body will be null.
400	Invalid request. The request has not completed successfully.
401	The token supplied is invalid. The POS should refresh the token and attempt the request again
404	Resource not found. The request was not submitted successfully.
408	A transient error has occurred. The POS should allow the operator to try the request again.
500-599	A server error has occurred. The POS should allow the operator to try the request again.

Reprint Receipt Response Object

Example reprint receipt Response object

{
  "SessionId": "7a2c33ce29b985f52f2bab7dfa4cce7d",
  "ResponseType": "reprintreceipt",
  "Response": {
    "Merchant": "00",
    "ReceiptText": [
      "------------------------",
      " *** TRAINING MODE ***  ",
      "  TEST MERCHANT TITLE   ",
      "   TEST MERCHANT NAME   ",
      "         LINE2          ",
      "                        ",
      "14:45:52 03/08/18       ",
      "                        ",
      "CREDIT ACCOUNT          ",
      "                        ",
      "PURCHASE   AUD     $1.00",
      "                --------",
      "TOTAL      AUD     $1.00",
      "                        ",
      "APPROVED -  00          ",
      "                        ",
      "PLEASE RETAIN AS RECORD ",
      "      OF PURCHASE       ",
      "------------------------"
    ],
    "Success": true,
    "ResponseCode": "00",
    "ResponseText": "APPROVED            "
  }
}

Field KeyName	Description
Merchant	Two Digit Merchant Code. Defaults to '00' (EFTPOS)
Success	Required. Indicates if the request was successful.
ResponseCode	The response code of the request
ResponseText	The response text for the response code
ReceiptText	Receipt text to be printed. Returned as an array of lines

Send Key

Send a key press from the POS to an existing active session.

# replace <<uuid>> with the UUID from your Transaction Request
# replace <<token>> with the token returned from your auth request
curl -v "https://127.0.0.1/v1/sessions/<<uuid>>/sendkey?async=false" \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <<token>>' \
  -H 'Accept: application/json' \
  -d '{
        "Request": {
              "Key": "0"
            }
      }'  

var token = "<<token>>"; // replace <<token>> with the token returned from your auth request
var uuid = "<<uuid>>"; // replace <<uuid>> with the UUID from your Transaction Request
var requestContent = new
{
  Request = new
  {
    Key = "0"
  }
};

var request = new HttpRequestMessage(HttpMethod.Post, $"https://127.0.0.1/v1/sessions/{uuid}/sendkey?async=false")
{
  Content = new StringContent(Newtonsoft.Json.JsonConvert.SerializeObject(requestContent), System.Text.Encoding.UTF8, "application/json")
};
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
var httpClient = new HttpClient(); // Note: in production don't create multiple HttpClient instances. Share one single instance.
HttpResponseMessage httpResponse = await httpClient.SendAsync(request);
string responseContent = await httpResponse.Content.ReadAsStringAsync();

import datetime
import requests; # http://python-requests.org

uuid = '<<uuid>>' # replace <<uuid>> with the UUID from your Transaction Request
token = '<<token>>' # replace <<token>> with the token returned from your auth request
request_payload = {
  "Request": {
    "Key": "0"
  }
}
uri = 'https://127.0.0.1/v1/sessions/' + uuid + '/sendkey?async=false'
headers = {'Authorization': 'Bearer ' + token}
response = requests.post(uri, json=request_payload, headers=headers)
response_payload = response.json()

Send a key press request.

URI Path

POST ~/v1/sessions/<<sessionid>>/sendkey&async=false

Headers

Parameter	Value
Content-Type	application/json
Accept	application/json

Send Key Request Object

Example send key request object

{
  "Request": {
    "Key": "0",
    "Data": ""
  }
}

Field KeyName	Required	Description
Key	true	Indicates the key to be pressed. '0' for the CANCEL key or OK key (see Note 1) '1' for the YES key '2' for the NO key '3' for the AUTH key
Data		Entry data collected by POS. Maximum length of 60 characters

Note 1:
The OK and CANCEL key are the same key. Only one can be displayed at a time.

Send Key Response HTTP Status Codes

Code	Description
200	Only for synchronous mode. The request completed and a valid response has been returned from the PIN pad. The 'success' property in the Response object indicates the actual success of the transaction.
202	Only for asynchronous mode. The request has been started. The POS should await the result in its notification postback (Asynchronous mode only). Response body will be null.
400	Invalid request. The request has not completed successfully.
401	The token supplied is invalid. The POS should refresh the token and attempt the request again
404	Resource not found. The request was not submitted successfully.
408	A transient error has occurred. The POS should allow the operator to try the request again.
500-599	A server error has occurred. The POS should allow the operator to try the request again.

Send Key Response Object

Example send key Response object

{
  "SessionId": "7a2c33ce29b985f52f2bab7dfa4cce7d",
  "ResponseType": "sendkey",
  "Response": null
}

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 Status.
Applies to configMerchant.
Note: Not supported by all acquirers.

AmtCash

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

AmtCreditLimit

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

AmtPurchase

The purchase amount for the transaction.
Returned by transaction.

AmtTip

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

Application

Value	Description
"00"	Make EFTPOS payment
"02"	Make payment using extension

Applies to Transaction.

AuthCode

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

AvailableBalance

The balance amount remaining on the card, only used on fixed value payment products.

Caid

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

CancelKeyFlag

Enables / disables the availability of the cancel button on the display.

• 0 = No cancel button
• 1 = Cancel button

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
89	Zip Money
90	TruRating
98	Reserved
99	Reserved

Catid

Card Acceptor Terminal ID.
Returned by Transaction, LogonEvent, Status.
Applies to configMerchant.

ChqAccount

Cheque Account Number.
Applies to .
NOT Used

ChqBranch

Cheque Branch Number.
Applies to .
NOT Used

ChqSerialNumber

Cheque Serial Number.
Applies to .
NOT Used

ClearedFundsBalance

The cleared funds balance amount.

CommandCode

Used to indicate what command is being passed to Linkly

• 'N' = Get last transaction

ConfigLocked

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

CurrencyCode

Currency code for this transaction (e.g. AUD) A 3-digit ISO currency code. Defaults to " "(NotSet).

CutReceipt

Set to "1" if the receipt should be cut by the printer after the receipt is printed.
"0" Don't cut

DataField

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

For the QueryCard Event
It will contain the following if it was available in the PIN pad CPAT:

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

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

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

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

For the Status, this field will contain the Extra Status information which is used in PX328 Linkly systems and onward.
For a Transaction Request, if the TxnType is set to "K", this property will contain data for the PIN pad 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 PIN pad has a SAF)
Network Type	1	'1' = Leased, '2' = Dial-up
Hardware Serial #	16	Actual Serial Number that is unique to the h/w
Retailer Name	40	AS2805 Field 43 (if supported by host)
Options Flags	32	These flags denote the support of various options within the terminal.
Stand in Credit card Limit	9	Max limit allowed for stand-in on credit cards
Stand in Debit card limit	9	Max Limit allowed for stand-in on debit cards
Max number of stand-in transactions	3
Key-handling scheme	1	'0' = Single DES '1' = Triple DES
Maximum Cash Out Limit	9	$$$$$$$cc
Maximum Refund Limit	9	$$$$$$$cc
Current CPAT version	6
Current Name table version	6
Terminal Comms Type	1	'0' = Cable, '1' = Infra-red
Card Misread Count	6
Total # memory pages	4
# free memory pages	4
EFT Terminal Type	4
# applications in terminal	2
# lines on terminal display	2
Hardware inception Date	6	DDMMYY - Date that the hardware serial number was entered into this device.

Supported Functionality Index:

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

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

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

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

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

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

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

For each CPAT entry, the following will be sent:

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

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

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

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

Name	Byte
Card Name	20
Bin #	2
Index	2

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

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

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

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

Date

Date of transaction
Returned by Transaction

DateExpiry

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

DateSettlement

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

DisplayText

An array of strings containing the text to display.

EftPosNetwork

Indicates the network to which the PIN pad is connected.
Returned by Status.

EnableTip

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

InputData

The Input Data that is returned if the POS is implementing a custom display with Input using the Display Request, maximum 20 characters. 

InputDataFieldKey

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

KeyPressed

Indicates which key is to be pressed '0' for the CANCEL key '1' for the YES key '2' for the NO key '3' for the AUTH key

KVC

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

LastTxnSuccess

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

LineLength

The length of the lines in the display.

LoggedOn

Set to True if the PIN pad 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 PIN pad as auto-logons are performed.
Returned by Status.

LogonType

The type of logon to perform.

Value	Description
" "	Standard
"4"	RSA logon
"5"	TMSFull
"6"	TMSParams
"7"	TMSSoftware
"8"	Logoff
"1"	Diagnostics

Merchant

Indicates the active merchant. (Reserved for future use) - Currently only merchant '00' is supported and setting this property to any other value will result in an error.

Value	Description
"00"	Default value to indicate EFTPOS
"65"	AfterPay payment
"66"	Alipay payment
"67"	Humm payment
"89"	ZipMoney payment

Applies to Transaction, Logon, Settlement, and Status.

MessageType

A property to represent:
- The Message type returned by Transaction.
- The Subcode to select in a Status request.
- The resulting subcode in a Status

Nii

EFTPOS Network International Identifier.
Returned by Status.
Applies to ConfigMerchant.
Note: Not supported by all acquirers.

NumberOfLines

The number of lines in the display.

OkKeyFlag

Enables / disables the availability of the OK button on the display.

• 0 = No OK button
• 1 = OK button

Pan

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

PanSource

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

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

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

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

Applies to Transaction.

PinPadPort

The port to which the PIN pad is attached. On input, this property may be used to set the specific PIN pad port to use. On output, it indicates the PIN pad port used for the transaction.
Applies to Transaction, Logon, Settlement
Note: Not supported by all acquirers.

PinPadSerialNumber

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

PinPadVersion

The PIN pad software name and version (Up to 16 characters).
Returned by Status

PHN

Humm only. Customer phone number. Applies to Humm Invite

QueryCardType

The type of query to perform during a QueryCard request

Value	Description
"0"	Read card only
"1"	read card + select account
"5"	select account only
"7"	pre-swipe
"8"	Preswipe special

Receipt

Formatted EFTPOS receipt information (Up to 2048 characters).
Returned by PrintReceipt, GetLastReceipt.

ReceiptAutoPrint

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

Type

Type	Description
"M"	Request Merchant receipt copy
"C"	Request Cardholder/Customer copy
not set	defaults to Cardholder copy

ResetTotals

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

ResponseCode

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

ResponseText

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

ResponseType

The type of response that is being returned. This can be used to help sort responses sent to POS postback endpoints.

ResponseType
transaction
logon
settlement
status
querycard
configuremerchant
reprintreceipt
display
receipt

RRN

Retrieval Reference Number this value is used to trace transactions.

SettlementReport

Formatted EFTPOS receipt information with settlement report (Up to 2048 characters).
Returned by Settlement, Settlement.

SettlementTotalsData

JSON array of settlement data for each card type settled. Each card record contains different amounts as follows:
- Card Name
- Purchase Amount
- Purchase Count
- Cash-Out Amount
- Cash-Out Count
- Refund Amount
- Refund Count
- Totals Amount
- Totals Count

Note: There will be one entry ("CardName": "TOTAL") in the array with totals of every card type settled.

Returned by Settlement.

SettlementType

Value	Description
"S"	Settlement
"P"	Pre-Settlement
"L"	Last Settlement
"U"	Sub Totals or Summary Totals for ANZ
"H"	Shift Totals or Subtotals for ANZ
"I"	Txn Listing
"M"	Start Cash
"F"	Store and forward (SAF) totals report
"D"	Daily cash statement (STG Agency)

Stan

The Systems Trace Audit Number of the last transaction performed. (0-999999).
Returned by Transaction, GetLastTransaction, Logon.

StatusType

The type of status to perform

Value	Description
"0"	Standard
"1"	TerminalAppInfo
"2"	AppCPAT
"3"	AppNameTable
"4"	Undefined
"5"	Preswipe

SubCode

Used to control behaviour of methods:

Reprint receipt Indicates to reprint or retrieve (sent to POS)

• '1' = reprint receipt
• '2' = get last receipt

Get last transaction

• '0' = Standard request

Success

Boolean value indicating success or failure of relevant event/method call. E.g., if the request was of type transaction, this flag indicates that the financial transaction (sale) succeeded. Returned by all events.

Time

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

Timeout

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

TotalsData

A totals record containing the locally stored terminal totals.

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

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

For each charge card:

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

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

Returned by Settlement.

Track1

Contents of magnetic card track 1 or 3, if either is read by the PIN pad.
Returned by QueryCard.

TotalPurchaseCount

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

Track2

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

TxnFlags

The transaction flags that apply to the transaction

• "Offline" = 0/1
• "ReceiptPrinted" = 0/1
• "CardEntry" = '0' = unknown; 'S' = Swiped; 'K' = Keyed 'C' = Contactless Chip card 'E' = Contact Chip Card
• "CommsMethod" = '1' = P66, '2' = Argent, '3' = X25, '4'&'5' = HostEm, '6' = Non-EFT
• "Currency" = '0' = AUD, '1' = Converted Currency. (Transfer Data will contain Currency Code, Amount and Exponent if this is set).
• "PayPass" = '0' = Non Paypass '1' = Paypass.
• "UndefinedFlag6" = 0/?
• "UndefinedFlag7" = 0/?

TxnRef

Application supplied reference number up to 16 characters in length. TxnRef can contain any ascii characters between 32 and 127 (decimal).

Returned by Transaction, GetLastTransaction.
Applies to Transaction.

TxnType

This property should be set to indicate the type of transaction to be performed when calling Transaction or Settlement.
See Appendix E - Txn type

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
67 / ??	Humm
70 / OPN	OpenPay
?? / 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.
E.g. 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
78, 79, XG	SYSTEM ERROR	ANZ Specific: Bank configuration issue
97	ALREADY SETTLED	PIN pad already has been settled
B1	PRINTER ERROR	Linkly setup to handle printing, but no printer defined
BB / BY	Client/Pinpad Busy	Pinpad/client are processing
N8	SERVER ERROR	Invalid TID entered into the PIN pad
P7	COMMS ERROR	Comms issue with the PIN pad or the EFT server
PF	Pinpad Offline	Pinpad is offline
S0	MODEM ERROR	(Should be CBA only) Generic Connection error - can't connect to the bank
S7	NO EFT SERVER	Linkly EFT Client is not connecting to EFT Server
S8	NO EFT SERVER	Error in the lines tab of the EFT Server
TB	TMS REQUIRED	PIN pad needs to logon to TMS
TF	INIT REQUIRED	PIN pad needs to be logged on
TI	Operator Timeout	Input timeout
TM	Operator Cancelled	Operator cancelled sale
TX	Unable to Process	Reversal failed to process
X0	NO RESPONSE	Bank not responding to the terminal
X0J	No Response	Message timeout
X2	System Error	Internal Error
XG	Txn Not Supported	Txntype is not supported
XT	CONFIG REQUIRED	PIN pad not configured with TID/MID
Z0	Modem Error	No connection from eftsrv
Z5	Power Fail	The PINpad has lost power/recovered from a powerFail
ZB	PINPAD BUSY	ANZ Specific: PIN pad is not ready to accept transaction

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

AppHub Response Codes

Response Code	Response Text	Description
99	General Decline	Unexpected Error
97	Auth Error	Linkly Auth Error – Token is invalid
H0	Config Required	Lane Info/Third party host credentials are missing
H1	POS Format Error	POS has sent a wrong/missing field in the request
HA	Invalid Amount	The Amount does not match Third party requirements
HB	Insufficient Funds	The customer account does not have sufficient funds for the transaction
HC	Host Format Error	The message is incorrect to the third party
HD	Txn Cancelled	The txn has been cancelled
HE	Bad Read	The card data/barcode provided is invalid
HG	Host Auth Error	Authentication error from the third party
HH	Txn Not Found	The txn reference does not exist on the third party system
HI	Expired payment	The barcode/QR code/card has expired and cannot be processed
HL	Host Internal Error	Internal error on the third party system
HM	Activation Error	Third party activation error
HN	Account In Use	The account/payment authenticator is already in use
HQ	Account Funds Error	There is a funds error with the specified account
HR	Already processed	The specific sale is already processed
HS	Account Error	There is an issue with the customer account

Appendix C - Purchase Analysis Data

{
  ...,
  "PurchaseAnalysisData": {
    "<TagName>": "<tagValue>",
    "PAT": "1"
  }
}

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

Only use this field if instructed by Linkly.

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

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

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

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

Silent Card Not Supported In Transaction

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

Limit Account Selection

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

Operator Display Prompts

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

Field 48 Data

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

Myer Specific

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

Tip value passed from POS

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

Amount tag

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

SKU tag

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

Unique Card Identifier

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

Available Balance

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

Cleared Funds Balance

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

Operator Reference

• The operator reference.
• TAG:
  
  • OPR
    
• Direction
  • POS --> Linkly
• Transaction Types Supported:
  
  • Transaction Requests
    

Unique Identifier

• The unique identifier for the transaction, this should be unique for the given transaction.
• TAG:
  
  • UID
    
• Direction
  • POS --> Linkly
• Transaction Types Supported:
  
  • Transaction Requests
    

POS Name

• The POS name, this must match the name used for the Linkly accreditation.
• TAG:
  
  • NME
    
• Direction
  • POS --> Linkly
• Transaction Types Supported:
  
  • Transaction Requests
    

POS Version

• The POS version.
• TAG:
  
  • VER
• Direction
  • POS --> Linkly
• Transaction Types Supported:
  
  • Transaction Requests
    

POS Vendor ID

• The POS vendor ID, this must match the ID supplied by Linkly during accreditation.
• TAG:
  
  • VND
    
• Direction
  • POS --> Linkly
• Transaction Types Supported:
  
  • Transaction Requests
    

POS Capabilities Matrix

• The POS capabilities matrix:
  1. Byte 1 - 1=POS has barcode scanner, 0=No barcode scanner
• TAG:
  
  • PCM
    
• Direction
  • POS --> Linkly
• Transaction Types Supported:
  
  • Transaction Requests
    

Purchase REF

• Reference of the extension purchase. It's returned in "PurchaseAnalysisData" of Transaction Response. It's used to refund an extension transaction.
  
• TAG:
  
  • REF
    
• Direction
  • Linkly --> POS
  • POS --> Linkly
• Transaction Types Supported:
  
  • Purchase
  • Refund
• Notes
  • Returned by AfterPay Purchase as AfterPay Order Id
    
  • Returned by Alipay Purchase as Alipay Trade Number
    
  • Returned by Humm Purchase as Humm Purchase Number
    
  • Returned by ZipMoney Purchase as ZipMoney Order Id
    

Host Response Code

• The host supplied response code, this can be useful for providing more detailed transaction information to the customer and merchant.
  
• TAG:
  
  • HRC
    
• Direction
  • Linkly --> POS
• Transaction Types Supported:
  
  • Transaction Responses

Host Response Text

• The host supplied response text, this can be useful for providing more detailed transaction information to the customer and merchant.
  
• TAG:
  
  • HRT
    
• Direction
  • Linkly --> POS
• Transaction Types Supported:
  
  • Transaction Responses

Appendix D - Application Codes

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

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

Appendix E - 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 PAN) - 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 PIN pad The following properties can be set prior to this call: - amtpurchase. - txnref - PANSource - track2 (as returned in original request) - dateExpiry (if manually keyed) - Pan (if manually keyed) - AccountType (as returned in original request) - DataField
I	Void

Settlement Types

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

Returned by TransactionEvent and SettlementEvent.
Applies to DoTransaction and DoSettlement.
Note: Not all TxnTypes are supported by all acquirers.

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

---