Getting started

About

Use the PayTec Terminal Web API to access your PayTec POS Terminal from any web-based application.

• Works from any modern web browser
• Terminal and client may run in separate networks, e.g. cash register in LAN and terminal on 4G
• Keeps connection while roaming between networks
• Can also be used when running your web application on a PayTec Android terminal
• Secure TLS 1.2 connection

A comprehensive example application can be found here.

Prerequisites

To access your POS terminal via web, the following is needed:

• PayTec POS terminal with PayTec EP2 software equal or higher than 16.00.00
• Configured cash register integration type: 'KIT'

Terminal simulator

To start development, you can use the PayTec Terminal Simulator.

The terminal simulator is a web based tool that simulates the terminal part of our cloud based cash register interface. This lets you start your integration without the need of a physical terminal.

** Note **: The PayTec Virtual Terminal Simulator is a valuable tool for testing and development purposes. However, it is important to be aware of the following differences when compared to a physical POS terminal:

• Missing features: The simulator may not include all features present in a physical terminal, including but not limited to automatically triggered actions, tip entry, reference based transactions, petrol use cases
• Different timing behavior: The timing behavior and status notifications during operations in the simulator may vary from that of a physical terminal.
• Receipt differences: Receipt content may slightly differ between the simulator and an actual terminal.

Keep these differences in mind while utilizing the terminal simulator for your testing and development. For finishing and testing the integration, a physical terminal will be needed.

Embed the API

From a web page

At the end of your HTML code, embed the API as a script:

<script src="//ecritf.paytec.ch/api/v1.0/ecritf.js"></script>

Instantiate a POSTerminal object using its constructor:

trm = new PayTec.POSTerminal(undefined, { OnConnected: onConnected, ... });

From NPM-based frameworks

Add @paytecag/ecritf to your package dependencies:

npm i -save @paytecag/ecritf

Import and instantiate a POSTerminal object:

import POSTerminal from '@paytecag/ecritf';

trm = new POSTerminal(undefined, { OnConnected: onConnected, ... });

There is a very basic example available for react-native. For a more comprehensive sight on how to use the SDK, please consider the web example.

Pairing

Before a web application can communicate with a remote POS terminal, it establishes a trusted connection providing a temporary pairing code. This code is generated on the POS terminal via the attendant menu...

click 'Go' =>

... and used by the web application via the pair method:

trm.pair("6017087", "Awesome POS 1234");

=> the following message will be shown for a few seconds on the terminal:

// store the current pairing info in local browser storage
function onConnected() {
    if (typeof(Storage) !== "undefined") {
        localStorage.setItem("pairingInfo", JSON.stringify(trm.getPairingInfo()));
    }
}

// reuse it in a later session
var pairingInfo;

if (typeof(Storage) !== "undefined") {
    let info = localStorage.getItem("pairingInfo");

    if (info !== undefined) {
        pairingInfo = JSON.parse(info);
    }
}

trm = new PayTec.POSTerminal(pairingInfo, ...

Once pairing was successful, pairing info can be retrieved and stored for further sessions.

Transactions

function onTransactionApproved() {
    console.log("All ok\n");
}

trm.setOnTransactionApproved(onTransactionApproved);

if (trm.canPerformTransactions()) {
    trm.startTransaction({
            TrxFunction: trm.TransactionFunctions.PURCHASE,
            TrxCurrC: 756,
            AmtAuth: 1000
        }
    );
}

Once activated, the terminal is ready to start a transaction. The result of this operation is reported through the OnTransactionApproved, OnTransactionDeclined, OnTransactionaborted and OnTransactionReferred callback functions.

POSTerminal

This object represents the POS terminal to interact with.

Constructor

trm = new PayTec.POSTerminal(pairingInfo, options);

// not yet paired:
trm = new PayTec.POSTerminal(
    undefined,
    {
        TrmLng: 'en',
        PrinterWidth: 34,
        OnConnected: myOnConnected
    }
);

// pairing info available e.g. from local storage:
trm = new PayTec.POSTerminal(
    JSON.parse(localStorage.getItem("pairingInfo")),
    options
);

pair

trm.pair(code, friendlyName);

trm.pair("6017087", "Awesome POS 1234");

Establishes a trusted connection between the web application and the POS terminal.

unpair

trm.unpair();

Disconnects from the terminal and removes any pairing info from the POSTerminal object.

connect

trm.connect();

Connects the POSTerminal object with its physical counterpart.

disconnect

trm.disconnect();

Disconnects from the terminal and removes any pairing info from the POSTerminal object.

activate

trm.activate()

Activates the terminal to get ready for transaction processing.

deactivate

trm.deactivate()

Deactivates the terminal. In deactivated state, no transactions can be done.

startTransaction

trm.startTransaction(params)

trm.startTransaction({
        TrxFunction: trm.TransactionFunctions.PURCHASE_WITH_CASHBACK,
        TrxCurrC: 756,
        AmtAuth: 1575,
        AmtOther: 1000
    });

Starts a new payment transaction.

Parameters:

abortTransaction

trm.abortTransaction(params)

trm.abortTransaction({
        TrxAbortFlags: trm.TransactionAbortFlags.ABORT_TRX_SILENT
    }
);

Aborts a ongoing payment transaction.

confirmTransaction

trm.confirmTransaction(params)

trm.confirmTransaction({
        TrxAmt: 500,
        TrxSeqCnt: 1234
    });

Confirms a successfully authorized payment transaction. Without this, no money will be transferred from the cardholder's to the merchant's account, and the authorized amount is finally reverted.

rollbackTransaction

trm.rollbackTransaction(params)

trm.rollbackTransaction({ TrxSeqCnt: 1234 });

Cancels an approved but not yet confirmed transaction, e.g. if a vending machine cannot deliver the purchased goods.

balance

trm.balance()

Triggers the final balance procedure.

configure

trm.configure()

Lets the terminal download its configuration data from the Service Center/TMS.

initialize

trm.initialize(acqID)

Advises the terminal to update its initialization data from its acquirer(s). If acqID is -1, all acquirers will be reinitialized.

requestReceipt

trm.requestReceipt(params)

trm.requestReceipt({
        ReceiptType: trm.ReceiptTypes.TRX_COPY,
        ReceiptID: 1234
    });

Request a certain receipt from the terminal. When the receipt is available, OnReceipt will be called.

print

trm.print(params)

trm.print({
        ReceiptText: "THE QUICK BROWN FOX",
        ReceiptFlags: trm.ReceiptFlags.MORE_DATA_AVAILABLE
                    | trm.ReceiptFlags.DOUBLE_HEIGHT
    });

trm.print({
        ReceiptText: "jumps over\nthe lazy dog"
    });

trm.print({
        ReceiptText: "iVBORw0KGgoAAAANSUhEUgAAAHgAAAAlCAYAAACJdC37AAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAAFiIAABYiARsWgo8AAASRSURBVHhe7ZxdU90gEIZztDq2Y79rO73qdfv/f4veO9Oq9atV69haa9+Xs0SChEAgCefoM8NAwrIsLCAJOc6qqrpFGJ3b20GqPZ/NZs8lXRQDtbeTGSrOUjM6VlLhoOqfiF7Or8qhT1u6KNnBNxJ7QaesSjKakRof1A6S0pY2SnZwbg7RgVuSVsCEc0RFLq1tmLN8KueFMIWDFfYyWHInuVgUB69IPDqL5tBFZTIH29gz+pE8FONgF3R6W/BwJiGWM9Hbp2wop3Y7dEiAexpTz3d1V5jsbzCxG0ZTYhtrm2+Wj2labLlI+RPIv5G0l0Cbg/UVPYNDMDs6Ae7iB4H2hTqDdLUnVl+xDsZIPuZobgnHIqZo65SuztJArn5Eo/5cuOqH/hOjHc76Ytpj69JB5xWzRPcxo618rN4+doSUMWWIT3eXbIwuk8lmsG1wBi4lLoJYhzjyjyS+R6hzySQO7jsafUDnM0k26BpIZj7suJBkVkLbB7lDSdKud5LsbIOPnA4+oiEhYWgSBsymxFPReIXrAm3jAU0w2RwMx9UjLhQY+yPBGSVzKvEQRJ2+TfY3WBz7Sl34aV0ZQvHInkhMe7I5BfW9lqTCtLkr5CbbLto2LlFtr4N7u07TJpc9Xfk+fGXtvuiL1ptkJwrElWghxQiTlM6x6+2yKanjPGXtNqT0B0mxc7Il2oXdMYQN8gUfyK+XYIfu+mUJ5KI2LotEUQ42CXFgAK2v9ODwt5IkWT8bKmnAlOTgMTqlfs4cmCG/M4t6Vi/mb7C9hIbqCKnXlkm1lXTpsPJ5BPlifhWPqYvE2FzMDIbRY82u0YGDejuXoG/qvUQsJS3RnW9xbOyR3QY6qD4ODC2Tij3LEutt7CVidBW7yepohPqKIQLnM3XMUtcH6G8cGNBmj92XOt8l4xowHl13X3mgYJZWmpWlqPQY3YmvXpfeXHZ26Ln3mXAIbTpj+6e4GRza6ZSLcZAtG1M2ka2cdcXqyuZgVqxDKoauxuaC1zpPo6/Ne2MQW68pj2C368zKlxw3lmz9Dh3pIytv2i86xiRiSV0qit1kPZKHB+Hghzp7ydI7OHbXuWwstYNt51qz9wr59a8AkN5H2EH4JdfqzZodE6QPEDW+pcY9bpzUhgdpPv+qjZSU0xuh+sNAkWFMoxofG+DeHsI2wje5rk++kD5AYKxsR8zHMObrupUsYqV/aAfzN7mjBTSKDauDiWNp3kAwfwd8A5nPiLcRviK9pu7ewb76O0+qtP0TF+bpLzlWUb+WZcX6PgfVMQKd829+q6IzrxGrwxak91D3R4QvuFznPQOW+yBt0YNiBdc8GVN1MA0dl4jVJ1RDO5gdOGZwgsY6T6qkM/RMXEd6F/EmYp4GNT4nElk6guktkWnjGjLvJf1EYrJBPZKn+36N19D3VK5N9CBQspBROhEz0q8vVbtxz3yXfyVxUY9Jg/x/DV/zUB9/PWGeC2vunf5Als+YalaYaRfI30U+VwjtEFc9dJ45wTh41KoBea4itJ2zWOlDdGFc7yDN1UaB631Ev3Hv0/xO9QcBs7+q/gO+N9k5oy3IOgAAAABJRU5ErkJggg==",
        ReceiptFlags: trm.ReceiptFlags.IS_PNG_IMAGE
    });

Prints a text on the terminal's thermal printer.

deviceCommand

trm.deviceCommand(params)

trm.deviceCommand({
        DeviceCommandCode: trm.DeviceCommands.REBOOT
    }
);

trm.deviceCommand({
        DeviceCommandCode: trm.DeviceCommands.SCAN_SYMBOL,
        Title: "POS Scanner",
        Text: "Please scan QR or bar code!",
        Timeout: 60000
    }
);

Let the terminal perform some actions in addition to payment.

Request format:

Response format (when onDeviceCommandSucceeded is called):

sendMessage

trm.sendMessage(message)

Sends a JSON message to the terminal. This function is meant for use cases not yet reflected in the API.

supportsAcqID

trm.supportsAcqID(trxFunction)

Tells whether a transaction function supports an Acquirer Identifier.

needsAcqID

trm.needsAcqID(trxFunction)

Tells whether a transaction function needs an Acquirer Identifier.

needsAmtAuth

trm.needsAmtAuth(trxFunction)

Tells whether a transaction function needs an Amount, Authorised.

needsAmount

trm.needsAmount(trxFunction)

Alias for needsAmtAuth.

needsAmtOther

trm.needsAmtOther(trxFunction)

Tells whether a transaction function needs an Amount, Other (cashback amount).

needsAuthC

trm.needsAuthC(trxFunction)

Tells whether a transaction function needs an Authorisation Code.

supportsTrxRefNum

trm.supportsTrxRefNum(trxFunction)

Tells whether a transaction function supports a Transaction Reference Number.

needsTrxRefNum

trm.needsTrxRefNum(trxFunction)

Tells whether a transaction function needs a Transaction Reference Number.

supportsTrxReasonC

trm.supportsTrxReasonC(trxFunction)

Tells whether a transaction function supports a Transaction Reason Code.

hasPairing

trm.hasPairing()

Tells whether the API has been provisioned with pairing data.

getPairingInfo

trm.getPairingInfo()

Returns the pairing data in JSON form.

getSerialNumber

trm.getSerialNumber()

Returns the terminal's device serial number.

getTerminalID

trm.getTerminalID()

Returns the Terminal Identification within the payment system.

getDeviceModelName

trm.getDeviceModelName()

Returns the device model name of the terminal.

getSoftwareVersion

trm.getSoftwareVersion()

v = trm.getSoftwareVersion();

console.log("Software version: "
    + Math.trunc(v / 10000) + "."
    + Math.trunc((v % 10000) / 100) + "."
    + Math.trunc(v % 100));

returns the terminal software version as a number.

getStatus

status = trm.getStatus()

Gets the terminal status as a combination of flags.

getActSeqCnt

actSeqCnt = trm.getActSeqCnt()

Returns the current Activation Sequence Counter which will be increased whenever a new shift is opened via activate.

getPeSeqCnt

peSeqCnt = trm.getPeSeqCnt()

Returns the current Period Sequence Counter which will be increased whenever a new booking period is opened by calling activate after balance.

canPerformTransactions

var ready = trm.canPerformTransactions()

Tells whether the terminal is activated, not locked and not busy with another use case.

getAcquirers

trm.getAcquirers()

trm.getAcquirers();
-> [ 1, 4 ]

Return an array containing the configured acquirer IDs.

getAcquirerInfo

trm.getAcquirerInfo(acqID)

trm.getAcquirerInfo(4)
->
{
    AcqID: 4,
    LastAcqInitDate: "2019-05-26 06:32:26"
}

Returns information to a given acquirer ID as an object.

getBrands

trm.getBrands()

trm.getBrands();
-> [ "MAESTRO", "MASTERCARD", "V PAY", "VISA" ]

Returns an array containing the initialized payment brands

getCurrencies

trm.getCurrencies()

trm.getCurrencies();
-> [ 756, 840, 978 ]

Returns an array of supported ISO-4217 currency codes.

getTransactionFunctions

trm.getTransactionFunctions()

trm.getTransactionFunctions();
-> [ 32768, 2048, 32 ]

Returns an array of supported transaction functions.

getTransactionFunctionName

trm.getTransactionFunctionName(trxFunction, language)

trm.getTransactionFunctionName(
    trm.TransactionFunctions.PURCHASE_RESERVATION, "fr");

-> "Vente Réservation"

Returns the name of a transaction function in English, German, French or Italian. If language is undefined, the current terminal language is used.

POSID

trm.getPOSID()
trm.setPOSID(value)

trm.setPOSID("pos_1234");

Identifier of the Point of Sale, e.g. a cash register number.

TrmLng

trm.getTrmLng()
trm.setTrmLng(value)

trm.setTrmLng("en");
trm.setTrmLng("de");
trm.setTrmLng("fr");
trm.setTrmLng("it");

Terminal language as ISO 639-1 2 letter code.

Default value: Language as configured on the TMS

PrinterWidth

trm.getPrinterWidth()
trm.setPrinterWidth(value)

Width of the printer for receipt formatting in characters per line.

Default value: 34

AutoConnect

trm.getAutoConnect()
trm.setAutoConnect(value)

Configures whether the API tries to connect automatically to the terminal if pairing info has been provided.

Default value: true

AutoReconnect

trm.getAutoReconnect()
trm.setAutoReconnect(value)

Configures whether the API tries to reconnect automatically to the terminal after connection loss.

Default value: true

AutoConfirm

trm.getAutoConfirm()
trm.setAutoConfirm(value)

Configures whether the API shall automatically confirm successfully authorized payment transactions.

Default value: true.

HeartbeatInterval

trm.getHeartbeatInterval()
trm.setHeartbeatInterval(value)

Configures how many milliseconds the API waits with sending heartbeat requests after receiving a message from the terminal.

Default value: 10000.

HeartbeatTimeout

trm.getHeartbeatTimeout()
trm.setHeartbeatTimeout(value)

Configures after how many milliseconds without a message from the terminal the API assumes a connection loss.

Default value: 10000

ConnectionTimeout

trm.getConnectionTimeout()
trm.setConnectionTimeout(value)

Configures how many milliseconds to wait for a connection to the terminal.

Default value: 20000

InitializationTimeout

trm.getInitializationTimeout()
trm.setInitializationTimeout(value)

Configures how many milliseconds to wait for an initialization.

Default value: 120000

TransactionTimeout

trm.getTransactionTimeout()
trm.setTransactionTimeout(value)

Configures how many milliseconds to wait for a transaction to complete.

Default value: 70000

DefaultTimeout

trm.getDefaultTimeout()
trm.setDefaultTimeout(value)

Configures how many milliseconds to wait for any other use case.

Default value: 30000

OnConnected

function onConnected() {}
trm.setOnConnected(onConnected)

Called when the API has successfully connected to the terminal.

OnDisconnected

function onDisConnected() {}
trm.setOnDisconnected(onDisConnected)

Called when the API has lost connection to the terminal.

OnPairingSucceeded

function onPairingSucceeded() {}
trm.setOnPairingSucceeded(onPairingSucceeded)

Called when pairing has succeeded.

OnPairingFailed

function onPairingFailed() {}
trm.setOnPairingFailed(onPairingFailed)

Called when pairing has failed due to any reason.

OnActivationSucceeded

function onActivationSucceeded() {}
trm.setOnActivationSucceeded(onActivationSucceeded)

Called when activate has succeeded.

OnActivationFailed

function onActivationFailed() {}
trm.setOnActivationFailed(onActivationFailed)

Called when activate has failed.

OnActivationTimedOut

function onActivationTimedOut() {}
trm.setOnActivationTimedOut(onActivationTimedOut)

Called when activate has timed out.

OnDeactivationSucceeded

function onDeactivationSucceeded() {}
trm.setOnDeactivationSucceeded(onDeactivationSucceeded)

Called when deactivate has succeeded.

OnDeactivationFailed

function onDeactivationFailed() {}
trm.setOnDeactivationFailed(onDeactivationFailed)

Called when deactivate has failed.

OnDeactivationTimedOut

function onDeactivationTimedOut() {}
trm.setOnDeactivationTimedOut(onDeactivationTimedOut)

Called when deactivate has timed out.

OnTransactionApproved

function onTransactionApproved(transactionResponse) {}
trm.setOnTransactionApproved(onTransactionApproved)

Called when a payment transaction gets successfully authorized.

Please refer to the PayTec ECR Interface Specification for further information about the content of transactionResponse.

OnTransactionDeclined

function onTransactionDeclined(transactionResponse) {}
trm.setOnTransactionDeclined(onTransactionDeclined)

Called when a payment transaction is declined by either the acquirer, the card or the terminal.

Please refer to the PayTec ECR Interface Specification for further information about the content of transactionResponse.

OnTransactionReferred

function onTransactionReferred(transactionResponse) {}
trm.setOnTransactionReferred(onTransactionReferred)

Called when the card issuer request a voice referral to authorize a payment transaction.

Please refer to the PayTec ECR Interface Specification for further information about the content of transactionResponse.

OnTransactionAborted

function onTransactionAborted(transactionResponse) {}
trm.setOnTransactionAborted(onTransactionAborted)

Called when a payment transaction is aborted before completion.

Please refer to the PayTec ECR Interface Specification for further information about the content of transactionResponse.

OnTransactionTimedOut

function onTransactionTimedOut() {}
trm.setOnTransactionTimedOut(onTransactionTimedOut)

Called when no transaction response has been received within TransactionTimeout milliseconds after startTransaction.

OnTransactionConfirmationSucceeded

function onTransactionConfirmationSucceeded() {}
trm.setOnTransactionConfirmationSucceeded(onTransactionConfirmationSucceeded)

Called when the confirmation of a payment transaction has been acknowledged by the terminal.

OnTransactionConfirmationFailed

function onTransactionConfirmationFailed() {}
trm.setOnTransactionConfirmationFailed(onTransactionConfirmationFailed)

Called when the confirmation of a payment transaction fails.

OnTransactionConfirmationTimedOut

function onTransactionConfirmationTimedOut() {}
trm.setOnTransactionConfirmationTimedOut(onTransactionConfirmationTimedOut)

Called when the confirmation of a payment transaction timed out.

OnBalanceSucceeded

function onBalanceSucceeded() {}
trm.setOnBalanceSucceeded(onBalanceSucceeded)

Called when balance has succeeded.

OnBalanceFailed

function onBalanceFailed() {}
trm.setOnBalanceFailed(onBalanceFailed)

Called when balance has failed.

OnBalanceTimedOut

function onBalanceTimedOut() {}
trm.setOnBalanceTimedOut(onBalanceTimedOut)

Called when balance has timed out.

OnConfigurationSucceeded

function onConfigurationSucceeded() {}
trm.setOnConfigurationSucceeded(onConfigurationSucceeded)

Called when configure has succeeded.

OnConfigurationFailed

function onConfigurationFailed() {}
trm.setOnConfigurationFailed(onConfigurationFailed)

Called when configure has failed.

OnConfigurationTimedOut

function onConfigurationTimedOut() {}
trm.setOnConfigurationTimedOut(onConfigurationTimedOut)

Called when configure has timed out.

OnInitializationSucceeded

function onInitializationSucceeded() {}
trm.setOnInitializationSucceeded(onInitializationSucceeded)

Called when initialize has succeeded.

OnInitializationFailed

function onInitializationFailed() {}
trm.setOnInitializationFailed(onInitializationFailed)

Called when initialize has failed.

OnInitializationTimedOut

function onInitializationTimedOut() {}
trm.setOnInitializationTimedOut(onInitializationTimedOut)

Called when initialize has timed out.

OnDeviceCommandSucceeded

function onDeviceCommandSucceeded(deviceCommandResponse) {}
trm.setOnDeviceCommandSucceeded(onDeviceCommandSucceeded)

Called when deviceCommand has succeeded.

OnDeviceCommandFailed

function onDeviceCommandFailed() {}
trm.setOnDeviceCommandFailed(onDeviceCommandFailed)

Called when deviceCommand has failed.

OnDeviceCommandTimedOut

function onDeviceCommandTimedOut() {}
trm.setOnDeviceCommandTimedOut(onDeviceCommandTimedOut)

Called when deviceCommand has timed out.

OnStatusChanged

function onStatusChanged(statusResponse) {}
trm.setOnStatusChanged(onStatusChanged)

Called whenever the terminal status flags have changed.

Please refer to the PayTec ECR Interface Specification for further information about the content of statusResponse.

OnReceipt

function onReceipt(receiptType, receiptText) {}
trm.setOnReceipt(onReceipt)

Called when a receipt has been received from the terminal. This can happen automatically by performing use cases or after requesting a receipt explicitely.

OnMessageSent

function onMessageSent(message) {}
trm.setOnMessageSent(onMessageSent)

Called after the API sends a JSON message to the terminal. This is mainly meant for logging.

OnMessageReceived

function onMessageReceived(message) {}
trm.setOnMessageReceived(onMessageReceived)

Called when the API has received a JSON message from the terminal.

OnError

function onError(message) {}
trm.setOnError(callback)

Called when an error occurs; message is a textual description of the error.

Symbolic constants

TransactionFunctions

trm.TransactionFunctions.PURCHASE

The transaction function is a mandatory paramater to start a payment transaction.

TransactionRequestFlags

trm.TransactionRequestFlags.TRX_REPORT_UNKNOWN_NFC_UID

Flags that impact the behaviour when starting a transaction.

TransactionAbortFlags

trm.TransactionAbortFlags.ABORT_TRX_SILENT

Flags that impact the behaviour when aborting a transaction.

ReceiptTypes

trm.ReceiptTypes.TRX

Types of receipts the terminal can create.

ReceiptFlags

trm.ReceiptTypes.TRX

Flags that modify receipt printing.

StatusFlags

trm.StatusFlags.SHIFT_OPEN

Flags that describe the terminal's current state.

DeviceCommands

trm.DeviceCommands.EJECT_CARD

Commands to perform some terminal actions beside payment.