LocalLink

Introduction

LocalLink is an application that runs directly on PAX payment terminals and manages communication with third-party ECR/EPOS systems over a local network. It exposes a REST API on the terminal, providing a secure and straightforward way for ECR systems to interact with the payment terminal via USB or local wifi.

This documentation includes:

A general overview of how the communication flow works
Detailed instructions for integrating with LocalLink
A C# test application demonstrating how to communicate with the terminal, including both setup instructions and sample code
A Postman collection that can be imported directly and covers all available features

LocalLink Transaction Flow

Click here to download the test app.

Figura 9. LocalLink - Test App

Figura 10. Pair Terminal to Test Application

Figura 11. Transaction Flow Sale

Transaction Flow Sale

Sample 1

{
"appName":"4D4320435245444954",
"applicationId":"A0000000041010",
"authCode":"814113",
"cardholderReceipt":[See next sample],
"cardholderVerificationMethod":"CVM_NO_CVM",
"currencyCode":"826",
"dccAmount":0,
"dccCommissionAmount":0,
"dccExchangeRate":0.0,
"dccTransaction":false,
"id":24,
"isCustomCardData":false,
"merchantId":"800574917121001",
"merchantReceipt":[See next sample],
"messageId":3,
"primaryAccountNumber":"541333******0036",
"signature":false,
"statuses":„
[\"Transaction started\",
\"Contactless card read\",
\"Contactless card read\",
\"Transaction approved\",
\"Transaction finished\"]",
"terminalId":"34550535",
"tipAmount":0,
"totalAmount":"100",
"transApproved":true,
"transCancelled":false,
"transSource":"500",
"transactionDate":"Nov 22, 2023 13:35:18",
"transactionResponse":"00",
"transactionSource":"PICC",
"transactionType":"SALE",
"uti":"40b46f56-9aab-44fa-8c19-c682895ca51c",
"voided":false
}

Sample 2

{
"cardholderReceipt":[
["CARDHOLDER COPY","5","C","B"],
[],
["Valitor test","5","L","B"],
["#{ADDR1}","5","L","B"],
["#{ADDR2}","5","L","B"],
[],
["22/11/23","13:35","5","S","N"],
["MC CREDIT","9","L","I"],
["************0036","5","L","N"],
[],
["AUTHORISED - 814113","5","C","B"],
[],
[],
[],
["SALE","5","C","N"],
["Amount","9","C","B"],
["£1.00","9","C","B"],
["NO VERIFICATION","5","L","N"],
["CONTACTLESS","5","L","N"],
["ReceiptNo: 3","1","L","N"],
["***********1001","*****535","1","S","N"],
["A0000000041010","1","L","N"],
[]
],
"merchantReceipt":[
["MERCHANT COPY","5","C","B"],
[],
["Valitor test","5","L","B"],
[„Dalshraun 3","5","L","B"],
[„220 Hafnarfjörður","5","L","B"],
[],
["22/11/23","13:35","5","S","N"],
["MC CREDIT","9","L","I"],
["541333******0036","5","L","N"],
[],
["AUTHORISED - 814113","5","C","B"],
[],
[],
[],
["SALE","5","C","N"],
["Amount","9","C","B"],
["£1.00","9","C","B"],
["NO VERIFICATION","5","L","N"],
["CONTACTLESS","5","L","N"],
["ReceiptNo: 3","1","L","N"],
["800574917121001",
"34550535","1","S","N"],
["A0000000041010","1","L","N"],[]
]
}

LocalLink Detailed Instructions

The terminal listens on port 8080.
Launch the LocalLink application on the terminal.
In your system, enter the IP address displayed at the bottom of the terminal screen.
Enter the terminal serial number shown on the barcode label at the bottom of the device.
In the LocalLink app, select “Pair”.
Enter the pairing code into your system, then send a GET – PairRequest.
The pairing response will return an authToken, which must be included in the request header for all subsequent API calls.
When submitting a sale request, a UTI is returned. This UTI is then used to query the transaction status via GetRequest.

Printing With LocalLink

All app2app receipts use the same format. You can also use this format and send strings to the Rapyd core app to get your strings printed. The text format is as follows:

Tabla 7. App2App Printing Text Formatting

[“Text”, “size”, “location”, “style”]

Or with two text strings in one line:

[“Text left”, “text right”, “size”, “location”, “style”]

Size:

* 1 = Small

* 5 = Medium (default)

* 9 = Tall

Location (both upper- and lower-case letters work):

* L = Left justified (default)

* C = Center text

* R = Right justified

* S = Split (two texts in the line)

Style (both upper- and lower-case letters work):

* N = Normal (default)

* B = Bold

* I = Italic

* U = Underline

If you just send [“text”] then the default size, location, and style values are used.

An empty line is []

Test string:

["Cardholder copy", "5", "C", "B"]

["dagsetning", "timi", "5", "s", "n“]

List of Endpoints

Setup

To setup a Locallink terminal, press the pair button on first startup. Send a pairing request with the displayed pairing code, retrieve the auth bearer token and pass it in with all further requests. The available endpoints are in the following table:

Endpoint	URL parameters	Request body	Description
`GET /locallink/1.0.0/pair`	`pairingCode` - The pairing code shown on the device `tid`- The terminal serial number	Not applicable.	Request used to pair a device. The pairing code shown on the device needs to bent. An auth bearer token is returned in the response body, this needs to be sent with all further requests. Response { "authToken": "9543623770051381" }
`POST /locallink/1.0.0/transaction`	`disablePrinting` - Set to true to not print on device `tid` - The terminal serial number	Payload { "transType": "SALE", // Possible values are: SALE, REFUND, PREAUTH, COMPLETION "amountTrans": 500000, // The amount as a long with two minor units. "amountCashback": 0, // The cashback amount if a cashback transaction is performed "firstSix": "476173", // Only for completions "lastFour": "0036", // Only for completions "authCode": "668268", // Only for completions "messageId": "137" // Only for completions }	Request to start a transaction. Locallink will respond with a 200 with the following body if transaction is successfully started: Response "transType": "SALE", "amountTrans": 500000, "amountCashback": 0, "uti": "d1a6d9d0-ce61-4e27-a077-834e77e6e7a5" } The uti needs to be used when calling the GET endpoint to get the transaction status.
`GET /locallink/1.0.0/transaction`	`tid`- The terminal serial number `uti` - The UTI of the transaction to get status update for.	Not applicable.	Request to see the status of a transaction. The uti of the transaction is passed in as an URL parameter. Returns 400 if transaction is not found or a 200 with the transaction status/result in the response body. For custom card transactions the following response body will be returned. In this case the caller should send the result to the result endpoint. Response "isCustomCardTransaction":true, "cardData":9352305800032822 // The full PAN of the card }
`DELETE /locallink/1.0.0/transaction`	`tid` - The terminal serial number	Not applicable.	Request used to cancel an ongoing transaction. A transaction can only be canceled before card has been read. Sending cancel after card read or when no transaction is ongoing will have no effect.
`POST /locallink/1.0.0/result`	`tid` - The terminal serial number `uti` - The UTI of the transaction to approve or decline.	Example { "result": "APPROVED" // Sent value is either APPROVED or DECLINED }	Request to approve or decline a custom card transaction. E.g. a bonus card where the authorization is handled by some internal system. The POS will show the passed in result on the screen.
`GET /locallink/1.0.0/report`	`tid` - The terminal serial number `disablePrinting` - Set to true to not print on device `reportType` - XReport and ZReport are the only supported values.	Not applicable.	Request to send the EOD report for the terminal. Setting `disablePrinting` to false will make the terminal print a receipt with the EOD report. For the ZReport the result object will look like, empty result objects means that the request failed: Response { "result": { "MasterCard": { "currency": "ISK", "saleCount": "3", "saleAmount": 11000, "refundCount": "0", "refundAmount": 0 }, "Totals": { "currency": "ISK", "saleCount": "3", "saleAmount": 11000, "refundCount": "0", "refundAmount": 0 } } } For the XReport the result will look as follows: Response { "totalRefunds": 0, "totalSales": 1000, "totalTip": 0 }
`GET /locallink/1.0.0/status`	`tid` - The terminal serial number	Not applicable.	Request to check if the terminal is available to received a command. Terminal will respond with the following: Result { "result": "TERMINAL_APPROVED" or "TERMINAL_BUSY" }

Transaction Result Example

{
    "appName": "5649534120435245444954",
    "applicationId": "A0000000031010",
    "authCode": "796516",
    "cardholderReceipt": , // Cardholder receipt, hidden for brewity
    "cardholderVerificationMethod": "CVM_NO_CVM",
    "currencyCode": "352",
    "dccAmount": 0,
    "dccCommissionAmount": 0,
    "dccExchangeRate": 0.0,
    "dccTransaction": false,
    "id": 48,
    "isCustomCardData": false,
    "merchantId": "800573916121001",
    "merchantReceipt": , // Merchant receipt, hidden for brewity
    "messageId": 341,
    "primaryAccountNumber": "476173******0010",
    "signature": false,
    "statuses": "[\"Transaction started\",\"Contactless card read\",\"Transaction approved\",\"Transaction finished\"]",
    "terminalId": "34550576",
    "tipAmount": 0,
    "totalAmount": "500000",
    "transSource": "400",
    "transactionDate": "Oct 5, 2023 9:21:58 AM",
    "transactionResponse": "00",
    "transactionSource": "PICC",
    "transactionType": "SALE",
    "uti": "9e3b9d36-1bcb-4261-b944-8cf1f88777f7"
}

Postman Collection

Click here to download the LocalLink Postman collection.

Figura 12. Postman Tests Included

En esta sección:

Documentación