# JPMC-PDP Documentation from https://developer.payments.jpmorgan.com # 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](/docs/commerce/in-store-payments/capabilities/payment-terminal-application/card-transactions#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. > The cancel response may not return immediately, as certain operations may take a little time to back out of. > The following tables describes the request fields for `Cancel`. **Cancel request fields** | Field | | --- | | operation Send this field with the value Cancel. | The following table describes the response fields for `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 `Cancel`. **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 table describes the request 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. | The following table describes the response fields for `Display`. **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. | > 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 table describes the request fields for `GetInformation`. **GetInformation request fields** | Field | | --- | | operation Send this field with the value GetInformation. | The following table describes the response fields for `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](/docs/commerce/in-store-payments/capabilities/payment-terminal-application/configuration-parameters) for the values and key names of Payment Terminal Application parameters. `GetParameter` is a simple operation. The following table describes the request 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 Send a value that matches the name of a [parameter](/docs/commerce/in-store-payments/capabilities/payment-terminal-application/configuration-parameters). | The following table describes the response fields for `GetParameter`. **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 matches the name of a [parameter](/docs/commerce/in-store-payments/capabilities/payment-terminal-application/configuration-parameters). 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 table describes the request 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. | The following table describes the response fields for `GetSignature`. **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_REFUNDS | 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 describes the 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 describes 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 table describes the request fields for `LastTransaction`. **LastTransaction request fields** | Field | | --- | | operation Send this field with the value LastTransaction. | The following table describes the response fields for `LastTransaction`. **LastTransaction response fields** | Field | | --- | | operation This field is echoed with the value LastTransaction. | | The response includes all fields from the most recent transaction. The following response fields are provided for reference. For the complete list, refer to the table of [response fields](/docs/commerce/in-store-payments/capabilities/payment-terminal-application/card-transactions#response-fields). The transaction response includes two transaction type fields, transactionType and type. Use the value in type for logic-based computations. Use the value in transactionType for display. - 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](/api/download/en/docs/commerce/in-store-payments/capabilities/payment-terminal-application/cf-setup-and--management/screen-lineitemdisp-1.png?type=image) The following table describes the request fields for `LineItems`. **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. | The following table describes the response fields for `LineItems`. **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 table describes the request fields for `PrintLastReceipt`. **PrintLastReceipt request fields** | Field | | --- | | operation Send this field with the value PrintLastReceipt. | The following table describes the response fields for `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: ```json { "operation": "PrintLastReceipt" } ``` Response: ```json { "operation": "PrintLastReceipt", "result": "0" } ``` ## 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). > Print Text is only supported in terminals that have a physical printer connected. > `PrintText` is a simple operation. The following table describes the request 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. | The following table describes the response fields for `PrintText`. **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 table describes the request 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. | The following table describes the response fields for `ReadCard`. **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. | | 2 | Card Error: Indicates removal or failure of a contact card. | | 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": "1", "timeout": "0" } ``` Response: ```json { "account": "401136******0012", "cardBrand": "VISA", "cardType": "1", "merchantID": "9999999", "operation": "Transaction", "readCardID": "c6dd4a14-e6bf-411e-bf96-69586ec4814d", "result": "0", "terminalID": "009", "type": "READ_CARD" } ``` ## 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 table describes the request fields for `Restart`. **Restart request fields** | Field | | --- | | operation Send this field with the value Restart. | The following table describes the response fields for `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](/docs/commerce/in-store-payments/capabilities/payment-terminal-application/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 table describes the request 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](/docs/commerce/in-store-payments/capabilities/payment-terminal-application/configuration-parameters). 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. | The following table describes the response fields for `SetParameter`. **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](/docs/commerce/in-store-payments/capabilities/payment-terminal-application/configuration-parameters). 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:00 a.m. local time. Reboot triggers a drop from the network while the payment rerminal reboots. If necessary, a reboot includes the installation of files. The time required to reboot and come back online varies. Your POS must allow for this behavior and act accordingly. ### Confirm software version on the terminal As a POS client, verify the expected software version on the terminal. Send a `GetInformation` request and refer to the `firmwareVersion` field in the response. ### Extend operating life of battery powered terminals For battery powered terminals, avoid doing operations when not necessary. For example, heartbeat checks, status checks, and other operations impact battery life if performed often enough. The features with the most significant battery drain are usually the screen, the contactless radio, and the networking chip (Wi-Fi or LTE). To maximize the operating time, limit how often the payment terminal wakes to perform an operation.