Point-of-sale icon

Override existing tipping options

Offer shoppers tipping options on the terminal to match different tipping scenarios.

Depending on the type of goods or services that a shopper buys, you may want to present them with different tipping options. For example, if a shopper buys a coffee, percentage-based tipping will result in a lower tip for your staff than predefined fixed amounts.

You can override the settings defined in your Customer Area by specifying the tipping options in the payment request. This will present the shopper with different tipping options on the terminal. However, you need to implement logic in your system when to trigger the override. For example, you may want to offer predefined fixed amount options instead of percentages if the total amount is low.

You can present your customer with either:

  • Three predefined percentage options.
  • Three predefined tipping amount options.

Additionally, you can enable the flag to present a Custom tip option. The No tip option is always included.

Make a payment to override existing tipping options

To trigger the payment terminal to ask the customer for a tip amount or a total amount, you need to make a payment request with the AskGratuity tender option. The payment requests also needs to contain a base-64 encoded Operation object with the predefined tipping options.

Software versions 1.97 to 1.100 use an outdated Operation object format. Choose the correct version tab in Step 1.

  1. Create an Operation JSON object in the format that your software version supports with the following parameters:

    Parameter Description
    Type Payment
    TipOptions Contains the TipSuggestions object with:
    • up to three predefined tipping options for either a fixed tipping amount (Amount1, Amount2, and Amount3) or a percentage of the original payment amount (Percentage1, Percentage2, and Percentage3). The numeric value for percentage tipping options must not be greater than 100.
    • TipCustom (optional): allows shopper to place a custom tipping amount. Value true or false.

  2. Encode the Operation JSON object to Base64. You will pass the resulting string in SaleData.SaleToPOIData. The example below shows a Base64-encoded string of the Operation object format for software version V1.101 and later.

  3. Make a PaymentRequest with:

    • MessageHeader: the standard SaleToPOIRequest.MessageHeader object. Specify:

      Parameter Required Description
      ProtocolVersion -white_check_mark- 3.0
      MessageClass -white_check_mark- Service
      MessageCategory -white_check_mark- Payment
      MessageType -white_check_mark- Request
      ServiceID -white_check_mark- Your unique ID for this request, consisting of 1-10 alphanumeric characters. Must be unique within the last 48 hours for the terminal (POIID) being used.
      SaleID -white_check_mark- Your unique ID for the POS system component to send this request from.
      POIID -white_check_mark- The unique ID of the terminal to send this request to. Format: [device model]-[serial number].

    • PaymentRequest: the request body. This includes:

      Parameter Description
      SaleData.SaleToAcquirerData The AskGratuity tender option that triggers the terminal to start the tipping flow.

      See the Specify tender options.
      SaleData.SaleToPOIData An object with the Base64-encoded Operation string that contains the tipping options.
      PaymentTransaction.AmountsReq An object with:
      • Currency: The transaction currency.
      • RequestedAmount: The purchase amount, with decimals.

    The example below shows how to present tipping options and initiate a transaction of EUR 10.00.

  4. In the PaymentResponse note the following:

    • PaymentReceipt: receipt data with the original purchase amount, the gratuity amount, and the total amount. If the customer didn't add a tip, the gratuity amount is not included.

    • PaymentResult.AmountsResp:

      • TipAmount: amount of the tip. If the customer didn't add a tip, this field is not included.
      • AuthorizedAmount: total authorized amount of the transaction: The original purchase amount plus the tip amount.
      • Currency: currency of the payment.

    • Response.AdditionalResponse: additional transaction data. Depending on your settings, you receive either a string of form-encoded key-value pairs or a Base64 string that you need to decode to get a JSON object. This includes:

      • posadditionalamounts.originalAmountValue: the original purchase amount in minor units.
      • posAmountGratuityValue: the tip amount in minor units.
      • authorisedAmountValue: the total authorized amount in minor units.

    The example below shows the response for a transaction of EUR 10.00 with a 10 percent tip added.

See also