Terminal Settings

Overview

The sync command allows you to push configuration directly from the terminal. Settings such as tip, cashback, surcharge, receipt, MOTO, restaurant, language and transaction id label can be changed. The settings can be applied at either the Terminal level or the Merchant level, but not both simultaneously. Mixing both levels will result in inconsistent behaviour.

List of coding scenarios that use this endpoint:

Terminal Settings Command

To change the tip settings, your object needs the following format:

Request example

{
  "apiVersion": "3.0",
  "istConfigCode": "example_istConfigCode",
  "dataId": "example_dataId",
  "dataTimestamp": "1969-12-31 23:59:59",
  "data": {
    "request": [
      {
        "idempotencyKey": "example_idempotencyKey",
        "merchantId": "example_merchantId",
        "terminalId": "example_terminalId",
        "action": "sync",
        "syncModifier": "SYNCTMS",
        "updateProfileLevel": "Terminal",
        "settings": {
          "tms": {
            "parameters": {
              "applicationSettings": {
                "tip": {
                  "enableTip": "false",
                  "byAmount": "true",
                  "byPercent": "true",
                  "preset1": "2",
                  "preset2": "5",
                  "preset3": "10",
                  "onSubtotal": "true"
                }
              }
            }
          }
        }
      }
    ]
  }
}

To change the cashback settings, your object needs the following format:

Request example

{
  "apiVersion": "3.0",
  "istConfigCode": "example_istConfigCode",
  "dataId": "example_dataId",
  "dataTimestamp": "1969-12-31 23:59:59",
  "data": {
    "request": [
      {
        "idempotencyKey": "example_idempotencyKey",
        "merchantId": "example_merchantId",
        "terminalId": "example_terminalId",
        "action": "sync",
        "syncModifier": "SYNCTMS",
        "updateProfileLevel": "Terminal",
        "settings": {
          "tms": {
            "parameters": {
              "applicationSettings": {
                "transactionSettings": {
                  "cashBack": {
                    "enableCashBack": "true",
                    "customValueAllowed": "false",
                    "limit": "100",
                    "amount1": "10",
                    "amount2": "40",
                    "amount3": "60"
                  }
                }
              }
            }
          }
        }
      }
    ]
  }
}

To change the surcharge settings, your object needs the following format:

Request example

{
  "apiVersion": "3.0",
  "istConfigCode": "example_istConfigCode",
  "dataId": "example_dataId",
  "dataTimestamp": "1969-12-31 23:59:59",
  "data": {
    "request": [
      {
        "idempotencyKey": "example_idempotencyKey",
        "merchantId": "example_merchantId",
        "terminalId": "example_terminalId",
        "action": "sync",
        "syncModifier": "SYNCTMS",
        "updateProfileLevel": "Terminal",
        "settings": {
          "tms": {
            "parameters": {
              "applicationSettings": {
                "transactionSettings": {
                  "surcharge": {
                    "enableSurcharge": "true",
                    "surchargeAmount": "25"
                  }
                }
              }
            }
          }
        }
      }
    ]
  }
}

To change the receipt settings, your object needs the following format:

Request example

{
  "apiVersion": "3.0",
  "istConfigCode": "example_istConfigCode",
  "dataId": "example_dataId",
  "dataTimestamp": "1969-12-31 23:59:59",
  "data": {
    "request": [
      {
        "idempotencyKey": "example_idempotencyKey",
        "merchantId": "example_merchantId",
        "terminalId": "example_terminalId",
        "action": "sync",
        "syncModifier": "SYNCTMS",
        "updateProfileLevel": "Terminal",
        "settings": {
          "tms": {
            "parameters": {
              "applicationSettings": {
                "receipt": {
                  "customerReceiptPrompt": {
                    "emailReceipt": "true",
                    "smsReceipt": "true",
                    "noReceipt": "true",
                    "printReceipt": "true",
                    "receiptPrompt": "true"
                  },
                  "footerCustomerCopy": [
                    "Thank you!!"
                  ],
                  "headerCustomerCopy": [
                    "default header"
                  ],
                  "numberOfMerchantCopies": "0",
                  "printDelay": "1",
                  "printQRCode": "true"
                }
              }
            }
          }
        }
      }
    ]
  }
}

To change the MOTO settings, your object needs the following format:

Request example

{
  "apiVersion": "3.0",
  "istConfigCode": "example_istConfigCode",
  "dataId": "example_dataId",
  "dataTimestamp": "1969-12-31 23:59:59",
  "data": {
    "request": [
      {
        "idempotencyKey": "example_idempotencyKey",
        "merchantId": "example_merchantId",
        "terminalId": "example_terminalId",
        "action": "sync",
        "syncModifier": "SYNCTMS",
        "updateProfileLevel": "Terminal",
        "settings": {
          "tms": {
            "parameters": {
              "applicationSettings": {
                "transactionSettings": {
                  "MOTO": "false"
                }
              }
            }
          }
        }
      }
    ]
  }
}

To change the restaurant settings, your object needs the following format:

Request example

{
  "apiVersion": "3.0",
  "istConfigCode": "example_istConfigCode",
  "dataId": "example_dataId",
  "dataTimestamp": "1969-12-31 23:59:59",
  "data": {
    "request": [
      {
        "idempotencyKey": "example_idempotencyKey",
        "merchantId": "example_merchantId",
        "terminalId": "example_terminalId",
        "action": "sync",
        "syncModifier": "SYNCTMS",
        "updateProfileLevel": "Terminal",
        "settings": {
          "tms": {
            "parameters": {
              "applicationSettings": {
                "restaurant": {
                  "enable": "true",
                  "paybySeat": "true",
                  "checkSplitting": "true",
                  "supportCash": "true",
                  "supportGift": "true"
                }
              }
            }
          }
        }
      }
    ]
  }
}

To change the language settings, your object needs the following format:

Request example

{
  "apiVersion": "3.0",
  "istConfigCode": "example_istConfigCode",
  "dataId": "example_dataId",
  "dataTimestamp": "1969-12-31 23:59:59",
  "data": {
    "request": [
      {
        "idempotencyKey": "example_idempotencyKey",
        "merchantId": "example_merchantId",
        "terminalId": "example_terminalId",
        "action": "sync",
        "syncModifier": "SYNCTMS",
        "updateProfileLevel": "Terminal",
        "settings": {
          "tms": {
            "parameters": {
              "applicationSettings": {
                "transactionSettings": {
                  "language": "French"
                }
              }
            }
          }
        }
      }
    ]
  }
}

To change the transaction id label settings, your object needs the following format:

Request example

{
  "apiVersion": "3.0",
  "istConfigCode": "example_istConfigCode",
  "dataId": "example_dataId",
  "dataTimestamp": "1969-12-31 23:59:59",
  "data": {
    "request": [
      {
        "idempotencyKey": "example_idempotencyKey",
        "merchantId": "example_merchantId",
        "terminalId": "example_terminalId",
        "action": "sync",
        "syncModifier": "SYNCTMS",
        "updateProfileLevel": "Terminal",
        "settings": {
          "tms": {
            "parameters": {
              "applicationSettings": {
                "transactionSettings": {
                  "transactionIdLabel": "test"
                }
              }
            }
          }
        }
      }
    ]
  }
}

Request Structure

Element	Type	Description	Size	Required
apiVersion	String	API version number	V20	Required
istConfigCode	String	Moneris provided integration configuration code	V25	Required
dataId	String	Merchant defined unique identifier for the data object	V50	Required
dataTimestamp	String	Date and time of the request (YYYY-MM-DD HH:MM:SS)	F19	Required
data	Object	Object that contains all transaction requests	—	—
request	Array	Contains data applicable to transaction request	—	—
idempotencyKey	String	Unique transaction identifier to avoid duplicate request	V50	Required
merchantId	String	Merchant ID of requestor	V13	Required
terminalId	String	Destination Terminal ID. Note: An error will be returned if terminalId in the request does not match with the Terminal.	F8	Optional
progressStatus	String	If value is set to "True", terminal will return progress to POS. Note: This feature is only available on Direct Integration.	V5	Optional
syncModifier	String	Identifies which host to synchronize with	V24	Optional
action	String	"sync"	V50	Required
updateProfileLevel	String	"Terminal" or "Merchant." If the value "Terminal" is selected, the payment application will instruct TMS to apply the setting exclusively to the terminal. If the value "Merchant" is chosen, the payment application will instruct TMS to apply the setting at the merchant profile level. This is a required field if the “settings” object is provided.	—	Conditional
settings	Object		—	Optional
tms	Object		—	Optional
parameters	Object		—	Optional
applicationSettings	Object		—	Optional
language	String	Update default terminal language. Valid values: “English” or “French”	V5	Optional
tip	Object		—	Optional
enableTip	String	If value is true then tip is enabled and if the value is false it is disabled. Additional tip settings are not applicable when tip is disabled. Valid values: “true” or “false”	V5	Optional
byAmount	String	Tip by dollar enables the customer to enter tip as a dollar amount. Valid values: “true” or “false”	V5	Optional
byPercent	String	Tip by percentage enables the customer to enter tip as a percentage of the amount. Valid values: “true” or “false”	V5	Optional
onSubtotal	String	If value is “true” then tips will be calculated on the subtotal (pre-tax amount). Valid values: “true” or “false”	V5	Optional
preset1	String	Tip preset 1 through Tip preset 3 allow for quick entry of a tip. Preset value is either a percentage or dollar amount of tip. Valid values: 1 to 999. If POS sets any of the values as 0, that Tip preset will not be presented to the cardholder.	V3	Optional
preset2	String	Tip preset 1 through Tip preset 3 allow for quick entry of a tip. Preset value is either a percentage or dollar amount of tip. Valid values: 1 to 999. If POS sets any of the values as 0, that Tip preset will not be presented to the cardholder.	V3	Optional
preset3	String	Tip preset 1 through Tip preset 3 allow for quick entry of a tip. Preset value is either a percentage or dollar amount of tip. Valid values: 1 to 999. If POS sets any of the values as 0, that Tip preset will not be presented to the cardholder.	V3	Optional
presetByAmount	String	If “true” the presets are dollar values. If “false” the presets are percentage amounts. Valid values: “true” or “false”	V5	Optional
restaurant	Object	These parameters are only applicable to Moneris's "Pay at the Table" Solution.	—	Optional
enable	String	If value is “true” the terminal will enable the restaurant settings. Valid values: “true” or “false”	V5	Optional
checkSplitting	String	If value is “true” then bill splitting will be enabled. Valid values: “true” or “false”	V5	Optional
payBySeat	String	If value is “true” then terminal will be enabled to collect payment by seat. Valid values: “true” or “false”	V5	Optional
supportCash	String	If value is “true” the terminal can record payments made by cash. Valid values: “true” or “false”	V5	Optional
supportGift	String	If value is “true” the terminal will be allowed to collect payments by gift cards. Valid values: “true” or “false”	V5	Optional
transactionSettings	Object		—	Optional
cashBack	Object		—	Optional
enableCashBack	String	When Enable Cashback is “false”, the terminal will not provide cashback option to the cardholder. When it is “true”, merchants can set all other cashback options. Valid values: “true” or “false”	V5	Optional
customValueAllowed	String	Custom Value Allowed allows the cardholder to enter a cashback amount. If the value is “true” it allows the cardholder to enter a custom value in the cashback prompt screen. Valid values: “true” or “false”	V5	Optional
limit	String	Limit sets the maximum cashback allowed per transaction. Maximum value is 990	V3	Optional
amount1	String	Cashback preset 1 through cashback preset 3 allow for quick entry of cashback. Values must be in multiples of 10. If POS sets any of the values as 0, that preset will not be presented to the cardholder.	V3	Optional
amount2	String	Cashback preset 1 through cashback preset 3 allow for quick entry of cashback. Values must be in multiples of 10. If POS sets any of the values as 0, that preset will not be presented to the cardholder.	V3	Optional
amount3	String	Cashback preset 1 through cashback preset 3 allow for quick entry of cashback. Values must be in multiples of 10. If POS sets any of the values as 0, that preset will not be presented to the cardholder.	V3	Optional
MOTO	String	If “true” manual entry transactions (moto) enables the terminals to perform card not present transactions. Valid values: “true” or “false”	V5	Optional
surcharge	Object		—	Optional
enableSurcharge	String	When the value is “true” the terminal will charge customers surcharge on interac transactions. Valid values: “true” or “false”	V5	Optional
surchargeAmount	String	The Surcharge amount field is not displayed when enableSurcharge is “false”. Surcharge only applies to Interac transactions. Valid values are 1($0.01) to 25 ($0.25)	V2	Optional
transactionIdLabel	String	The transaction identifier supplies a title of custom texts that merchants wish to capture for any transaction. The field can contain a maximum of twenty alphanumeric characters.	V20	Optional
receipt	Object		—	Optional
customerReceiptPrompt	Object		—	Optional
emailReceipt	String	If enabled, cardholders can enter their email IDs to avail an e-receipt. Valid values: “true” or “false”	V5	Optional
noReceipt	String	If enabled, cardholders can select this option if they do not want to obtain a receipt. Valid values: “true” or “false”	V5	Optional
printReceipt	String	If “true”, cardholders will be presented the option to print a physical receipt (on supported devices). Valid values: “true” or “false”	V5	Optional
receiptPrompt	String	When receiptPrompt is enabled, the screen will show additional receipt options to the cardholder. Toggles for Email receipt, Text Receipt, SMS Receipt and No receipt. Valid values: “true” or “false”	V5	Optional
smsReceipt	String	If enabled, cardholders can enter their phone numbers to avail an e-receipt. Valid values: “true” or “false”	V5	Optional
footerCustomerCopy	Array	The POS can define upto 6 lines, each 30 characters long, to print in the footer section of the customer's copy of the receipt.	—	Optional
headerCustomerCopy	Array	The POS can define upto 6 lines, each 30 characters long, to print in the header section of the customer's copy of the receipt.	—	Optional
numberOfMerchantCopies	String	Sets the number of merchant copies to print. Valid values: “0”, “1”, “2”	F1	Optional
printDelay	String	Sets the length of time printing is paused between cardholder and merchant copies of the receipt. Valid values: “0”, “1”, “2”, “3”, “4”, “5” (in seconds).	F1	Optional
printQRCode	String	If enabled, a QR code is printed on the receipt. Valid values: “true” or “false”. This is only applicable on the DX8000 and A920 when the terminal prints the receipt.	V5	Optional

Request example

{
  "apiVersion": "3.0",
  "apiToken": "example_apiToken",
  "storeId": "example_storeId",
  "istConfigCode": "example_istConfigCode",
  "polling": "true",
  "postBackUrl": "https://example.client.url",
  "dataId": "example_dataId",
  "dataTimestamp": "1969-12-31 23:59:59",
  "data": {
    "request": [
      {
        "idempotencyKey": "example_idempotencyKey",
        "merchantId": "example_merchantId",
        "terminalId": "example_terminalId",
        "action": "sync",
        "syncModifier": "SYNCTMS",
        "updateProfileLevel": "Terminal",
        "settings": {
          "tms": {
            "parameters": {
              "applicationSettings": {
                "transactionSettings": {
                  "transactionIdLabel": "test"
                }
              }
            }
          }
        }
      }
    ]
  }
}

Response Structure

Element	Type	Description	Size	Required
apiVersion	String	API version number	V20	Required
statusCode	String	Status code for the overall transaction request	V4	Required
status	String	Description of the statusCode	V4	Required
dataId	String	Merchant defined unique identifier for the data object	V50	Required
dataTimestamp	String	Date and time of the request (YYYY-MM-DD HH:MM:SS)	F19	Required
data	Object	Object that contains all transaction requests	—	—
response	Array	Contains data applicable to transaction request	—	—
idempotencyKey	String	Unique transaction identifier to avoid duplicate request	V50	Required
action	String	"sync"	V50	Required
statusCode	String	Status code for individual request	V4	Required
status	String	Description of the individual statusCode	V50	Required
settings	Object	returns TMS and Host settings	—	—
completed	String	"true" or "false"	V5	Required

Response example

{
  "apiVersion": "3.0",
  "statusCode": "example_statusCode",
  "status": "example_status",
  "dataId": "example_dataId",
  "dataTimestamp": "1969-12-31 23:59:59",
  "data": {
    "response": [
      {
        "idempotencyKey": "example_idempotencyKey",
        "statusCode": "example_statusCode",
        "status": "example_status",
        "completed": "true",
        "action": "sync",
        "settings": {
          "tms": {
            "parameters": {
              "applicationSettings": {
                "goDevice": true,
                "receipt": {
                  "customerReceiptPrompt": {
                    "emailReceipt": true,
                    "noReceipt": true,
                    "printReceipt": true,
                    "receiptPrompt": true,
                    "smsReceipt": true
                  },
                  "footerCustomerCopy": [
                    "testö",
                    "testgbj.",
                    " chycb. hj"
                  ],
                  "headerCustomerCopy": [
                    "ËlïOÔoïö"
                  ],
                  "numberOfMerchantCopies": "0",
                  "printDelay": "1",
                  "printQRCode": true
                },
                "security": {
                  "autoSignout": false,
                  "signoutTime": "40"
                },
                "semiIntegrated": {
                  "commType": "IP",
                  "enable": true,
                  "port": "",
                  "printingOnEcr": true
                },
                "tip": {
                  "byAmount": false,
                  "byPercent": true,
                  "enableTip": false,
                  "onSubtotal": false,
                  "preset1": "10",
                  "preset2": "0",
                  "preset3": "20",
                  "presetByAmount": false,
                  "warningThreshold": "100"
                },
                "TMS": {
                  "TMSConnectInterval": "720",
                  "TMSConnectTime": "07:23",
                  "TMSHost": "tmsct.moneris.com",
                  "TMSPort": "1124"
                },
                "transactionSettings": {
                  "cashBack": {
                    "amount1": "0",
                    "amount2": "10",
                    "amount3": "05",
                    "reportResetTime": "23:00"
                  }
                }
              },
              "host": {
                "card": {
                  "Ctls": true,
                  "Cards": {
                    "P": "INTERAC",
                    "V": "VISA",
                    "M": "MASTERCARD",
                    "AX": "AMEX",
                    "C1": "JCB",
                    "UP": "UNIONPAY",
                    "NO": "DISCOVER",
                    "DC": "DINERS"
                  }
                },
                "term": {
                  "MerchantID": "0030128914802",
                  "MerchantName": "MONERIS GO DEV TEAM",
                  "TermAddr1": "3300 BLOOR ST WEST",
                  "TermAddr2": "TORONTO ON",
                  "defaultTxn": "00",
                  "purchase": 1,
                  "purchaseCashback": 1,
                  "preAuthorization": 1,
                  "completion": 1,
                  "forcePost": 1,
                  "refund": 1,
                  "purchaseCorrection": 1,
                  "refundCorrection": 0,
                  "cardVerification": 1,
                  "balanceInquiry": 1,
                  "payment": 1,
                  "paymentCorrection": 1,
                  "hostInitialization": 1,
                  "clerkIDMaintenace": 1,
                  "logon": 1,
                  "logoff": 1,
                  "clerkSubtotalsInquiry": 1,
                  "closeBatch": 0,
                  "merchantSubtotalsInquiry": 0,
                  "depositTotalsInquiry": 0,
                  "assistedUP": 1,
                  "currency": "124",
                  "timeoutPinInterchar": 15,
                  "timeoutPinEntry": 60,
                  "timeoutHostResponse": 60
                }
              }
            }
          }
        }
      }
    ],
    "customValueAllowed": true,
    "enableCashBack": true,
    "Interac": true,
    "InteracLimit": "100",
    "limit": "100",
    "Mastercard": true,
    "MastercardLimit": "100",
    "Visa": true,
    "VisaLimit": "100"
  },
  "completion": {
    "limitMultiplier": "4",
    "limitThreshold": "1500"
  },
  "MonerisGiftAndLoyaltyApp": {
    "enableGiftAndLoyalty": true,
    "giftandLoyaltyID": "163467",
    "routingCode": "79"
  },
  "MOTO": true,
  "passTerminalTimer": "2",
  "surcharge": {
    "enableSurcharge": false,
    "surchargeAmount": "50"
  },
  "transactionIdLabel": "Custom",
  "transactionIdPrompt": true,
  "general": {
    "initialized": true,
    "PCIRebootTime": "03:00"
  },
  "merchant": {
    "merchantAddress": "1180 BOULEVARD SACR COEU",
    "merchantCity": "SAINT-FLICIE",
    "merchantName": "MONERIS GO DEV TEAM",
    "merchantPhone": "4169557091",
    "merchantPostalCode": "M5J 0B8",
    "merchantProvince": "ON"
  },
  "reports": {
    "depositTotalsInquiry": 0,
    "assistedUP": 1,
    "currency": "124",
    "timeoutPinInterchar": 15,
    "timeoutPinEntry": 60,
    "timeoutHostResponse": 60
  }
}

Errors

If your response contains errors, visit the Errors page for a detailed description of each one.