Override the amount to tip on

When a customer buys a mix of products and services, you can let them add a tip to an amount that is different from the total purchase amount. For example, if the total amount consists of the costs of a haircut and a hair product, you can let the shopper add a tip only for the cost of having the haircut. This is convenient if the customer wants to add a tip as a percentage of the cost of the service they received, and not the total amount.

You can specify the original amount in the payment request and exclude product-related charges, taxes, or other fees. The terminal will present the customer with the adjusted amount before adding the tip.

Make a payment request with the adjusted tipping amount

To trigger the payment terminal to ask the customer for a tip, you need to make a payment request with the AskGratuity tender option and include a base-64 encoded Operation object with the AmountToTipOn parameter.

1. Create an Operation JSON object with the following parameters:

   Parameter	Description
   Type	Payment
   AmountToTipOn	The amount that the customer can tip on.
   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.

3. Make a PaymentRequest with:

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

     Parameter	Required	Description
     ProtocolVersion		3.0
     MessageClass		Service
     MessageCategory		Payment
     MessageType		Request
     ServiceID		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		Your unique ID for the POS system component to send this request from.
     POIID		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 initiate a transaction with an adjusted amount to tip on.

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 with an adjusted amount of EUR 15.00 with a 15 percent tip added.

See also