Skip to main content

Setup and management

The terminal management operations allow the POS to drive specific lower-level functions of the payment terminals. Use terminal management to configure or troubleshoot the payment terminal.

The transaction management operations allow the POS to perform certain non-payment functions on the payment terminal. Use these operations to communicate additional details to the cardholder during their interaction with the payment terminal, such as displaying messages and driving line item display.

This section describes exception handling and the following operations.

  • Cancel
  • Display
  • GetInformation
  • GetParameter
  • GetSignature
  • GetTransactions
  • LastTransaction
  • LineItems
  • PrintLastReceipt
  • PrintText
  • ReadCard
  • Restart
  • SetParameter

Result codes

For a list of values for the result field, refer to the table of result codes.

Cancel

The Cancel operation cancels an outstanding complex operation where the operation field has a value of Display or Transaction. A transaction cannot be canceled once it reaches the communicating stage. If a transaction request has been sent to our payment host, the operation must complete. If necessary, void an approved transaction.

Cancel is a simple operation. 

Note

The cancel response may not return immediately, as certain operations may take a little time to back out of.

The following tables describe the request and response fields for Cancel:

Cancel request fields
Field

operation

Send this field with the value Cancel.
Cancel response fields
Field

operation

This field echoes the value Cancel

result

Success or error indicator for your request.

The following table describes the result codes applicable to a Cancel response:

Cancel result codes
Code Description

0

OK – the operation completed successfully. This indicates that the current complex operation has been successfully canceled. The complex operation returns a separate response message with a result of 12 (Canceled).

1

Application Error: These errors represent failures of processes internal to the Payment Terminal Application. Examples include being unable to create a new thread, file access errors, or loss of communication.

3

Message Error: A field in the request is invalid, a required field is missing, or the request is not formatted correctly.

13

Cancel Not Available: The POS attempts a Cancel operation during a transaction, but after the Payment Terminal Application begins communication with our payment host.

Here is an example of a Cancel request and response:

Request:

Json
{
    "operation": "Cancel"
}

Response:

Json
{
    "operation": "Cancel",
    "result": "13"
}

Display

The Display operation displays a short message to the customer.

Display is a complex operation consisting of a single request/response pair. Display is complex because Payment Terminal Application does not return the response until the screen times out or the request is canceled.

The following tables describe the request and response fields for Display.

Display request fields
Field

operation

Send this field with the value Display.

text

The text to be displayed on the screen. The exact length of the text to be displayed depends on the formatting of the display form. This is a required field.

timeout

The number of seconds to display the message. If 0 is sent with this field, or if this field is omitted, the message is displayed until a cancel operation is sent, a new Display command or a transaction is initiated.
Display response fields
Field

operation

This field is echoed with the value Display.

result

The two expected scenarios are 10 for display message timeout and 12 if canceled by the POS. The following table describes the result codes.

The following table describes the result codes applicable to a Display response:

Display result codes
Code Description

1

Application Error: These errors represent failures of processes internal to the application. Examples include being unable to create a new thread, file access errors, or loss of communication.

3

Message Error: A field in the request is invalid, a required field is missing, or the request is not formatted correctly.

5

Busy: An ongoing operation is already in progress. A new operation cannot be started.

10

Timeout

12

Canceled: The operation was canceled by a Cancel operation from the POS client application.

Here is an example of a Display request and response:

Request:

Json
{
    "operation": "Display",
    "text": "Thank you!\nPlease show your ID to the cashier.",
    "timeout": "6"
}

Response:

Json
{
    "operation": "Display",
    "result": "12"
}

Exception handling

The following table lists typical failure scenarios and the expected terminal behavior:

Typical terminal failures
Condition Terminal behavior
POS cancels transaction The terminal prompts the Merchant for confirmation. The transaction is canceled as soon as the POS sends the Cancel command. Payment Terminal Application returns to the idle screen.
This scenario is only possible before the transaction is sent online for authorization. The merchant can cancel the transaction in any input entry or confirmation steps.

Cardholder cancels transaction via Cancel button

 The terminal prompts the cardholder for confirmation. The transaction is canceled if the cardholder confirms and the terminal returns to the idle menu. 
This condition only occurs during a flow in which the terminal is facing the cardholder.

Prompt or input screen times out

All prompt and input screens have a configurable timeout. If no action is performed during that time, the terminal cancels the transaction automatically and returns to Idle screen.

Chip card read error during insertion

The terminal makes three attempts to read the card before falling back to magstripe prompt.

No mutually supported applications between the chip card and the terminal

The terminal falls back to magstripe read and prompts the cardholder to swipe their card.

The chip card declines the transaction in the 1st Generate AC command (before the authorization attempt is sent online)

The terminal declines the transaction offline. Optionally, print a decline receipt with EMV data for future reference.

No response received from the host for a financial transaction

The terminal declines the transaction locally and issues a reversal.

Printer is not connected or not working properly

If the condition is detected at the start of the operation, a warning is prompted to the merchant before continuing. At the end of the operation, if the printer condition persists, the merchant is informed about the error. Possible error conditions to be informed to the user are: paper low / out of paper, printer disconnected.

Card is removed before the transaction completes

This error happens when the application is not running in Quick Chip mode, and the card is removed before completing an online approved transaction. A reversal is generated in these conditions.
Attention

Reversals are kept in memory until acknowledged by the host.  No other transactions can be performed before the reversal is acknowledged or explicitly deleted.

GetInformation

Use the GetInformation command to retrieve information about the payment terminal that is running the Payment Terminal Application. GetInformation returns real-time information about the device for identification and troubleshooting purposes.

GetInformation is a simple operation.

The following tables describes the request and response fields for GetInformation:

GetInformation request fields
Field

operation

Send this field with the value GetInformation. 
GetInformation response fields
Field

operation

This field echoes the value GetInformation.

information

A JSON object that encapsulates all of the information details about the device.

result

The following table describes the possible result codes.

The following table describes the fields within the information field of a GetInformation response:

Information fields
Information field Description

batteryPercent

The current battery percentage remaining, calculated by the OS.

buildNumber

 OS-specific build number for the configuration package.

extraInfo

A JSON encapsulation object containing data about the hardware. This includes software version numbers, IMEI, Android versions, Part Numbers and more.

firmwareVersion

The OS-specific firmware version number.

isCharging

A Boolean value indicating if the hardware is currently connected to a power source or not.

model

The model name of the connected device.

readerName

The MSD reader name of the connected device.

serialNumber

The unique serial number for the connected device

serialNumberUnformatted

The unique serial number for the connected device, in plaintext.

versionCTLS

The Contactless library version number (if applicable).

versionCoreLibraryCAM

The CAM Core Library version number (if applicable).

versionLibraryEMV

The EMV Library version number (if applicable).

versionOS

The Android OS level.

The following table describes the result codes applicable to a GetInformation response:

GetInformation result codes
Code Description

0

 OK – the operation completed successfully.

1

 Application Error: These errors represent failures of processes internal to the application. Examples include being unable to create a new thread, file access errors, or loss of communication.

3

 Message Error: A field in the request is invalid, a required field is missing, or the request is not formatted correctly.

5

Busy: An ongoing operation is already in progress. A new operation cannot be started.

Here is an example of a GetInformation request and response:

Request:

Json
{
    "operation": "GetInformation"
}

Response:

Json
{
  "information": {
    "batteryPercent": 77.0,
    "buildNumber": "1.10.0",
    "extraInfo": {
      "ICCID": "",
      "PayComponentVersion": "0",
      "SecfwVersion": "01.07.01.00008",
      "ROMVersion": "1.10.0",
      "ProcessorInfo": "Qualcomm Technologies, Inc QCM2150",
      "Mode": "3",
      "IMEI": "016014004667872",
      "BasebandVersion": "19080.4000.00.03.01.62,19080.4000.00.03.01.62",
      "HardwareVersion": "0",
      "HardWareSn": "S6DX800075-2Q95C\u003c226THD829948000",
      "isOvsTerm": "true",
      "TerminalType": "DX8000",
      "AndroidKernelVersion": "4.9.217",
      "BootVersion": "1.1.2\n2022-12-06 18:50",
      "IMSI": "",
      "Manufacture": "ingenico",
      "pn": "TWT52012139B",
      "CSN": ""
    },
    "firmwareVersion": "AND-Q4-ALPHA",
    "isCharging": false,
    "model": "DX8000",
    "readerName": "DX8000",
    "serialNumber": "226THD829948",
    "serialNumberUnformatted": "",
    "versionCTLS": "",
    "versionCoreLibraryCAM": "",
    "versionLibraryEMV": "",
    "versionOS": "10"
  },
  "operation": "GetInformation",
  "result": "0"
}

GetParameter

The GetParameter operation retrieves the value(s) of one or more parameters. Refer to Configuration parameters for the values and key names of Payment Terminal Application parameters.

GetParameter is a simple operation. 

The following tables describe the request and response fields for GetParameter.

GetParameter request fields
Field

operation

Send this field with the value GetParameter

parameters

This required field contains an array of objects. Each object has the following field:

  • key - The key must match the name of a parameter.
GetParameter response fields
Field

operation

This field echoes the value GetParameter

parameters

This required field contains an array of objects. Each object has the following fields:

  • key - The key must match the name of a parameter. Each key field must have an accompanying value field.
  • result - The result indicates whether the associated parameter value was retrieved. Refer to the following table of result codes for the applicable codes.
  • value - The retrieved value for the parameter key name. For an error or blank parameter, this field is empty.

The following table describes the result codes applicable to a GetParameter response.

GetParameter result codes
Code Description

0

OK – the operation completed successfully.

1

Application Error: These errors represent failures of processes internal to the application. Examples include being unable to create a new thread, file access errors, or loss of communication.

3

Message Error: A field in the request is invalid, a required field is missing, or the request is not formatted correctly.

4

Invalid Reference or Key: For a void Transaction request, this indicates that the reference number does not match one in the terminal’s batch. For one of the parameter operations, this indicates an invalid key name

5

Busy: An ongoing operation is already in progress. A new operation cannot be started.

Here is an example of a GetParameter request and response:

Request:

Json
{
    "operation": "GetParameter",
    "parameters": [
        {
            "key": "HOST_IP"
        },
        {
            "key": "Invalid_param"
        },
        {
            "key": "HOST_PORT"
        }
    ]
}

Response:

Json
{
    "operation": "GetParameter",
    "parameters": [
        {
            "key": "HOST_IP",
            "result": "0",
            "value": "123.123.123.123"
        },
        {
            "key": "Invalid_param",
            "result": "4",
            "value": ""
        },
        {
            "key": "HOST_PORT",
            "result": "0",
            "value": "80"
        }
    ]
}

GetSignature

The GetSignature operation prompts the Payment Terminal Application to display the signature screen and acquire a cardholder signature.

GetSignature is a complex operation consisting of a single request/response pair. GetSignature is complex because the Payment Terminal Application does not return the response until one of the following occurs:

  • Screen times out
  • POS sends a request to cancel
  • User cancels on the terminal
  • The cardholder enters and accepts the signature

The following tables describe the request and response fields for GetSignature:

GetSignature request fields
Field

operation

Send this field with the value GetSignature.

disclaimer

The disclaimer text to display in a scrolling text box above the signature field. This is an optional field. If not present, the signature screen does not display the disclaimer scrolling text element.
GetSignature response fields
Field

operation

This field echoes the value GetSignature.

result

The following table describes the possible result codes.

signatureData

The signature data captured by the Payment Terminal Application in BCD format. Converting the BCD-formatted data to binary provides the signature in bitmap format. This field is only present on a successful signature command, which is indicated by a result code of 00.

The following table describes the result codes applicable to a GetSignature response:

GetSignature result codes
Code Description

0

OK – the operation completed successfully. The response will include the signature data field.

1

Application Error: These errors represent failures of processes internal to the application. Examples include being unable to create a new thread, file access errors, or loss of communication.

3

Message Error: A field in the request is invalid, a required field is missing, or the request is not formatted correctly.

5

Busy: An ongoing operation is already in progress. A new operation cannot be started.

10

Timeout

11

Canceled by user: The user pressed the cancel key.

12

Canceled: The operation was canceled by a Cancel operation from the POS client application.

14

Declined by user: On a signature operation, the customer pressed the decline button.

Here is an example of a GetSignature request and response:

Request:

Json
{
    "operation": "GetSignature",
    "disclaimer": "You agree to sign this form"
}

Response:

Json
{
    "operation": "GetSignature",
    "result": "0",
    "signatureData": "iVBORw0KGgoAAAANSUhEUgAAAQgAAACTCAYAAAByIIfLAAAAAXNSR0IArs4c6QAAAARzQklUCAgI\nCHwIZIgAAATTSURBVHic7d1NiFVlGAfwZ9JSRsjM6AMKBKlWUqtECLRNIkQLa5ebhAjLRbtq0UYE\nqXWtahFltAiCKMJalKtKlDYRBAVFkS4qzJKyCZsW5x7OuTn3SDrO88yd3w+G9y7/i+HP877nK4L/\nY0N2AKCm+dEfrBhXZQdYhmayAwD1PBDNBDGXHQSoyTYDmOiRaAribHYQoCZTBCuGQ8pLd3V2AKCe\n16KZID7IDgLU1G4zXPJkqtliXJp3RutbqSmAshxWMvVMEMBECuLSvTRaj6emAMqyzWCqmSAuz+uj\n9aPUFEBZpgimlgkCmEhBXL6fR+szqSmAsmwzmEomiMVxZrQ+mZoCKMsUwdQxQQATKYjF891ofSEz\nBFDTDWGbAQz4KZqCeC47CFDPpjBFAAMUBFPDIeWVszU7AFDP+jBFAAPagrgjOwhQj0uewCAFwbLn\nkPLK25UdAKhnTzQTxFx2EKCmdptxb3YQoJ4noimIP7ODADU5rGTZcki5dGazAwD1bAxTBDDgRDQF\ncTo7CFBTO0Wszg4C1HMkmoI4lx0EqOmraEriVHYQoCYHliwbLnMuvU9H6++pKYCy2iliR3IOoChb\nDcqzxcj3aHYAoKZ2itiWHQSo5+Gw1QAGtAWxOzsIUM+2MEUAA/aGkgAGKAhgop2hJIABf0RTEB9n\nBwFqMkVQhjsp6/lltH6RmgIo61w0U8Tb2UGAetaErQYw4HQ0BfFJdhCgnpnopoiNyVmAgmbDVgMY\n0BbEvuwgQE1tSTyfHQSoZ3vYagAD/oqmIM5kBwHq6V/VeCo5C1CUrQZLxrMYy09bDt+npgDKch4B\nTNQ/j4ArxhZjeZqPiDd7vwEu8E80BXEyOwhQU7vVuCU7CFDP0XAeAQw4HEoCGNAWxO3ZQYB6NkRX\nEm8kZwEK8tQnMOjd6EpiXXIWoKBTYZIABrQF4XkN4AKroiuJ48lZgKLakngoOwhQz6HoSuLW5CxA\nQTeHQ0tgwPloCuJ8dhCgpqNhkgAGtAVxIDsIUFNbEnPZQYB61kRXEnuTswAFXRtdSTiTAC7QnyQO\nJ2cBCuq/Qt8kASyoLYgvs4MANc2FSQIY4DFxYNCPYZIgmgMqWEi/HPyfrFC+zckkMxHx3uj3fDSX\nRAHG9C+BbkzOAhS0O7qS2JKcBSjobHQlcX9yFqCg26IriWeTswAFHYuuJF7NjQJU1H9+41hyFqCg\n/dGVxNfJWYCi2pL4LTsIUM+W6Eri7+QsLDK30LJY3Jo9hdxqzWJZ2/vtIS9gQf1bs29MzgIU1H7F\nyyQBLOjX6EriYHIWoKAPoyuJu5OzAAVtDm/NBi7C5/6AQS9HVxQ7k7MABf0QXUkcSc4CFNU/l1iV\nnAUoxseDgYv6PDw2DgzYF11JfJacBShofYxvOTbnxgEq6pfEK8lZgIL6b8+ej4jZ3DhANfeFqxzA\nRXwbbtMGBjwWXUmcTM4CFHUmuqLYnpwFKKh/LvFNchagoGtivCgO5cYBqlkb4+++PJAbB6hoR4xP\nE3empgFK6pfEieQsQEHXxXhR7M+NA1RzfYyXxOO5cYCK9sR4UdyUGweoqF8S7ydnAQr679OhD+bG\nAarZFOMlsSs1DVDS0zFeFOty4wDVrI7xkngxNw5Q0V0xXhRbc+MA1dwT3lw10b8C92ErsE363QAA\nAABJRU5ErkJggg==\n"
}

GetTransactions

The GetTransactions operation performs a query on the current batch and returns the results to the POS application. Retrieve the records for a category of transactions, as needed, to then perform subsequent actions on specific transactions.

The following table describes the supported transaction type categories.

GetTransactions transaction types
Transaction type Description

“ALL_SALES”

Requests all approved Sales in the batch.

“ALL_AUTHORIZATIONS”

Requests all approved and open Authorizations.

“ALL_RETURNS”

Requests all approved Refunds in the batch.

“ALL_UNADJUSTED”

Requests all approved and open unadjusted Authorizations.
"ALL_SAF" Requests all Store and Forward (SAF) transactions.

The following table identifies the required request fields for GetTransactions:

GetTransactions request fields
Field

operation

Send this field with the value GetTransactions.

type

The transaction type category. For values, refer to the preceding table of supported transaction types.

The following table identifies the response fields for GetTransactions:

GetTransactions response fields
Field

operation

This field echoes the value GetTransactions.

result

Success or error indicator for your request. Refer to the following table for result codes.

records [ ]

An array of transaction response objects. Refer to card and gift card transaction response fields for the list of fields applicable to each transaction type.

The following table describes the result codes applicable to a GetTransactions response.

GetTransactions result codes
Code Description

0

OK – the operation completed successfully. The result field does not indicate whether the transaction was approved; it is instead an indicator of whether the transaction operation was able to successfully gather payment information and communicate with the host.

1

Application Error: These errors represent failures of processes internal to the application. Examples include being unable to create a new thread, file access errors, or loss of communication.

3

Message Error: A field in the request is invalid, a required field is missing, or the request is not formatted correctly.

5

Busy: An ongoing operation is already in progress. A new operation cannot be started.

10

Timeout

97

No records found for the requested operation.

99

Unknown Error: This is a catch-all error that occurs only if an error condition has not been specifically accounted for in Payment Terminal Application.

Here is an example of a GetTransactions request:

Json
{
    "operation": "GetTransactions",
    "type": "ALL_SALES"
}

Response:

Json
{
    "operation": "GetTransactions",
    "result": "0",
    "records": [
        {
            "reference": "510403104321",
            "dateTime": "2017-04-03 13:59:59",
            "account": "********1234",
            "cardBrand": "VISA",
            "entryMode": "Swiped",
            "requestedAmount": "12.34",
            "subTotalAmount": "12.34",
            "totalAmount": "12.34",
            "transactionId": "123456",
            "batchNumber": "1234",
            "result": "00",
            "approval": "approved"
        },
        {
            "reference": "510406674345",
            "dateTime": "2017-04-05 15:00:00",
            "account": "********4321",
            "cardBrand": "VISA",
            "entryMode": "Swiped",
            "requestedAmount": "12.34",
            "subTotalAmount": "10.00",
            "totalAmount": "10.10",
            "transactionId": "654321",
            "batchNumber": "1234",
            "result": "00",
            "approval": "approved"
        }
    ]
}

LastTransaction

LastTransaction returns transaction details from the last transaction sent to our payment host. After a loss of connectivity, use this operation to determine the status of the previous transaction.

LastTransaction is a simple operation with a single request-response pair.

The following tables describe the request and response fields for LastTransaction.

LastTransaction request fields
Field

operation

Send this field with the value LastTransaction. 
LastTransaction response fields
Field

operation

This field is echoed with the value LastTransaction.

Transaction Fields

The response includes all of the transaction fields from the previous transaction. Here is the list of transaction fields:

  • Approval
  • approvalMode
  • balance
  • cardBrand
  • cardToken
  • cashbackAmount
  • CVM
  • dateTime
  • entryMode
  • hostError
  • hostMessage
  • responseCode
  • totalAmount
  • transactionType

result

The following table lists the result codes applicable to this scenario.

The following table describes the result codes applicable to a LastTransaction response:

LastTransaction result codes
Code Description

0

OK – the operation completed successfully.

1

Application Error: These errors represent failures of processes internal to the application. Examples include being unable to create a new thread, file access errors, or loss of communication.

3

Message Error: A field in the request is invalid, a required field is missing, or the request is not formatted correctly.

5

Busy: An ongoing operation is already in progress. A new operation cannot be started.
97 No records found for the requested operation.

Here is an example of a LastTransaction request and response:

Request:

Json
{
    "operation": "LastTransaction"
}

Response:

Json
{
    "account": "4111******1111",
    "approval": "approved",
    "approvalMode": "ISSUER",
    "authCode": "OK1234",
    "terminalID": "12345678",
    "reference": "510403104321",
    "storeID": "123",
    "dateTime": "12-31-2021 13:59:59",
    "operation": "LastTransaction",
    "transactionType": "SALE",
    "cardBrand": "VISA",
    "entryMode": "EMV",
    "requestedAmount": "1234",
    "subtotal": "1234",
    "totalAmount": "1234",
    "transactionID": "12345678",
    "batchNumber": "001",
    "result": "0",
    "responseCode": "00",
    "preferredName": "Visa Common Debit",
    "AID": "A0000000980840",
    "TVR": "8000040000",
    "IAD": "1234567890123456",
    "TSI": "F800",
    "ARC": "00",
    "cvm": "PIN Verified",
    "signatureRequired": "no"
}

LineItems

Use line item display, the LineItems operation, to display an open basket of items to the cardholder. This is common in retail locations, where the merchant may tally several goods or services and wants to display information about each item to the cardholder, including item, quantity, and price.

The LineItems operation causes the application to display a screen with different text sections. The main section contains a list of customizable strings that can be used as line items.

LineItems is a simple operation. The screen displays until your POS sends a new command.

Line Item Display screen capture
LineItems request fields
Field           Description
operation Send this field with the value LineItems
title Contains the text to display in the title bar.
lineItems Array of objects containing left and right components for each line item. The left component is left-aligned on the screen and the right component is right-aligned.
subTotals Array of objects containing left and right components for each of the sub total lines. Supports up to 3 entries. The left component is left-aligned on the screen and the right component is right-aligned.
totals Array of objects containing left and right components for each fo the total lines. Supports up to 2 entries. The left component is left-aligned on the screen and the right component is right-aligned.
LineItems response fields
Field Description
operation This field echoes the value LineItems
result Result code indicates success or failure for your request.

The following table describes the result codes applicable to a LineItems response:

LineItems result codes
Code Description
0 OK - the operation completed successfully.
1 Application error: these errors represent failures of processes internal to the application. Examples include being unable to create a new thread, file access errors, or loss of communication.
3 Message error: a field in the request is invalid, a required field is missing, or the request is not formatted correctly.
5 Busy: an ongoing operation is in progress. You cannot start a new operation.

Here is an example of a LineItems request and response:

Request:

Json
{
    "operation": "LineItems",
    "title": "SHOPPING BASKET",
    "lineItems": [
        {
            "left": "1 x Orange Juice",
            "right": "$2.50"
        },
        {
            "left": "Discount",
            "right": "-$0.50"
        }
    ],
    "subTotals": [
        {
            "left": "Sub Total:",
            "right": "$2.00"
        }
    ],
    "totals": [
        {
            "left": "Total:",
            "right": "$2.00"
        },
        {
            "left": "Earned Points:",
            "right": "200"
        }
    ]
}

Response:

Json
{
    "operation": "LineItems",
    "result": "0"
}

PrintLastReceipt

The PrintLastReceipt operation reprints the last printed, or print attempted, receipt.  

PrintLastReceipt is a simple operation.

The following tables describe the request and response fields for PrintLastReceipt

PrintLastReceipt request fields
Field

operation

Send this field with the value PrintLastReceipt. 
PrintLastReceipt response fields
Field

operation

This field is echoed with the value PrintLastReceipt.

result

The following table describes the possible result codes.

The following table describes the result codes applicable to a PrintLastReceipt response:

PrintLastReceipt result codes
Code Description

0

 OK – the operation completed successfully.

1

 Application Error: These errors represent failures of processes internal to the application. Examples include being unable to create a new thread, file access errors, or loss of communication.

3

Message Error: A field in the request is invalid, a required field is missing, or the request is not formatted correctly.

5

Busy: An ongoing operation is already in progress. A new operation cannot be started.

97

No records found for the requested operation.

Here is an example of a PrintLastReceipt request and response:

Request:

Response:

PrintText

The PrintText operation initiates the paper printing of custom text. Format the text to print according to the printer capabilities (for example, the number of columns and the supported escape characters).

Attention

Print Text is only supported in terminals that have a physical printer connected. 

PrintText is a simple operation.

The following tables describe the request and response fields for PrintText:

PrintText request fields
Field

operation

Send this field with the value PrintText.

text

The full text to be printed. Lines can be delimited using the "new line" character.
PrintText response fields
Field

operation

This field is echoed with the value PrintText.

result

The following table describes the possible result codes.

The following table describes the result codes applicable to a PrintText response:

PrintText result codes
Code Description

0

OK – the operation completed successfully.

1

Application Error: These errors represent failures of processes internal to the application. Examples include being unable to create a new thread, file access errors, or loss of communication.

3

Message Error: A field in the request is invalid, a required field is missing, or the request is not formatted correctly.

5

Busy: An ongoing operation is already in progress. A new operation cannot be started.

72

Printer out of paper or other mechanical problem.

Here is an example of a PrintText request and response:

Request:

Json
{
    "operation": "PrintText",
    "text": " Line1\n Line2\n"
}

Response:

Json
{
    "operation": "PrintText",
    "result": "0"
}

ReadCard

The ReadCard operation causes the application to prompt for a banking card or a non-banking card. When a valid card is presented, the application behavior depends on the type of card:

  • For banking cards, the card information is buffered and is available for use after the final amount is known. A new call to the ReadCard or Cancel operations clears buffered card data.
  • For non-banking cards, the cleartext card information is returned and no card information is buffered.

In order to capture banking cards, the provisional amount (defined by parameter PROVAMT) needs to be set to a value other than 0.0. When set to 0.0 this API operation returns ‘1’ – Application Error.

When a banking card is successfully captured, the operation returns a key to be used when calling the Transaction operation. This ensures the integrity of the transaction flow and avoids using card data from a previous cardholder. 

ReadCard is a complex operation consisting of a single request and response pair. ReadCard is a complex operation because the application does not return the response until a valid card is presented, a timeout occurs, the POS cancels, or the user cancels. 

Steps of a ReadCard operation

  1. ReadCard prompt - the terminal prompts the cardholder for their card.
    • Entry modes accepted are swipe, insert, tap, and EBT.
  2. Language prompt - Payment Terminal Application prompts the cardholder for choice of language. 
    • This step applies only to banking cards.
  3. PIN entry prompt - supports offline PIN only, if required.
    • This step applies only when the cardholder inserts an EMV banking card
    • Control PIN entry bypass with the parameter PINBYPASS

The following tables describe the request and response fields for ReadCard

ReadCard request fields
Field           Description
operation Send this field with the value ReadCard
cardType

Determines the types of cards to be accepted. Value is 0 or 1.

0=Non-banking cards. The card data is returned in cleartext format.

1=Banking cards. The card information is buffered to be used later. No card information is returned at this point. Requires the PROVAMT parameter to be greater than 0.0.
timeout The number of seconds to wait for a card to be presented. If 0 is sent with this field, or if this field is omitted, the card is prompted until a card is presented, the cardholder cancels, or a cancel operation is sent.
ReadCard response fields
Field                     Description
operation This field echoes the value ReadCard. 
result The following table describes the possible result codes.
cardType Echoed from the request.
track2Data

The cleartext track2 data as read from the card.

For non-banking cards only.
track1Data

The cleartext track1 data as read from the card.

For non-banking cards only.
account

The account number masked according to PCI and card brand requirements.

The first 6 and last 4 digits are not masked. The masking character for the middle digits  is ‘*’.

For banking cards only.
cardBrand

The card brand label as inferred from the card BIN. Possible values:

“VISA”, “MASTERCARD”, “DISCOVER”, “JCB”, “DINERS”, “AMERICAN EXPRESS”, “MAESTRO”, “INTERAC”, “UNION PAY”. 

For banking cards only.
readCardID

A unique key generated by the application when a banking card is successfully captured. The same value needs to be provided when calling the Transaction operation.

For banking cards only.

Example: “f09832f1-e1a8-48b7-8ca2-87d481e39cdc”

The following table describes the result codes applicable to a ReadCard response:

ReadCard result codes
Code Description
0 OK – the operation completed successfully and the response includes card data.
1 Application Error: These errors represent failures of processes internal to the application. Examples include being unable to create a new thread, file access errors, or loss of communication.
3

Message Error: A field in the request is invalid, a required field is missing, or the request is not formatted correctly.
5 Busy: An ongoing operation is already in progress. A new operation cannot be started.
10 Timeout.
11 Canceled by user. The user pressed the cancel key.
12 Canceled: The operation was canceled by a Cancel operation from the POS client application.

Here is an example of a ReadCard request and response:

Request:

Json
{
    "operation":"ReadCard",
    "cardType":"0",
    "timeout":"30"
}

Response:

Json
{
    "AC": "",
    "ARC": "",
    "IAD": "",
    "TSI": "",
    "cardType": "0",
    "demoMode": "no",
    "operation": "Transaction",
    "result": "2",
    "type": ""
}

Restart

The Restart operation restarts\reboots the terminal. Payment Terminal Application accepts the request, returns the response, delays for a moment to allow time to handle the request at all layers, shuts down any open connections, then issues the application restart. There can be a considerable delay after issuing the restart command until the terminal effectively restarts, followed by the boot up sequence.

Restart is a simple operation.

The following tables describes the request and response fields for Restart:

Restart request fields
Field

operation

Send this field with the value Restart. 
Restart response fields
Field

operation

This field is echoed with the value Restart.

result

The following table describes the possible result codes.

The following table describes the result codes applicable to a Restart response:

Restart result codes
Code Description

0

OK – the operation completed successfully. The terminal will restart shortly.

1

Application Error: These errors represent failures of processes internal to the application. Examples include being unable to create a new thread, file access errors, or loss of communication.

3

Message Error: A field in the request is invalid, a required field is missing, or the request is not formatted correctly.

Here is an example of a Restart request and response:

Request:

Json
{
    "operation": "Restart"
}

Response:

Json
{
    "operation": "Restart",
    "result": "0"
}

SetParameter

The SetParameter operation sets the value(s) of one or more of Payment Terminal Application parameters. Refer to Configuration parameters for the values and key names of Payment Terminal Application parameters. The POS client needs to set parameters within Payment Terminal Application from time to time, so plan to set and change parameters for Payment Terminal Application ahead of time. Build in a function to set and get these values easily.

SetParameter is a simple operation.

The following tables describe the request and response fields for SetParameter.

SetParameter request fields
Field

operation

Send this field with the value SetParameter.

parameters

This required field contains an array of objects. Each object has the following fields:

  • key - The key must match the name of a parameter. Each key field must have an accompanying value field.
  • value - The value must match the values described for the parameter. A value field must have an accompanying key field.
SetParameter response fields
Field

operation

This field echoes the value SetParameter.

parameters

This required field contains an array of objects. Each object has the following fields:

  • key – The key must match the name of a parameter. Each key field must have an accompanying value field.
  • result – The result indicates whether the associated parameter value was set. Refer to the following table of result codes for the applicable codes.

The following table describes the result codes applicable to a SetParameter response.

SetParameter result codes
Code Description

0

OK – the operation completed successfully.

1

Application Error: These errors represent failures of processes internal to the application. Examples include being unable to create a new thread, file access errors, or loss of communication.

3

Message Error: A field in the request is invalid, a required field is missing, or the request is not formatted correctly.

4

Invalid Reference or Key: For a void Transaction request, this indicates that the reference number does not match one in the terminal’s batch. For one of the parameter operations, this indicates an invalid key name

5

Busy: An ongoing operation is already in progress. A new operation cannot be started.

Here is an example of a SetParameter request and response:

Request:

Json
{
    "operation": "SetParameter",
    "parameters": [
        {
            "key": "HOST_IP",
            "value": "123.123.123.123"
        },
        {
            "key": "Invalid_param",
            "value": "1234"
        },
        {
            "key": "HOST_PORT",
            "value": "80"
        }
    ]
}

Response:

Json
{
    "operation": "SetParameter",
    "parameters": [
        {
            "key": "HOST_IP",
            "result": "0"
        },
        {
            "key": "Invalid_param",
            "result": "4"
        },
        {
            "key": "HOST_PORT",
            "result": "0"
        }
    ]
}

Payment terminal maintenance

Requirements for PCI DSS Payment Terminal Reboot

PCI DSS requires the payment terminal to reboot at least once every 24 hours. Depending on the manufacturer of the terminal, your device has a configurable time slot to reboot the device every day.

This time slot is configurable and can be set by TMS or the POS Client. (Refer to the parameter REBTIME.) The default value is 02:00am local time.

This reboot will trigger a drop from the network while the Payment Terminal reboots. Additionally, files may be installed after the reboot, so the reboot time may take a varying amount of time to come back online. Your POS must be aware of this behavior and act accordingly.

Confirm Software Versions on the terminal

It is best practice for the POS Client to verify an expected software version that is running on the terminal. This can be done with the ‘Get Information’ command and by referencing the ‘firmwareVersion field’.

Extend operating life of battery powered terminals

For battery powered terminals specifically, it is best practice to avoid doing operations when not necessary. Things like ‘heartbeat’ checks, status checks and other operations may have an impact battery life if performed often enough.

The features with the most significant battery drain are usually the screen, the Contactless radio and then the networking chip (Wi-Fi or LTE). If the POS Client can limit how often the Payment terminal wakes to perform an operation, the longer the operating time will be.