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.
You can adjust the amount to tip on from software versions 1.103 and later.
-
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.
Operation objectExpand viewCopy link to code blockCopy code{ "Operation":[ { "Type":"Payment", "TipOptions":{ "AmountToTipOn": 15.00, "TipSuggestions":{ "Percentage1":15, "Percentage2":18, "Percentage3":20, "TipCustom":true } } } ] } -
Encode the
Operation
JSON object to Base64. You will pass the resulting string inSaleData.SaleToPOIData
. The example below shows a Base64-encoded string of theOperation
object format.Converted to a Base64-encoded stringExpand viewCopy link to code blockCopy codeICAgICB7CiAgICAgICAgICJPcGVyYXRpb24iOlsKICAgICAgICAgICAgIHsKICAgICAgICAgICAgICAgICAiVHlwZSI6IlBheW1lbnQiLAogICAgICAgICAgICAgICAgICJUaXBPcHRpb25zIjp7CiAgICAgICAgICAgICAgICAgICAgICJBbW91bnRUb1RpcE9uIjogMTUuMDAsCiAgICAgICAgICAgICAgICAgICAgICJUaXBTdWdnZXN0aW9ucyI6ewogICAgICAgICAgICAgICAgICAgICAgICAgIlBlcmNlbnRhZ2UxIjoxNSwKICAgICAgICAgICAgICAgICAgICAgICAgICJQZXJjZW50YWdlMiI6MTgsCiAgICAgICAgICAgICAgICAgICAgICAgICAiUGVyY2VudGFnZTMiOjIwLAogICAgICAgICAgICAgICAgICAgICAgICAgIlRpcEN1c3RvbSI6dHJ1ZQogICAgICAgICAgICAgICAgICAgICB9CiAgICAgICAgICAgICAgICAgfQogICAgICAgICAgICAgfSAKICAgICAgICAgXQogICAgIH0g
-
Make a
PaymentRequest
with:-
MessageHeader
: the standardSaleToPOIRequest.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.
Payment requestExpand viewCopy link to code blockCopy code{ "SaleToPOIRequest":{ "MessageHeader":{ "ProtocolVersion":"3.0", "MessageClass":"Service", "MessageCategory":"Payment", "MessageType":"Request", "SaleID":"POSSystemID12345", "ServiceID":"0207111104", "POIID":"P400Plus-275688710" }, "PaymentRequest":{ "SaleData":{ "SaleToAcquirerData": "tenderOption=AskGratuity", "SaleTransactionID":{ "TransactionID":"27908", "TimeStamp":"2019-12-17T10:11:03.000Z" }, "SaleToPOIData": "ICAgICB7CiAgICAgICAgICJPcGVyYXRpb24iOlsKICAgICAgICAgICAgIHsKICAgICAgICAgICAgICAgICAiVHlwZSI6IlBheW1lbnQiLAogICAgICAgICAgICAgICAgICJUaXBPcHRpb25zIjp7CiAgICAgICAgICAgICAgICAgICAgICJBbW91bnRUb1RpcE9uIjogMTUuMDAsCiAgICAgICAgICAgICAgICAgICAgICJUaXBTdWdnZXN0aW9ucyI6ewogICAgICAgICAgICAgICAgICAgICAgICAgIlBlcmNlbnRhZ2UxIjoxNSwKICAgICAgICAgICAgICAgICAgICAgICAgICJQZXJjZW50YWdlMiI6MTgsCiAgICAgICAgICAgICAgICAgICAgICAgICAiUGVyY2VudGFnZTMiOjIwLAogICAgICAgICAgICAgICAgICAgICAgICAgIlRpcEN1c3RvbSI6dHJ1ZQogICAgICAgICAgICAgICAgICAgICB9CiAgICAgICAgICAgICAgICAgfQogICAgICAgICAgICAgfSAKICAgICAgICAgXQogICAgIH0g" }, "PaymentTransaction":{ "AmountsReq":{ "Currency":"EUR", "RequestedAmount":20.00 } } } } } -
-
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.
Payment responseExpand viewCopy link to code blockCopy code{ "SaleToPOIResponse":{ "MessageHeader":{...}, "PaymentResponse":{ "POIData":{ "POIReconciliationID":"1000", "POITransactionID":{ "TimeStamp":"2024-04-16T09:12:45.865Z", "TransactionID":"u6W7001529672124004.NC6HT9CRT65ZGN82" } }, "PaymentReceipt":[...], "PaymentResult":{ "AmountsResp":{ "AuthorizedAmount":22.25, "Currency":"EUR", "TipAmount":2.25 }, "OnlineFlag":true, "PaymentAcquirerData":{ "AcquirerPOIID":"V400m-324688179", "AcquirerTransactionID":{ "TimeStamp":"2024-04-16T09:12:45.865Z", "TransactionID":"NC6HT9CRT65ZGN82" }, "ApprovalCode":"123456", "MerchantID":"TestMerchantPOS" }, "PaymentInstrumentData":{...} }, "Response":{ "...posAmountGratuityValue=225&posAuthAmountCurrency=EUR&posAuthAmountValue=2225&posEntryMode=CLESS_CHIP&posOriginalAmountValue=2000&posadditionalamounts.gratuityAmount=225&posadditionalamounts.originalAmountCurrency=EUR&posadditionalamounts.originalAmountValue=2000&...", "Result":"Success" }, "SaleData":{ "SaleTransactionID":{ "TimeStamp":"2024-04-16T09:12:44.892Z", "TransactionID":"181" } } } } } -