Override configured tipping options

If you have defined default tipping options in your Customer Area, you may want to present different tipping options depending on the type of goods or services that a shopper buys. For example, if a shopper buys a cup of coffee, percentage-based tipping results 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 shows the new tipping options on the terminal screen during the payment flow. However, you need to implement logic in your system when to trigger the override, such as logic to offer fixed amount options instead of percentages if the total amount is low.

Requirements

Before you begin, take into account the following requirements and preparations.

Tipping options

You can present your customer with either three percentage options or three tipping amount options. Additionally, you can enable the flag to present a Custom tip option. The No tip option is always included.

Specify tipping options in the payment request

To override the configured tipping options, in the payment request you need to include the AskGratuity tender option and a Base64-encoded Operation object with the new tipping options.

1. Create an Operation JSON object. Select the tab for the software version that your terminal is using.

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 for software version V1.101 and later.

3. Make a PaymentRequest with:

   • The standard SaleToPOIRequest.MessageHeader object, with MessageClass set to Service and MessageCategory set to Payment.

     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 Specify tender options.
     SaleData.SaleToPOIData	An object with the Base64-encoded Operation string that contains the new 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: the amount of the tip. If the customer didn't add a tip, this field is not included.
     • AuthorizedAmount: the total authorized amount of the transaction, consisting of the original purchase amount plus the tip amount.
     • Currency: the 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 20 percent tip added.

See also