In-Store Payments

Terminal tipping sale flow

There are a set of configuration parameters for the Payment Terminal Application you can use to collect tips on the terminal during a sale transaction. By configuring the parameters once, the user experience for cardholders is the same every time.

This is the flow:

The POS application sends a sale transaction to the Payment Terminal Application.
The terminal screen displays the tip prompts based on the parameter configurations.
Once the cardholder completes the tip flow, they are prompted to enter their card for payment via tap, insert, or swipe.
The sale response data includes the total amount and the tip amount to be recorded in the POS application.

Tip parameters

The following table lists and defines the relevant tip parameters for tipping on the terminal.

Relevant tip parameters
Parameter	Description	TMS	API	Format	Value
TIP	Controls tip prompting. *Configure the TIP parameter using the `SetParameter` operation. On individual Sale transactions, configure the TIP parameter for either no tip (TIP=0) or prompt for tip on the terminal (TIP=1)	Y		Num	0=No Tip (default) 1=Prompt for tip on the terminal
TIPCALC	Defines how the tip suggestions are calculated.	Y	N	Num	0=Based on the transaction amount (default) 1=Based on transaction amount + tax(es)
TIPOPT	Controls additional options for tip prompting when tipping on the terminal is enabled (parameter TIP=1).	Y	Y	Num	0=suggested percentages (default) 1=suggested amounts 2=suggested amounts up to a threshold, and then suggested percentages, for example., tipping dollar amounts up to $10 and percentages above
TIPTHR	Only used in conjunction with parameter TIPOPT=2 to set the threshold amount.	Y	Y	Float	Default: 2000 ($20.00)
NOTIP	Controls the display of the “No Tip” option on the Payment Terminal Application. Only applies when parameter TIP=1.	Y	Y	Num	0=Screen doesn't include “No Tip” button 1=Screen includes button with “No Tip” (default) 2=Screen includes button with “Cash Tip”
STATICTIP	Defines a static tip percentage for the requestedAmount on every transaction when tipping on the terminal is enabled (parameter TIP=1). Percentages are expressed with 3 implied decimals; for example, 10000 represents 10.000%.	Y	Y	Float	Default: 0
TIPAMT1	Defines suggested fixed tip amount for option 1 when tipping on the terminal is enabled (parameter TIP=1)	Y	Y	Float	Default: 100 ($1.00)
TIPAMT2	Defines suggested fixed tip amount for option 2 when tipping on the terminal is enabled (parameter TIP=1)	Y	Y	Float	Default: 300 ($3.00)
TIPAMT3	Defines suggested fixed tip amount for option 3 when tipping on the terminal is enabled (parameter TIP=1)	Y	Y	Float	Default: 500 ($5.00)
TIPPERC1	Defines suggested tip percentage for option 1 when tipping on the terminal is enabled (parameter TIP=1)	Y	Y	Float	Default: 15000 (15.000%)
TIPPERC2	Defines suggested tip percentage for option 2 when tipping on the terminal is enabled (parameter TIP=1)	Y	Y	Float	Default: 18000 (18.000%)
TIPPERC3	Defines suggested tip percentage for option 3 when tipping on the terminal is enabled (parameter TIP=1)	Y	Y	Float	Default: 20000 (20.000%)
TIPGUIDE	Controls how the guide text below the primary tip suggestions are presented on the tipping buttons. Only applies when parameter TIP=1.	Y	Y	NUM	0=The guide text below the button shows the final amount including tax and tip. This applies to both percentage and amount suggestions (controlled by the parameter TIPOPT). (default) 1=The guide text below the button shows the tip amount calculated per the percentage on the button. This only applies to the percentage suggestions. If TIPOPT = 1 (prompt for suggested amounts), the guide is not shown.

Send tip configurations in the sale request

Use additional fields in the sale request to modify or ignore tipping parameters. For instance:

Configure a limited set of tip parameters and add tip settings in the Sale request, allowing you to program to your POS application to change tip percentages dynamically, for example based on amounts, time of day, whether a gift certificate was used, etc.
Ignore all tip parameters configured on the terminal and send all tip parameters in your sale request, giving your POS application ultimate control over when tips are prompted on the terminal. For instance, this can be used to skip prompting for tips on retail sales but add them for food and beverage sales.

API integration

To include tip settings in the Sale request, use the parameters in the request as seen in the following example. Refer to Sale on our card transactions page.

The list of parameters that can be included in a Sale request are as follows:

TIP
TIPPERC1, TIPPERC2, TIPPERC3
TIPAMT1, TIPAMT2, TIPAMT3
TIPCALC
TIPTHR
NOTIP
TIPGUIDE
TIPROUND

GetTipAmount renders three tipping amounts or percents on the payment terminal display.

The following example shows a sale that adds tip on the terminal to an individual transaction:

Json

{ 
  "operation": "Transaction", 
  "type": "SALE", 
  "requestedAmount": "1000", 
  "uniqueTransactionId": "ZswMQ1UVXz", 
  "parameters": [ 
    { 
      "key": "TIP", 
      "value": "1" 
    }, 
    { 
      "key": "TIPPERC1", 
      "value": "15000" 
    }, 
    { 
      "key": "TIPPERC2", 
      "value": "25000" 
    }, 
    { 
      "key": "TIPPERC3", 
      "value": "30000" 
    } 
  ] 
}

The following example is the response with tip added:

Json

{ 
   "AC": "A2713CD731C17D43", 
   "AID": "A0000000041010", 
   "ARC": "3030", 
   "IAD": "0110A04003240000000000000000000000FF", 
   "PARData": "50014Z7ANFG843M4NGU5H3H31M5N3", 
   "TSI": "E000", 
   "TVR": "0000008001", 
   "account": "540917******2610", 
   "accountType": "0", 
   "approval": "approved", 
   "approvalMode": "ISSUER", 
   "authCode": "067474", 
   "authorizedAmount": "1150", 
   "balance": "0", 
   "batchJulianDay": "246", 
   "batchNumber": "000001", 
   "cardBrand": "MASTERCARD", 
   "cardTypeProcessed": "1", 
   "cardholderLanguage": "en", 
   "cardholderReceipt": "\n         TEST STORE #123\n         213 Test Street\n      Testingvale, TN 12345\n          

(123) 456-7890\n\n\nMerc. ID: 9999999\nTerm. ID: 120\nRRN: 246144016405\nThu,Sep 03,2026         14:40:16\n\n              SALE\n\n            APPROVED\n\n      No Signature Required\n\n        ************2610\nMASTERCARD           Contactless\n\nAMOUNT                    $10.00\nTAX1                       $0.00\nTAX2                       $0.00\nSUBTOTAL                  $10.00\nTIP                        $1.50\n            ____________________\nTOTAL                     $11.50\n\nTransaction ID:\n                2460000011000001\nBatch#:                  246-001\nApproval Code:            067474\nCustomer Reference:\n                                \nCard Type:             Corporate\n\nBOI MASTERCARD\nAID: A0000000041010\n\n      *** Customer copy ***\n\n            Thank you\n        Please come again\n", 
   "cashbackAmount": "0", 
   "commercialCardType": "0", 
   "currencyCode": "USD", 
   "cvm": "NO CVM", 
   "dateTime": "09-03-2026 14:40:16", 
   "demoMode": "no", 
   "dueAmount": "0", 
   "emvTags":"...", "_comment": "Removed for brevity", 
   "entryMode": "Contactless", 
   "expDate": "3006", 
   "footerLine1": "Thank you", 
   "footerLine2": "Please come again", 
   "headerLine1": "TESTUPDATE", 
   "merchantID": "9999999", 
   "merchantReceipt": "\n         TEST STORE #123\n         213 Test Street\n      Testingvale, TN 12345\n          

(123) 456-7890\ n\n\nMerc. ID: 9999999\nTerm. ID: 120\nRRN: 246144016405\nThu,Sep 03,2026         14:40:16\n\n              SALE\n\n            APPROVED\n\n      No Signature Required\n\n        ************2610\nMASTERCARD           Contactless\n\nAMOUNT                    $10.00\nTAX1                       $0.00\nTAX2                       $0.00\nSUBTOTAL                  $10.00\nTIP                        $1.50\n            ____________________\nTOTAL                     $11.50\n\nTransaction ID:\n                2460000011000001\nBatch#:                  246-001\nApproval Code:            067474\nCustomer Reference:\n                                \nCard Type:             Corporate\n\nBOI MASTERCARD\nAID: A0000000041010\n\n      *** Merchant copy ***\n\n            Thank you\n        Please come again\n", 
   "operation": "Transaction", 
   "preferredName": "BOI MASTERCARD", 
   "reference": "246144016405", 
   "requestedAmount": "1000", 
   "responseCode": "00", 
   "result": "0", 
   "safState": "-1", 
   "safSubmissionState": "0", 
   "shift": "1", 
   "signatureRequired": "no", 
   "subTotalAmount": "1000", 
   "surchargeAmount": "0", 
   "surchargeFixed": "0", 
   "surchargePercentage": "0", 
   "table": "0", 
   "taxAmount": "0", 
   "taxAmount2": "0", 
   "taxLabel": "Tax1", 
   "taxLabel2": "Tax2", 
   "taxSurchargeAmount": "0", 
   "taxTotalAmount": "0", 
   "terminalID": "120", 
   "tipAmount": "150", 
   "totalAmount": "1150", 
   "transactionID": "2460000011000001", 
   "transactionType": "SALE", 
   "type": "SALE", 
   "uniqueTransactionId": "ZswMQ1UVXz" 
}

The following example is a request with tip turned off on the terminal prompting for the transaction:

Json

{ 
  "operation": "Transaction", 
  "type": "SALE", 
  "requestedAmount": "1000", 
  "uniqueTransactionId": "5M4qByQWgz", 
  "parameters": [ 
    { 
      "key": "TIP", 
      "value": "0" 
    } 
  ] 
}

The following example is a response with tip turned off:

Json

{ 
   "AC": "A8DA7499A579A568", 
   "AID": "A0000000041010", 
   "ARC": "3030", 
   "IAD": "0110A04003240000000000000000000000FF", 
   "PARData": "50014Z7ANFG843M4NGU5H3H31M5N3", 
   "TSI": "E000", 
   "TVR": "0000008001", 
   "account": "540917******2610", 
   "accountType": "0", 
   "approval": "approved", 
   "approvalMode": "ISSUER", 
   "authCode": "082018", 
   "authorizedAmount": "1100", 
   "balance": "0", 
   "batchJulianDay": "244", 
   "batchNumber": "000001", 
   "cardBrand": "MASTERCARD", 
   "cardTypeProcessed": "1", 
   "cardholderLanguage": "en", 
   "cardholderReceipt": "\n         TEST STORE #123\n         213 Test Street\n      Testingvale, TN 12345\n         (123) 456-7890\n\n\nMerc. ID: 9999999\nTerm. ID: 301\nRRN: 244111655595\nTue,Sep 01,2026         11:16:55\n\n              SALE\n\n            APPROVED\n\n      No Signature Required\n\n        ************2610\nMASTERCARD           Contactless\n\nAMOUNT                    $10.00\nSUBTOTAL                  $10.00\nTIP                        $1.00\n            ____________________\nTOTAL                     $11.00\n\nTransaction ID:\n                2440000011000018\nBatch#:                  244-001\nApproval Code:            082018\nCustomer Reference:\n                                \n\nBOI MASTERCARD\nAID: A0000000041010\n\n      *** Customer copy ***\n\n            Thank You\n        Please Come Again\n", 
   "cashbackAmount": "0", 
   "commercialCardType": "0", 
   "currencyCode": "CAD", 
   "cvm": "NO CVM", 
   "dateTime": "09-01-2026 11:16:55", 
   "dccBillingAmount": "1100", 
   "dccBillingCurrency": "CAD", 
   "dccExchangeRate": "0.6453", 
   "dccIndicator": "0", 
   "dccMarkup": "0", 
   "dccProvider": "FEXCO", 
   "demoMode": "no", 
   "dueAmount": "0", 
   "emvTags":"...", "_comment": "Removed for brevity", 
   "entryMode": "Contactless", 
   "expDate": "3006", 
   "headerLine1": "TEST STORE #123", 
   "headerLine3": "213 Test Street", 
   "headerLine5": "Testingvale, TN 12345", 
   "headerLine6": "(123) 456-7890", 
   "merchantID": "9999999", 
   "merchantReceipt": "\n         TEST STORE #123\n         213 Test Street\n      Testingvale, TN 12345\n         (123) 456-7890\n\n\nMerc. ID: 9999999\nTerm. ID: 301\nRRN: 244111655595\nTue,Sep 01,2026         11:16:55\n\n              SALE\n\n            APPROVED\n\n      No Signature Required\n\n        ************2610\nMASTERCARD           Contactless\n\nAMOUNT                    $10.00\nSUBTOTAL                  $10.00\nTIP                        $1.00\n            ____________________\nTOTAL                     $11.00\n\nTransaction ID:\n                2440000011000018\nBatch#:                  244-001\nApproval Code:            082018\nCustomer Reference:\n                                \n\nBOI MASTERCARD\nAID: A0000000041010\n\n      *** Merchant copy ***\n\n", 
   "operation": "Transaction", 
   "preferredName": "BOI MASTERCARD", 
   "reference": "244111655595", 
   "requestedAmount": "1000", 
   "responseCode": "00", 
   "result": "0", 
   "safState": "-1", 
   "safSubmissionState": "0", 
   "shift": "1", 
   "signatureRequired": "no", 
   "subTotalAmount": "1000", 
   "surchargeAmount": "0", 
   "surchargeFixed": "0", 
   "surchargePercentage": "0", 
   "table": "0", 
   "taxAmount": "0", 
   "taxAmount2": "0", 
   "taxLabel": "HST:", 
   "taxLabel2": "TAX2:", 
   "terminalID": "301", 
   "tipAmount": "100", 
   "totalAmount": "1100", 
   "transactionID": "2440000011000018", 
   "transactionType": "SALE", 
   "type": "SALE", 
   "uniqueTransactionId": "5M4qByQWgz" 
}